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