All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
modules/common/target/Darwin-i386/include/aerospike/as_hashmap_iterator.h
Go to the documentation of this file.
1 /******************************************************************************
2  * Copyright 2008-2013 by Aerospike.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to
6  * deal in the Software without restriction, including without limitation the
7  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
8  * sell copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
19  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
20  * IN THE SOFTWARE.
21  *****************************************************************************/
22 
23 #pragma once
24 
25 #include <aerospike/as_hashmap.h>
26 #include <aerospike/as_iterator.h>
27 
28 #include <stdbool.h>
29 
30 /******************************************************************************
31  * TYPES
32  ******************************************************************************/
33 
34 /**
35  * Iterator for as_hashmap.
36  *
37  * To use the iterator, you can either initialize a stack allocated variable,
38  * use `as_hashmap_iterator_init()`:
39  *
40  * ~~~~~~~~~~{.c}
41  * as_hashmap_iterator it;
42  * as_hashmap_iterator_init(&it, &map);
43  * ~~~~~~~~~~
44  *
45  * Or you can create a new heap allocated variable using
46  * `as_hashmap_iterator_new()`:
47  *
48  * ~~~~~~~~~~{.c}
49  * as_hashmap_iterator * it = as_hashmap_iterator_new(&map);
50  * ~~~~~~~~~~
51  *
52  * To iterate, use `as_hashmap_iterator_has_next()` and
53  * `as_hashmap_iterator_next()`:
54  *
55  * ~~~~~~~~~~{.c}
56  * while ( as_hashmap_iterator_has_next(&it) ) {
57  * const as_val * val = as_hashmap_iterator_next(&it);
58  * }
59  * ~~~~~~~~~~
60  *
61  * When you are finished using the iterator, then you should release the
62  * iterator and associated resources:
63  *
64  * ~~~~~~~~~~{.c}
65  * as_hashmap_iterator_destroy(it);
66  * ~~~~~~~~~~
67  *
68  *
69  * The `as_hashmap_iterator` is a subtype of `as_iterator`. This allows you
70  * to alternatively use `as_iterator` functions, by typecasting
71  * `as_hashmap_iterator` to `as_iterator`.
72  *
73  * ~~~~~~~~~~{.c}
74  * as_hashmap_iterator it;
75  * as_iterator * i = (as_iterator *) as_hashmap_iterator_init(&it, &map);
76  *
77  * while ( as_iterator_has_next(i) ) {
78  * const as_val * as_iterator_next(i);
79  * }
80  *
81  * as_iterator_destroy(i);
82  * ~~~~~~~~~~
83  *
84  * Each of the `as_iterator` functions proxy to the `as_hashmap_iterator`
85  * functions. So, calling `as_iterator_destroy()` is equivalent to calling
86  * `as_hashmap_iterator_destroy()`.
87  *
88  * @extends as_iterator
89  */
90 typedef struct as_hashmap_iterator_s {
91 
92  as_iterator _;
93 
94  /**
95  * The hashmap
96  */
97  void * htable;
98 
99  /**
100  * Current entry
101  */
102  void * curr;
103 
104  /**
105  * Next entry
106  */
107  void * next;
108 
109  /**
110  * Position
111  */
112  uint32_t pos;
113 
114  /**
115  * Number of entries
116  */
117  uint32_t size;
118 
120 
121 /******************************************************************************
122  * FUNCTIONS
123  *****************************************************************************/
124 
125 /**
126  * Initializes a stack allocated as_iterator for the given as_hashmap.
127  *
128  * @param iterator The iterator to initialize.
129  * @param map The map to iterate.
130  *
131  * @return On success, the initialized iterator. Otherwise NULL.
132  *
133  * @relatesalso as_hashmap_iterator
134  */
136 
137 /**
138  * Creates a heap allocated as_iterator for the given as_hashmap.
139  *
140  * @param map The map to iterate.
141  *
142  * @return On success, the new iterator. Otherwise NULL.
143  *
144  * @relatesalso as_hashmap_iterator
145  */
147 
148 /**
149  * Destroy the iterator and releases resources used by the iterator.
150  *
151  * @param iterator The iterator to release
152  *
153  * @relatesalso as_hashmap_iterator
154  */
156 
157 
158 /******************************************************************************
159  * ITERATOR FUNCTIONS
160  *****************************************************************************/
161 
162 /**
163  * Tests if there are more values available in the iterator.
164  *
165  * @param iterator The iterator to be tested.
166  *
167  * @return true if there are more values. Otherwise false.
168  *
169  * @relatesalso as_hashmap_iterator
170  */
172 
173 /**
174  * Attempts to get the next value from the iterator.
175  * This will return the next value, and iterate past the value.
176  *
177  * @param iterator The iterator to get the next value from.
178  *
179  * @return The next value in the list if available. Otherwise NULL.
180  *
181  * @relatesalso as_hashmap_iterator
182  */
const as_val * as_hashmap_iterator_next(as_hashmap_iterator *iterator)
as_hashmap_iterator * as_hashmap_iterator_init(as_hashmap_iterator *iterator, const as_hashmap *map)
void as_hashmap_iterator_destroy(as_hashmap_iterator *iterator)
bool as_hashmap_iterator_has_next(const as_hashmap_iterator *iterator)
as_hashmap_iterator * as_hashmap_iterator_new(const as_hashmap *map)