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-2017 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 #include <aerospike/as_iterator.h>
21 #include <aerospike/as_util.h>
22 #include <aerospike/as_val.h>
23 
24 #include <stdbool.h>
25 #include <stdint.h>
26 
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
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  * Information for this instance of as_map.
72  */
73  uint32_t flags;
74 
75  /**
76  * Hooks for subtypes of as_map 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 flags Map attributes.
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, uint32_t flags, const as_map_hooks * hooks);
218 
219 /**
220  * Initialize a stack allocated map.
221  *
222  * @param map Stack allocated map to initialize.
223  * @param hooks Implementation for the map interface.
224  *
225  * @return On success, the initialized map. Otherwise NULL.
226  * @relatesalso as_map
227  */
228 as_map * as_map_init(as_map * map, const as_map_hooks * hooks);
229 
230 /**
231  * Create and initialize a new heap allocated map.
232  *
233  * @param hooks Implementation for the list interface.
234  *
235  * @return On success, a new list. Otherwise NULL.
236  * @relatesalso as_map
237  */
238 as_map * as_map_new(const as_map_hooks * hooks);
239 
240 /**
241  * Destroy the as_map and associated resources.
242  * @relatesalso as_map
243  */
244 static inline void as_map_destroy(as_map * map)
245 {
246  as_val_destroy((as_val *) map);
247 }
248 
249 /*******************************************************************************
250  * INFO FUNCTIONS
251  ******************************************************************************/
252 
253 /**
254  * Hash value for the map
255  *
256  * @param map The map
257  *
258  * @return The hashcode value of the map.
259  * @relatesalso as_map
260  */
261 static inline uint32_t as_map_hashcode(const as_map * map)
262 {
263  return as_util_hook(hashcode, 0, map);
264 }
265 
266 /**
267  * Get the number of entries in the map.
268  *
269  * @param map The map
270  *
271  * @return The size of the map.
272  * @relatesalso as_map
273  */
274 static inline uint32_t as_map_size(const as_map * map)
275 {
276  return as_util_hook(size, 0, map);
277 }
278 
279 /*******************************************************************************
280  * ACCESSOR AND MODIFIER FUNCTIONS
281  ******************************************************************************/
282 
283 /**
284  * Get the value for specified key.
285  *
286  * @param map The map.
287  * @param key The key.
288  *
289  * @return The value for the specified key on success. Otherwise NULL.
290  * @relatesalso as_map
291  */
292 static inline as_val * as_map_get(const as_map * map, const as_val * key)
293 {
294  return as_util_hook(get, NULL, map, key);
295 }
296 
297 /**
298  * Set the value for specified key.
299  *
300  * @param map The map.
301  * @param key The key.
302  * @param val The value for the key.
303  *
304  * @return 0 on success. Otherwise an error occurred.
305  * @relatesalso as_map
306  */
307 static inline int as_map_set(as_map * map, const as_val * key, const as_val * val)
308 {
309  return as_util_hook(set, 1, map, key, val);
310 }
311 
312 /**
313  * Remove all entries from the map.
314  *
315  * @param map The map.
316  *
317  * @return 0 on success. Otherwise an error occurred.
318  * @relatesalso as_map
319  */
320 static inline int as_map_clear(as_map * map)
321 {
322  return as_util_hook(clear, 1, map);
323 }
324 
325 /**
326  * Remove the entry specified by the key.
327  *
328  * @param map The map to remove the entry from.
329  * @param key The key of the entry to be removed.
330  *
331  * @return 0 on success. Otherwise an error occurred.
332  *
333  * @relatesalso as_map
334  */
335 static inline int as_map_remove(as_map * map, const as_val * key)
336 {
337  return as_util_hook(remove, 1, map, key);
338 }
339 
340 /******************************************************************************
341  * ITERATION FUNCTIONS
342  *****************************************************************************/
343 
344 /**
345  * Call the callback function for each entry in the map.
346  *
347  * @param map The map.
348  * @param callback The function to call for each entry.
349  * @param udata User-data to be passed to the callback.
350  *
351  * @return true if iteration completes fully. false if iteration was aborted.
352  *
353  * @relatesalso as_map
354  */
355 static inline bool as_map_foreach(const as_map * map, as_map_foreach_callback callback, void * udata)
356 {
357  return as_util_hook(foreach, false, map, callback, udata);
358 }
359 
360 /**
361  * Creates and initializes a new heap allocated iterator over the given map.
362  *
363  * @param map The map to iterate.
364  *
365  * @return On success, a new as_iterator. Otherwise NULL.
366  * @relatesalso as_map
367  */
368 static inline union as_map_iterator_u * as_map_iterator_new(const as_map * map)
369 {
370  return as_util_hook(iterator_new, NULL, map);
371 }
372 
373 /**
374  * Initialzies a stack allocated iterator over the given map.
375  *
376  * @param map The map to iterate.
377  * @param it The iterator to initialize.
378  *
379  * @return On success, the initializes as_iterator. Otherwise NULL.
380  * @relatesalso as_map
381  */
382 static inline union as_map_iterator_u * as_map_iterator_init(union as_map_iterator_u * it, const as_map * map)
383 {
384  return as_util_hook(iterator_init, NULL, map, it);
385 }
386 
387 /******************************************************************************
388  * CONVERSION FUNCTIONS
389  *****************************************************************************/
390 
391 /**
392  * Convert to an as_val.
393  * @relatesalso as_map
394  */
395 static inline as_val * as_map_toval(const as_map * map)
396 {
397  return (as_val *) map;
398 }
399 
400 /**
401  * Convert from an as_val.
402  * @relatesalso as_map
403  */
404 static inline as_map * as_map_fromval(const as_val * val)
405 {
406  return as_util_fromval(val, AS_MAP, as_map);
407 }
408 
409 /******************************************************************************
410  * as_val FUNCTIONS
411  *****************************************************************************/
412 
413 /**
414  * @private
415  * Internal helper function for destroying an as_val.
416  */
417 void as_map_val_destroy(as_val * val);
418 
419 /**
420  * @private
421  * Internal helper function for getting the hashcode of an as_val.
422  */
423 uint32_t as_map_val_hashcode(const as_val * val);
424 
425 /**
426  * @private
427  * Internal helper function for getting the string representation of an as_val.
428  */
429 char * as_map_val_tostring(const as_val * val);
430 
431 #ifdef __cplusplus
432 } // end extern "C"
433 #endif