All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_map.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_iterator.h>
26 #include <aerospike/as_util.h>
27 #include <aerospike/as_val.h>
28 
29 #include <stdbool.h>
30 #include <stdint.h>
31 
32 /******************************************************************************
33  * TYPES
34  *****************************************************************************/
35 
36 union as_map_iterator_u;
37 
38 struct as_map_hooks_s;
39 
40 /**
41  * Callback function for `as_map_foreach()`. Called for each entry in the
42  * map.
43  *
44  * @param key The key of the current entry.
45  * @param value The value of the current entry.
46  * @param udata The user-data provided to the `as_list_foreach()`.
47  *
48  * @return true to continue iterating through the list.
49  * false to stop iterating.
50  */
51 typedef bool (* as_map_foreach_callback) (const as_val * key, const as_val * value, void * udata);
52 
53 /**
54  * as_map is an interface for Map based data types.
55  *
56  * Implementations:
57  * - as_hashmap
58  *
59  * @extends as_val
60  * @ingroup aerospike_t
61  */
62 typedef struct as_map_s {
63 
64  /**
65  * @private
66  * as_map is a subtype of as_val.
67  * You can cast as_map to as_val.
68  */
70 
71  /**
72  * Pointer to the data for this list.
73  */
74  void * data;
75 
76  /**
77  * Hooks for sybtypes of as_list to implement.
78  */
79  const struct as_map_hooks_s * hooks;
80 
81 } as_map;
82 
83 /**
84  * Map Function Hooks
85  */
86 typedef struct as_map_hooks_s {
87 
88  /***************************************************************************
89  * instance hooks
90  **************************************************************************/
91 
92  /**
93  * Releases the subtype of as_map.
94  *
95  * @param map The map instance to destroy.
96  *
97  * @return true on success. Otherwise false.
98  */
99  bool (* destroy)(as_map * map);
100 
101  /***************************************************************************
102  * info hooks
103  **************************************************************************/
104 
105  /**
106  * The hash value of an as_map.
107  *
108  * @param map The map to get the hashcode value for.
109  *
110  * @return The hashcode value.
111  */
112  uint32_t (* hashcode)(const as_map * map);
113 
114  /**
115  * The size of the as_map.
116  *
117  * @param map The map to get the size of.
118  *
119  * @return The number of entries in the map.
120  */
121  uint32_t (* size)(const as_map * map);
122 
123  /***************************************************************************
124  * accessor and modifier hooks
125  **************************************************************************/
126 
127  /**
128  * Set a value of the given key in a map.
129  *
130  * @param map The map to store the (key,value) pair.
131  * @param key The key for the given value.
132  * @param val The value for the given key.
133  *
134  * @return 0 on success. Otherwise an error occurred.
135  */
136  int (* set)(as_map * map, const as_val * key, const as_val * val);
137 
138  /**
139  * Set a value at the given key of the map.
140  *
141  * @param map The map to containing the (key,value) pair.
142  * @param key The key of the value.
143  *
144  * @return The value on success. Otherwise NULL.
145  */
146  as_val * (* get)(const as_map * map, const as_val * key);
147 
148  /**
149  * Clear all entries of the map.
150  *
151  * @param map The map to clear.
152  *
153  * @return 0 on success. Otherwise an error occurred.
154  */
155  int (* clear)(as_map * map);
156 
157  /**
158  * Remove the entry specified by the key.
159  *
160  * @param map The map to remove the entry from.
161  * @param key The key of the entry to be removed.
162  *
163  * @return 0 on success. Otherwise an error occurred.
164  */
165  int (* remove)(as_map * map, const as_val * key);
166 
167  /***************************************************************************
168  * iteration hooks
169  **************************************************************************/
170 
171  /**
172  * Iterate over each entry in the map can call the callback function.
173  *
174  * @param map The map to iterate.
175  * @param callback The function to call for each entry in the map.
176  * @param udata User-data to be passed to the callback.
177  *
178  * @return true on success. Otherwise false.
179  */
180  bool (* foreach)(const as_map * map, as_map_foreach_callback callback, void * udata);
181 
182  /**
183  * Create and initialize a new heap allocated iterator to traverse over the entries map.
184  *
185  * @param map The map to iterate.
186  *
187  * @return true on success. Otherwise false.
188  */
189  union as_map_iterator_u * (* iterator_new)(const as_map * map);
190 
191  /**
192  * Initialize a stack allocated iterator to traverse over the entries map.
193  *
194  * @param map The map to iterate.
195  *
196  * @return true on success. Otherwise false.
197  */
198  union as_map_iterator_u * (* iterator_init)(const as_map * map, union as_map_iterator_u * it);
199 
200 } as_map_hooks;
201 
202 /******************************************************************************
203  * INSTANCE FUNCTIONS
204  *****************************************************************************/
205 
206 /**
207  * @private
208  * Utilized by subtypes of as_map to initialize the parent.
209  *
210  * @param map The map to initialize
211  * @param free If TRUE, then as_map_destory() will free the map.
212  * @param data Data for the map.
213  * @param hooks Implementaton for the map interface.
214  *
215  * @return The initialized as_map on success. Otherwise NULL.
216  * @relatesalso as_map
217  */
218 as_map * as_map_cons(as_map * map, bool free, void * data, const as_map_hooks * hooks);
219 
220 /**
221  * Initialize a stack allocated map.
222  *
223  * @param map Stack allocated map to initialize.
224  * @param data Data for the map.
225  * @param hooks Implementation for the map interface.
226  *
227  * @return On success, the initialized map. Otherwise NULL.
228  * @relatesalso as_map
229  */
230 as_map * as_map_init(as_map * map, void * data, const as_map_hooks * hooks);
231 
232 /**
233  * Create and initialize a new heap allocated map.
234  *
235  * @param data Data for the list.
236  * @param hooks Implementation for the list interface.
237  *
238  * @return On success, a new list. Otherwise NULL.
239  * @relatesalso as_map
240  */
241 as_map * as_map_new(void * data, const as_map_hooks * hooks);
242 
243 /**
244  * Destroy the as_map and associated resources.
245  * @relatesalso as_map
246  */
247 inline void as_map_destroy(as_map * map)
248 {
249  as_val_destroy((as_val *) map);
250 }
251 
252 /*******************************************************************************
253  * INFO FUNCTIONS
254  ******************************************************************************/
255 
256 /**
257  * Hash value for the map
258  *
259  * @param map The map
260  *
261  * @return The hashcode value of the map.
262  * @relatesalso as_map
263  */
264 inline uint32_t as_map_hashcode(const as_map * map)
265 {
266  return as_util_hook(hashcode, 0, map);
267 }
268 
269 /**
270  * Get the number of entries in the map.
271  *
272  * @param map The map
273  *
274  * @return The size of the map.
275  * @relatesalso as_map
276  */
277 inline uint32_t as_map_size(const as_map * map)
278 {
279  return as_util_hook(size, 0, map);
280 }
281 
282 /*******************************************************************************
283  * ACCESSOR AND MODIFIER FUNCTIONS
284  ******************************************************************************/
285 
286 /**
287  * Get the value for specified key.
288  *
289  * @param map The map.
290  * @param key The key.
291  *
292  * @return The value for the specified key on success. Otherwise NULL.
293  * @relatesalso as_map
294  */
295 inline as_val * as_map_get(const as_map * map, const as_val * key)
296 {
297  return as_util_hook(get, NULL, map, key);
298 }
299 
300 /**
301  * Set the value for specified key.
302  *
303  * @param map The map.
304  * @param key The key.
305  * @param val The value for the key.
306  *
307  * @return 0 on success. Otherwise an error occurred.
308  * @relatesalso as_map
309  */
310 inline int as_map_set(as_map * map, const as_val * key, const as_val * val)
311 {
312  return as_util_hook(set, 1, map, key, val);
313 }
314 
315 /**
316  * Remove all entries from the map.
317  *
318  * @param map The map.
319  *
320  * @return 0 on success. Otherwise an error occurred.
321  * @relatesalso as_map
322  */
323 inline int as_map_clear(as_map * map)
324 {
325  return as_util_hook(clear, 1, map);
326 }
327 
328 /**
329  * Remove the entry specified by the key.
330  *
331  * @param map The map to remove the entry from.
332  * @param key The key of the entry to be removed.
333  *
334  * @return 0 on success. Otherwise an error occurred.
335  *
336  * @relatesalso as_map
337  */
338 inline int as_map_remove(as_map * map, const as_val * key)
339 {
340  return as_util_hook(remove, 1, map, key);
341 }
342 
343 /******************************************************************************
344  * ITERATION FUNCTIONS
345  *****************************************************************************/
346 
347 /**
348  * Call the callback function for each entry in the map.
349  *
350  * @param map The map.
351  * @param callback The function to call for each entry.
352  * @param udata User-data to be passed to the callback.
353  *
354  * @return true if iteration completes fully. false if iteration was aborted.
355  *
356  * @relatesalso as_map
357  */
358 inline bool as_map_foreach(const as_map * map, as_map_foreach_callback callback, void * udata)
359 {
360  return as_util_hook(foreach, false, map, callback, udata);
361 }
362 
363 /**
364  * Creates and initializes a new heap allocated iterator over the given map.
365  *
366  * @param map The map to iterate.
367  *
368  * @return On success, a new as_iterator. Otherwise NULL.
369  * @relatesalso as_map
370  */
371 inline union as_map_iterator_u * as_map_iterator_new(const as_map * map)
372 {
373  return as_util_hook(iterator_new, NULL, map);
374 }
375 
376 /**
377  * Initialzies a stack allocated iterator over the given map.
378  *
379  * @param map The map to iterate.
380  * @param it The iterator to initialize.
381  *
382  * @return On success, the initializes as_iterator. Otherwise NULL.
383  * @relatesalso as_map
384  */
385 inline union as_map_iterator_u * as_map_iterator_init(union as_map_iterator_u * it, const as_map * map)
386 {
387  return as_util_hook(iterator_init, NULL, map, it);
388 }
389 
390 /******************************************************************************
391  * CONVERSION FUNCTIONS
392  *****************************************************************************/
393 
394 /**
395  * Convert to an as_val.
396  * @relatesalso as_map
397  */
398 inline as_val * as_map_toval(const as_map * map)
399 {
400  return (as_val *) map;
401 }
402 
403 /**
404  * Convert from an as_val.
405  * @relatesalso as_map
406  */
407 inline as_map * as_map_fromval(const as_val * val)
408 {
409  return as_util_fromval(val, AS_MAP, as_map);
410 }
411 
412 /******************************************************************************
413  * as_val FUNCTIONS
414  *****************************************************************************/
415 
416 /**
417  * @private
418  * Internal helper function for destroying an as_val.
419  */
420 void as_map_val_destroy(as_val * val);
421 
422 /**
423  * @private
424  * Internal helper function for getting the hashcode of an as_val.
425  */
426 uint32_t as_map_val_hashcode(const as_val * val);
427 
428 /**
429  * @private
430  * Internal helper function for getting the string representation of an as_val.
431  */
432 char * as_map_val_tostring(const as_val * val);
bool as_map_foreach(const as_map *map, as_map_foreach_callback callback, void *udata)
Definition: as_map.h:358
void as_map_val_destroy(as_val *val)
Definition: as_map.h:62
as_val * as_map_toval(const as_map *map)
Definition: as_map.h:398
void * data
Definition: as_map.h:74
int as_map_set(as_map *map, const as_val *key, const as_val *val)
Definition: as_map.h:310
as_val * as_map_get(const as_map *map, const as_val *key)
Definition: as_map.h:295
#define as_util_fromval(object, type_id, type)
Definition: as_util.h:41
int as_map_remove(as_map *map, const as_val *key)
Definition: as_map.h:338
Definition: as_val.h:56
#define as_util_hook(hook, default, object, args...)
Definition: as_util.h:35
AS_MAP
Definition: as_val.h:214
char * as_map_val_tostring(const as_val *val)
uint32_t as_map_size(const as_map *map)
Definition: as_map.h:277
as_map * as_map_cons(as_map *map, bool free, void *data, const as_map_hooks *hooks)
union as_map_iterator_u * as_map_iterator_new(const as_map *map)
Definition: as_map.h:371
int as_map_clear(as_map *map)
Definition: as_map.h:323
uint32_t as_map_hashcode(const as_map *map)
Definition: as_map.h:264
as_map * as_map_fromval(const as_val *val)
Definition: as_map.h:407
union as_map_iterator_u * as_map_iterator_init(union as_map_iterator_u *it, const as_map *map)
Definition: as_map.h:385
void as_map_destroy(as_map *map)
Definition: as_map.h:247
#define as_val_destroy(__v)
Definition: as_val.h:109
as_val _
Definition: as_map.h:69
uint32_t as_map_val_hashcode(const as_val *val)
as_map * as_map_new(void *data, const as_map_hooks *hooks)
as_map * as_map_init(as_map *map, void *data, const as_map_hooks *hooks)
struct as_map_hooks_s * hooks
Definition: as_map.h:79
bool(* as_map_foreach_callback)(const as_val *key, const as_val *value, void *udata)
Definition: as_map.h:51