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 */ 41 typedef 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 } 153 HashMap; 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 */ 161 ESR_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 */ 169 ESR_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 */ 179 ESR_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 */ 190 ESR_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 */ 199 ESR_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 */ 207 ESR_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 */ 214 ESR_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 */ 221 ESR_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 */ 230 ESR_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 */ 238 ESR_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 */ 249 ESR_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 */ 258 ESR_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 */ 267 ESR_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 */ 274 ESR_SHARED_API ESR_ReturnCode HashMapDestroy(HashMap* self); 275 276 /** 277 * @} 278 */ 279 280 281 #endif /* __HASHMAP_H */ 282