HashMap.h revision 4a68b3365c8c50aa93505e99ead2565ab73dcdb0 
1/*---------------------------------------------------------------------------*
2 *  HashMap.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef __HASHMAP_H
21#define __HASHMAP_H
22
23
24
25#include "ESR_ReturnCode.h"
26#include "ESR_SharedPrefix.h"
27#include "ptypes.h"
28#include <stdlib.h>
29
30
31/**
32 * @addtogroup HashMapModule HashMap API functions
33 * Hashed [key, value] mapping.
34 *
35 * @{
36 */
37
38/**
39 * Hashed [key, value] mapping.
40 */
41typedef struct HashMap_t
42{
43  /**
44   * Sets new mapping, storing a reference to the value.
45   * The key can be safely deallocated after this operation.
46   *
47   * @param self HashMap handle
48   * @param key Mapping key
49   * @param value Mapping value
50   * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
51   */
52  ESR_ReturnCode(*put)(struct HashMap_t* self, const LCHAR* key, void* value);
53
54  /**
55   * Removes the mapping for this key from this map if present.
56   *
57   * @param self HashMap handle
58   * @param key Key whose mapping is to be removed from the map.
59   * @return ESR_INVALID_ARGUMENT if self is null
60   */
61  ESR_ReturnCode(*remove)(struct HashMap_t* self, const LCHAR* key);
62
63  /**
64   * Removes the mapping for this key from this map if present and frees the value.
65   *
66   * @param self HashMap handle
67   * @param key Key whose mapping is to be removed from the map.
68    * @return ESR_INVALID_ARGUMENT if self is null
69   */
70  ESR_ReturnCode(*removeAndFree)(struct HashMap_t* self, const LCHAR* key);
71
72  /**
73   * Removes the mappings for the key at the specified index.
74   *
75   * @param self HashMap handle
76   * @param index Index of element to be removed
77   * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
78   */
79  ESR_ReturnCode(*removeAtIndex)(struct HashMap_t* self, const size_t index);
80
81  /**
82   * Removes all mappings from this map.
83   *
84   * @param self HashMap handle
85   * @return ESR_INVALID_ARGUMENT if self is null
86   */
87  ESR_ReturnCode(*removeAll)(struct HashMap_t* self);
88
89  /**
90   * Removes all mappings from this map and frees the values.
91   *
92   * @param self HashMap handle
93   * @return ESR_INVALID_ARGUMENT if self is null
94   */
95  ESR_ReturnCode(*removeAndFreeAll)(struct HashMap_t* self);
96
97  /**
98   * Indicates if element is contained within the list.
99   *
100   * @param self HashMap handle
101   * @param key Key to check for
102   * @param exists True if key was found
103   * @return ESR_INVALID_ARGUMENT if self is null
104   */
105  ESR_ReturnCode(*containsKey)(struct HashMap_t* self, const LCHAR* key, ESR_BOOL* exists);
106
107  /**
108   * Returns the number of mappings contained in this map.
109   *
110   * @param self HashMap handle
111   * @param size Returned size
112   * @return ESR_INVALID_ARGUMENT if self is null
113   */
114  ESR_ReturnCode(*getSize)(struct HashMap_t* self, size_t* size);
115
116  /**
117   * Returns the value to which the specified key is mapped in this identity hash map,
118   * or null if the map contains no mapping for this key.
119   *
120   * @param self HashMap handle
121   * @param key the key whose associated value is to be returned.
122   * @param value the value to which this map maps the specified key, or null if the
123   *              map contains no mapping for this key.
124   * @return ESR_INVALID_ARGUMENT if self is null; ESR_NO_MATCH_ERROR if key cannot be found
125   */
126  ESR_ReturnCode(*get)(struct HashMap_t* self, const LCHAR* key, void** value);
127  /**
128   * Returns the key at the specified index.
129   *
130   * @param self HashMap handle
131   * @param index the key index
132   * @param key the key at the specified index
133   * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
134   */
135  ESR_ReturnCode(*getKeyAtIndex)(struct HashMap_t* self, const size_t index, LCHAR** key);
136  /**
137   * Returns the value at the specified index.
138   *
139   * @param self HashMap handle
140   * @param index the key index
141   * @param value the value at the specified index
142   * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
143   */
144  ESR_ReturnCode(*getValueAtIndex)(struct HashMap_t* self, const size_t index, void** value);
145  /**
146   * Destroys the HashMap.
147   *
148   * @param self HashMap handle
149   * @return ESR_INVALID_ARGUMENT if self is null
150   */
151  ESR_ReturnCode(*destroy)(struct HashMap_t* self);
152}
153HashMap;
154
155/**
156 * Creates a new HashMap.
157 *
158 * @param self HashMap handle
159 * @return ESR_INVALID_ARGUMENT if self or the value it points to are null
160 */
161ESR_SHARED_API ESR_ReturnCode HashMapCreate(HashMap** self);
162/**
163 * Creates a new HashMap.
164 *
165 * @param bins The number of hashing bins to be used.
166 * @param self HashMap handle
167 * @return ESR_INVALID_ARGUMENT if self or the value it points to are null
168 */
169ESR_SHARED_API ESR_ReturnCode HashMapCreateBins(size_t nbBins, HashMap** self);
170/**
171 * Sets new mapping, storing a reference to the value.
172 * The key can be safely deallocated after this operation.
173 *
174 * @param self HashMap handle
175 * @param key Mapping key
176 * @param value Mapping value
177 * @return ESR_INVALID_ARGUMENT if self is null; ESR_OUT_OF_MEMORY if system is out of memory
178 */
179ESR_SHARED_API ESR_ReturnCode HashMapPut(HashMap* self, const LCHAR* key, void* value);
180/**
181 * Removes the mapping for this key from this map if present.
182 * The value can be safely deallocated after this operation.
183 * If the map previously contained a mapping for this key, the old value is replaced,
184 * but not deallocated.
185 *
186 * @param self HashMap handle
187 * @param key Key whose mapping is to be removed from the map.
188 * @return ESR_INVALID_ARGUMENT if self is null
189 */
190ESR_SHARED_API ESR_ReturnCode HashMapRemove(HashMap* self, const LCHAR* key);
191/**
192 * Removes the mapping for this key from this map if present and frees the value.
193 * The value can be safely deallocated after this operation.
194 *
195 * @param self HashMap handle
196 * @param key Key whose mapping is to be removed from the map.
197 * @return ESR_INVALID_ARGUMENT if self is null
198 */
199ESR_SHARED_API ESR_ReturnCode HashMapRemoveAndFree(HashMap* self, const LCHAR* key);
200/**
201 * Removes the mappings for the key at the specified index.
202 *
203 * @param self HashMap handle
204 * @param index Index of element to be removed
205 * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
206 */
207ESR_SHARED_API ESR_ReturnCode HashMapRemoveAtIndex(HashMap* self, const size_t index);
208/**
209 * Removes all mappings from this map.
210 *
211 * @param self HashMap handle
212 * @return ESR_INVALID_ARGUMENT if self is null
213 */
214ESR_SHARED_API ESR_ReturnCode HashMapRemoveAll(HashMap* self);
215/**
216 * Removes all mappings from this map and frees the values.
217 *
218 * @param self HashMap handle
219 * @return ESR_INVALID_ARGUMENT if self is null
220 */
221ESR_SHARED_API ESR_ReturnCode HashMapRemoveAndFreeAll(HashMap* self);
222/**
223 * Indicates if element is contained within the list.
224 *
225 * @param self HashMap handle
226 * @param key Key to check for
227 * @param exists True if key was found
228 * @return ESR_INVALID_ARGUMENT if self is null
229 */
230ESR_SHARED_API ESR_ReturnCode HashMapContainsKey(HashMap* self, const LCHAR* key, ESR_BOOL* exists);
231/**
232 * Returns the number of mappings contained in this map.
233 *
234 * @param self HashMap handle
235 * @param size Returned size
236 * @return ESR_INVALID_ARGUMENT if self is null
237 */
238ESR_SHARED_API ESR_ReturnCode HashMapGetSize(HashMap* self, size_t* size);
239/**
240 * Returns the value to which the specified key is mapped in this identity hash map,
241 * or null if the map contains no mapping for this key.
242 *
243 * @param self HashMap handle
244 * @param key the key whose associated value is to be returned.
245 * @param value the value to which this map maps the specified key, or null if the
246 *              map contains no mapping for this key.
247 * @return ESR_INVALID_ARGUMENT if self is null; ESR_NO_MATCH_ERROR if key cannot be found
248 */
249ESR_SHARED_API ESR_ReturnCode HashMapGet(HashMap* self, const LCHAR* key, void** value);
250/**
251 * Returns the key at the specified index.
252 *
253 * @param self HashMap handle
254 * @param index the key index
255 * @param key the key at the specified index
256 * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
257 */
258ESR_SHARED_API ESR_ReturnCode HashMapGetKeyAtIndex(HashMap* self, const size_t index, LCHAR** key);
259/**
260 * Returns the value at the specified index.
261 *
262 * @param self HashMap handle
263 * @param index the key index
264 * @param value the key at the specified index
265 * @return ESR_INVALID_ARGUMENT if self is null; ESR_ARGUMENT_OUT_OF_BOUNDS if index is out of bounds
266 */
267ESR_SHARED_API ESR_ReturnCode HashMapGetValueAtIndex(HashMap* self, const size_t index, void** value);
268/**
269 * Destroys an HashMap.
270 *
271 * @param self HashMap handle
272 * @return ESR_INVALID_ARGUMENT if self is null
273 */
274ESR_SHARED_API ESR_ReturnCode HashMapDestroy(HashMap* self);
275
276/**
277 * @}
278 */
279
280
281#endif /* __HASHMAP_H */
282