All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_hashmap.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <aerospike/as_map.h>
26 
27 #include <stdbool.h>
28 #include <stdint.h>
29 
30 /******************************************************************************
31  * TYPES
32  ******************************************************************************/
33 
34 /**
35  * A hashtable based implementation of `as_map`.
36  *
37  * To use the map, you can either initialize a stack allocated map,
38  * using `as_hashmap_init()`:
39  *
40  * ~~~~~~~~~~{.c}
41  * as_hashmap map;
42  * as_hashmap_init(&map, 32);
43  * ~~~~~~~~~~
44  *
45  * Or you can create a new heap allocated map using
46  * `as_hashmap_new()`:
47  *
48  * ~~~~~~~~~~{.c}
49  * as_hashmap * map = as_hashmap_new(32);
50  * ~~~~~~~~~~
51  *
52  * When you are finished using the map, then you should release the
53  * map and associated resources, using `as_hashmap_destroy()`:
54  *
55  * ~~~~~~~~~~{.c}
56  * as_hashmap_destroy(list);
57  * ~~~~~~~~~~
58  *
59  *
60  * The `as_hashmap` is a subtype of `as_map`. This allows you to alternatively
61  * use `as_map` functions, by typecasting `as_hashmap` to `as_map`.
62  *
63  * ~~~~~~~~~~{.c}
64  * as_hashmap map;
65  * as_map * l = (as_list *) as_hashmap_init(&map, 32);
66  * as_stringmap_set_int64(l, "a", 1);
67  * as_stringmap_set_int64(l, "b", 2);
68  * as_stringmap_set_int64(l, "c", 3);
69  * as_map_destroy(l);
70  * ~~~~~~~~~~
71  *
72  * The `as_stringmap` functions are simplified functions for using string key.
73  *
74  * Each of the `as_map` functions proxy to the `as_hashmap` functions.
75  * So, calling `as_map_destroy()` is equivalent to calling
76  * `as_hashmap_destroy()`.
77  *
78  * @extends as_map
79  * @ingroup aerospike_t
80  */
81 typedef struct as_hashmap_s {
82 
83  /**
84  * @private
85  * as_hashmap is an as_map.
86  * You can cast as_hashmap to as_map.
87  */
89 
90  /**
91  * Hashtable
92  */
93  void * htable;
94 
95 } as_hashmap;
96 
97 /*******************************************************************************
98  * INSTANCE FUNCTIONS
99  ******************************************************************************/
100 
101 /**
102  * Initialize a stack allocated hashmap.
103  *
104  * @param map The map to initialize.
105  * @param buckets The number of hash buckets to allocate.
106  *
107  * @return On success, the initialized map. Otherwise NULL.
108  *
109  * @relatesalso as_hashmap
110  */
111 as_hashmap * as_hashmap_init(as_hashmap * map, uint32_t buckets);
112 
113 /**
114  * Creates a new map as a hashmap.
115  *
116  * @param buckets The number of hash buckets to allocate.
117  *
118  * @return On success, the new map. Otherwise NULL.
119  *
120  * @relatesalso as_hashmap
121  */
122 as_hashmap * as_hashmap_new(uint32_t buckets);
123 
124 /**
125  * Free the map and associated resources.
126  *
127  * @param map The map to destroy.
128  *
129  * @relatesalso as_hashmap
130  */
131 void as_hashmap_destroy(as_hashmap * map);
132 
133 /*******************************************************************************
134  * INFO FUNCTIONS
135  ******************************************************************************/
136 
137 /**
138  * The hash value of the map.
139  *
140  * @param map The list.
141  *
142  * @return The hash value of the list.
143  *
144  * @relatesalso as_hashmap
145  */
146 uint32_t as_hashmap_hashcode(const as_hashmap * map);
147 
148 /**
149  * Get the number of entries in the map.
150  *
151  * @param map The map.
152  *
153  * @return The number of entries in the map.
154  *
155  * @relatesalso as_hashmap
156  */
157 uint32_t as_hashmap_size(const as_hashmap * map);
158 
159 /*******************************************************************************
160  * ACCESSOR AND MODIFIER FUNCTIONS
161  ******************************************************************************/
162 
163 /**
164  * Get the value for specified key.
165  *
166  * @param map The map.
167  * @param key The key.
168  *
169  * @return The value for the specified key. Otherwise NULL.
170  *
171  * @relatesalso as_hashmap
172  */
173 as_val * as_hashmap_get(const as_hashmap * map, const as_val * key);
174 
175 /**
176  * Set the value for specified key.
177  *
178  * @param map The map.
179  * @param key The key.
180  * @param val The value for the given key.
181  *
182  * @return 0 on success. Otherwise an error occurred.
183  *
184  * @relatesalso as_hashmap
185  */
186 int as_hashmap_set(as_hashmap * map, const as_val * key, const as_val * val);
187 
188 /**
189  * Remove all entries from the map.
190  *
191  * @param map The map.
192  *
193  * @return 0 on success. Otherwise an error occurred.
194  *
195  * @relatesalso as_hashmap
196  */
197 int as_hashmap_clear(as_hashmap * map);
198 
199 /**
200  * Remove the entry specified by the key.
201  *
202  * @param map The map to remove the entry from.
203  * @param key The key of the entry to be removed.
204  *
205  * @return 0 on success. Otherwise an error occurred.
206  *
207  * @relatesalso as_hashmap
208  */
209 int as_hashmap_remove(as_hashmap * map, const as_val * key);
210 
211 /******************************************************************************
212  * ITERATION FUNCTIONS
213  *****************************************************************************/
214 
215 /**
216  * Call the callback function for each entry in the map.
217  *
218  * @param map The map.
219  * @param callback The function to call for each entry.
220  * @param udata User-data to be passed to the callback.
221  *
222  * @return true if iteration completes fully. false if iteration was aborted.
223  *
224  * @relatesalso as_hashmap
225  */
226 bool as_hashmap_foreach(const as_hashmap * map, as_map_foreach_callback callback, void * udata);