All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_hashmap_iterator.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_hashmap.h>
21 #include <aerospike/as_iterator.h>
22 #include <aerospike/as_pair.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 /**
36  * Iterator for as_hashmap.
37  *
38  * To use the iterator, you can either initialize a stack allocated variable,
39  * use `as_hashmap_iterator_init()`:
40  *
41  * ~~~~~~~~~~{.c}
42  * as_hashmap_iterator it;
43  * as_hashmap_iterator_init(&it, &map);
44  * ~~~~~~~~~~
45  *
46  * Or you can create a new heap allocated variable using
47  * `as_hashmap_iterator_new()`:
48  *
49  * ~~~~~~~~~~{.c}
50  * as_hashmap_iterator * it = as_hashmap_iterator_new(&map);
51  * ~~~~~~~~~~
52  *
53  * To iterate, use `as_hashmap_iterator_has_next()` and
54  * `as_hashmap_iterator_next()`:
55  *
56  * ~~~~~~~~~~{.c}
57  * while ( as_hashmap_iterator_has_next(&it) ) {
58  * const as_val * val = as_hashmap_iterator_next(&it);
59  * }
60  * ~~~~~~~~~~
61  *
62  * When you are finished using the iterator, then you should release the
63  * iterator and associated resources:
64  *
65  * ~~~~~~~~~~{.c}
66  * as_hashmap_iterator_destroy(it);
67  * ~~~~~~~~~~
68  *
69  *
70  * The `as_hashmap_iterator` is a subtype of `as_iterator`. This allows you
71  * to alternatively use `as_iterator` functions, by typecasting
72  * `as_hashmap_iterator` to `as_iterator`.
73  *
74  * ~~~~~~~~~~{.c}
75  * as_hashmap_iterator it;
76  * as_iterator * i = (as_iterator *) as_hashmap_iterator_init(&it, &map);
77  *
78  * while ( as_iterator_has_next(i) ) {
79  * const as_val * as_iterator_next(i);
80  * }
81  *
82  * as_iterator_destroy(i);
83  * ~~~~~~~~~~
84  *
85  * Each of the `as_iterator` functions proxy to the `as_hashmap_iterator`
86  * functions. So, calling `as_iterator_destroy()` is equivalent to calling
87  * `as_hashmap_iterator_destroy()`.
88  *
89  * Notes:
90  *
91  * as_hashmap_iterator_next() returns an as_pair pointer. The as_pair contains
92  * the key and value pointers of the current map element. This one as_pair
93  * "container" is re-used for all the iterations, i.e. the contents will be
94  * overwritten and are only valid until the next iteration.
95  *
96  * @extends as_iterator
97  */
98 typedef struct as_hashmap_iterator_s {
99 
100  as_iterator _;
101 
102  /**
103  * The hashmap
104  */
105  const as_hashmap * map;
106 
107  /**
108  * Current entry
109  */
111 
112  /**
113  * Internal counters
114  */
115  uint32_t count;
116  uint32_t table_pos;
117  uint32_t extras_pos;
118 
119  /**
120  * Last returned key & value
121  */
123 
125 
126 /******************************************************************************
127  * FUNCTIONS
128  *****************************************************************************/
129 
130 /**
131  * Initializes a stack allocated as_iterator for the given as_hashmap.
132  *
133  * @param iterator The iterator to initialize.
134  * @param map The map to iterate.
135  *
136  * @return On success, the initialized iterator. Otherwise NULL.
137  *
138  * @relatesalso as_hashmap_iterator
139  */
141 
142 /**
143  * Creates a heap allocated as_iterator for the given as_hashmap.
144  *
145  * @param map The map to iterate.
146  *
147  * @return On success, the new iterator. Otherwise NULL.
148  *
149  * @relatesalso as_hashmap_iterator
150  */
152 
153 /**
154  * Destroy the iterator and releases resources used by the iterator.
155  *
156  * @param iterator The iterator to release
157  *
158  * @relatesalso as_hashmap_iterator
159  */
161 
162 
163 /******************************************************************************
164  * ITERATOR FUNCTIONS
165  *****************************************************************************/
166 
167 /**
168  * Tests if there are more values available in the iterator.
169  *
170  * @param iterator The iterator to be tested.
171  *
172  * @return true if there are more values. Otherwise false.
173  *
174  * @relatesalso as_hashmap_iterator
175  */
177 
178 /**
179  * Attempts to get the next value from the iterator.
180  * This will return the next value, and iterate past the value.
181  *
182  * @param iterator The iterator to get the next value from.
183  *
184  * @return The next value in the list if available. Otherwise NULL.
185  *
186  * @relatesalso as_hashmap_iterator
187  */
189 
190 #ifdef __cplusplus
191 } // end extern "C"
192 #endif