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