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-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_map.h>
21 
22 #include <stdbool.h>
23 #include <stdint.h>
24 
25 /******************************************************************************
26  * TYPES
27  ******************************************************************************/
28 
29 /**
30  * A hashtable based implementation of `as_map`.
31  *
32  * To use the map, you can either initialize a stack allocated map,
33  * using `as_hashmap_init()`:
34  *
35  * ~~~~~~~~~~{.c}
36  * as_hashmap map;
37  * as_hashmap_init(&map, 32);
38  * ~~~~~~~~~~
39  *
40  * Or you can create a new heap allocated map using
41  * `as_hashmap_new()`:
42  *
43  * ~~~~~~~~~~{.c}
44  * as_hashmap * map = as_hashmap_new(32);
45  * ~~~~~~~~~~
46  *
47  * When you are finished using the map, then you should release the
48  * map and associated resources, using `as_hashmap_destroy()`:
49  *
50  * ~~~~~~~~~~{.c}
51  * as_hashmap_destroy(map);
52  * ~~~~~~~~~~
53  *
54  *
55  * The `as_hashmap` is a subtype of `as_map`. This allows you to alternatively
56  * use `as_map` functions, by typecasting `as_hashmap` to `as_map`.
57  *
58  * ~~~~~~~~~~{.c}
59  * as_hashmap map;
60  * as_map * l = (as_map*) as_hashmap_init(&map, 32);
61  * as_stringmap_set_int64(l, "a", 1);
62  * as_stringmap_set_int64(l, "b", 2);
63  * as_stringmap_set_int64(l, "c", 3);
64  * as_map_destroy(l);
65  * ~~~~~~~~~~
66  *
67  * The `as_stringmap` functions are simplified functions for using string key.
68  *
69  * Each of the `as_map` functions proxy to the `as_hashmap` functions.
70  * So, calling `as_map_destroy()` is equivalent to calling
71  * `as_hashmap_destroy()`.
72  *
73  * @extends as_map
74  * @ingroup aerospike_t
75  */
76 typedef struct as_hashmap_s {
77 
78  /**
79  * @private
80  * as_hashmap is an as_map.
81  * You can cast as_hashmap to as_map.
82  */
84 
85  /**
86  * Hashtable
87  */
88  void * htable;
89 
90 } as_hashmap;
91 
92 /*******************************************************************************
93  * INSTANCE FUNCTIONS
94  ******************************************************************************/
95 
96 /**
97  * Initialize a stack allocated hashmap.
98  *
99  * @param map The map to initialize.
100  * @param buckets The number of hash buckets to allocate.
101  *
102  * @return On success, the initialized map. Otherwise NULL.
103  *
104  * @relatesalso as_hashmap
105  */
106 as_hashmap * as_hashmap_init(as_hashmap * map, uint32_t buckets);
107 
108 /**
109  * Creates a new map as a hashmap.
110  *
111  * @param buckets The number of hash buckets to allocate.
112  *
113  * @return On success, the new map. Otherwise NULL.
114  *
115  * @relatesalso as_hashmap
116  */
117 as_hashmap * as_hashmap_new(uint32_t buckets);
118 
119 /**
120  * Free the map and associated resources.
121  *
122  * @param map The map to destroy.
123  *
124  * @relatesalso as_hashmap
125  */
126 void as_hashmap_destroy(as_hashmap * map);
127 
128 /*******************************************************************************
129  * INFO FUNCTIONS
130  ******************************************************************************/
131 
132 /**
133  * The hash value of the map.
134  *
135  * @param map The map.
136  *
137  * @return The hash value of the map.
138  *
139  * @relatesalso as_hashmap
140  */
141 uint32_t as_hashmap_hashcode(const as_hashmap * map);
142 
143 /**
144  * Get the number of entries in the map.
145  *
146  * @param map The map.
147  *
148  * @return The number of entries in the map.
149  *
150  * @relatesalso as_hashmap
151  */
152 uint32_t as_hashmap_size(const as_hashmap * map);
153 
154 /*******************************************************************************
155  * ACCESSOR AND MODIFIER FUNCTIONS
156  ******************************************************************************/
157 
158 /**
159  * Get the value for specified key.
160  *
161  * @param map The map.
162  * @param key The key.
163  *
164  * @return The value for the specified key. Otherwise NULL.
165  *
166  * @relatesalso as_hashmap
167  */
168 as_val * as_hashmap_get(const as_hashmap * map, const as_val * key);
169 
170 /**
171  * Set the value for specified key.
172  *
173  * @param map The map.
174  * @param key The key.
175  * @param val The value for the given key.
176  *
177  * @return 0 on success. Otherwise an error occurred.
178  *
179  * @relatesalso as_hashmap
180  */
181 int as_hashmap_set(as_hashmap * map, const as_val * key, const as_val * val);
182 
183 /**
184  * Remove all entries from the map.
185  *
186  * @param map The map.
187  *
188  * @return 0 on success. Otherwise an error occurred.
189  *
190  * @relatesalso as_hashmap
191  */
192 int as_hashmap_clear(as_hashmap * map);
193 
194 /**
195  * Remove the entry specified by the key.
196  *
197  * @param map The map to remove the entry from.
198  * @param key The key of the entry to be removed.
199  *
200  * @return 0 on success. Otherwise an error occurred.
201  *
202  * @relatesalso as_hashmap
203  */
204 int as_hashmap_remove(as_hashmap * map, const as_val * key);
205 
206 /******************************************************************************
207  * ITERATION FUNCTIONS
208  *****************************************************************************/
209 
210 /**
211  * Call the callback function for each entry in the map.
212  *
213  * @param map The map.
214  * @param callback The function to call for each entry.
215  * @param udata User-data to be passed to the callback.
216  *
217  * @return true if iteration completes fully. false if iteration was aborted.
218  *
219  * @relatesalso as_hashmap
220  */
221 bool as_hashmap_foreach(const as_hashmap * map, as_map_foreach_callback callback, void * udata);
bool as_hashmap_foreach(const as_hashmap *map, as_map_foreach_callback callback, void *udata)
as_map _
Definition: as_hashmap.h:83
int as_hashmap_remove(as_hashmap *map, const as_val *key)
Definition: as_map.h:57
uint32_t as_hashmap_hashcode(const as_hashmap *map)
Definition: as_val.h:51
int as_hashmap_set(as_hashmap *map, const as_val *key, const as_val *val)
as_hashmap * as_hashmap_new(uint32_t buckets)
as_hashmap * as_hashmap_init(as_hashmap *map, uint32_t buckets)
void * htable
Definition: as_hashmap.h:88
void as_hashmap_destroy(as_hashmap *map)
uint32_t as_hashmap_size(const as_hashmap *map)
bool(* as_map_foreach_callback)(const as_val *key, const as_val *value, void *udata)
Definition: as_map.h:46
as_val * as_hashmap_get(const as_hashmap *map, const as_val *key)
int as_hashmap_clear(as_hashmap *map)