1 /* 2 * Copyright (C) 2007 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * Hash map. 19 * 20 * Use std::map or std::unordered_map instead. 21 * https://en.cppreference.com/w/cpp/container 22 */ 23 24 #ifndef __HASHMAP_H 25 #define __HASHMAP_H 26 27 #include <stdbool.h> 28 #include <stdlib.h> 29 30 #ifdef __cplusplus 31 extern "C" { 32 #endif 33 34 /** A hash map. */ 35 typedef struct Hashmap Hashmap; 36 37 /** 38 * Creates a new hash map. Returns NULL if memory allocation fails. 39 * 40 * @param initialCapacity number of expected entries 41 * @param hash function which hashes keys 42 * @param equals function which compares keys for equality 43 */ 44 Hashmap* hashmapCreate(size_t initialCapacity, 45 int (*hash)(void* key), bool (*equals)(void* keyA, void* keyB)); 46 47 /** 48 * Frees the hash map. Does not free the keys or values themselves. 49 */ 50 void hashmapFree(Hashmap* map); 51 52 /** 53 * Hashes the memory pointed to by key with the given size. Useful for 54 * implementing hash functions. 55 */ 56 int hashmapHash(void* key, size_t keySize); 57 58 /** 59 * Puts value for the given key in the map. Returns pre-existing value if 60 * any. 61 * 62 * If memory allocation fails, this function returns NULL, the map's size 63 * does not increase, and errno is set to ENOMEM. 64 */ 65 void* hashmapPut(Hashmap* map, void* key, void* value); 66 67 /** 68 * Gets a value from the map. Returns NULL if no entry for the given key is 69 * found or if the value itself is NULL. 70 */ 71 void* hashmapGet(Hashmap* map, void* key); 72 73 /** 74 * Removes an entry from the map. Returns the removed value or NULL if no 75 * entry was present. 76 */ 77 void* hashmapRemove(Hashmap* map, void* key); 78 79 /** 80 * Invokes the given callback on each entry in the map. Stops iterating if 81 * the callback returns false. 82 */ 83 void hashmapForEach(Hashmap* map, bool (*callback)(void* key, void* value, void* context), 84 void* context); 85 86 /** 87 * Concurrency support. 88 */ 89 90 /** 91 * Locks the hash map so only the current thread can access it. 92 */ 93 void hashmapLock(Hashmap* map); 94 95 /** 96 * Unlocks the hash map so other threads can access it. 97 */ 98 void hashmapUnlock(Hashmap* map); 99 100 #ifdef __cplusplus 101 } 102 #endif 103 104 #endif /* __HASHMAP_H */ 105