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