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