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 
23 #include <stdbool.h>
24 
25 /******************************************************************************
26  * TYPES
27  ******************************************************************************/
28 
29 /**
30  * Iterator for as_hashmap.
31  *
32  * To use the iterator, you can either initialize a stack allocated variable,
33  * use `as_hashmap_iterator_init()`:
34  *
35  * ~~~~~~~~~~{.c}
36  * as_hashmap_iterator it;
37  * as_hashmap_iterator_init(&it, &map);
38  * ~~~~~~~~~~
39  *
40  * Or you can create a new heap allocated variable using
41  * `as_hashmap_iterator_new()`:
42  *
43  * ~~~~~~~~~~{.c}
44  * as_hashmap_iterator * it = as_hashmap_iterator_new(&map);
45  * ~~~~~~~~~~
46  *
47  * To iterate, use `as_hashmap_iterator_has_next()` and
48  * `as_hashmap_iterator_next()`:
49  *
50  * ~~~~~~~~~~{.c}
51  * while ( as_hashmap_iterator_has_next(&it) ) {
52  * const as_val * val = as_hashmap_iterator_next(&it);
53  * }
54  * ~~~~~~~~~~
55  *
56  * When you are finished using the iterator, then you should release the
57  * iterator and associated resources:
58  *
59  * ~~~~~~~~~~{.c}
60  * as_hashmap_iterator_destroy(it);
61  * ~~~~~~~~~~
62  *
63  *
64  * The `as_hashmap_iterator` is a subtype of `as_iterator`. This allows you
65  * to alternatively use `as_iterator` functions, by typecasting
66  * `as_hashmap_iterator` to `as_iterator`.
67  *
68  * ~~~~~~~~~~{.c}
69  * as_hashmap_iterator it;
70  * as_iterator * i = (as_iterator *) as_hashmap_iterator_init(&it, &map);
71  *
72  * while ( as_iterator_has_next(i) ) {
73  * const as_val * as_iterator_next(i);
74  * }
75  *
76  * as_iterator_destroy(i);
77  * ~~~~~~~~~~
78  *
79  * Each of the `as_iterator` functions proxy to the `as_hashmap_iterator`
80  * functions. So, calling `as_iterator_destroy()` is equivalent to calling
81  * `as_hashmap_iterator_destroy()`.
82  *
83  * @extends as_iterator
84  */
85 typedef struct as_hashmap_iterator_s {
86 
88 
89  /**
90  * The hashmap
91  */
92  void * htable;
93 
94  /**
95  * Current entry
96  */
97  void * curr;
98 
99  /**
100  * Next entry
101  */
102  void * next;
103 
104  /**
105  * Position
106  */
107  uint32_t pos;
108 
109  /**
110  * Number of entries
111  */
112  uint32_t size;
113 
115 
116 /******************************************************************************
117  * FUNCTIONS
118  *****************************************************************************/
119 
120 /**
121  * Initializes a stack allocated as_iterator for the given as_hashmap.
122  *
123  * @param iterator The iterator to initialize.
124  * @param map The map to iterate.
125  *
126  * @return On success, the initialized iterator. Otherwise NULL.
127  *
128  * @relatesalso as_hashmap_iterator
129  */
131 
132 /**
133  * Creates a heap allocated as_iterator for the given as_hashmap.
134  *
135  * @param map The map to iterate.
136  *
137  * @return On success, the new iterator. Otherwise NULL.
138  *
139  * @relatesalso as_hashmap_iterator
140  */
142 
143 /**
144  * Destroy the iterator and releases resources used by the iterator.
145  *
146  * @param iterator The iterator to release
147  *
148  * @relatesalso as_hashmap_iterator
149  */
151 
152 
153 /******************************************************************************
154  * ITERATOR FUNCTIONS
155  *****************************************************************************/
156 
157 /**
158  * Tests if there are more values available in the iterator.
159  *
160  * @param iterator The iterator to be tested.
161  *
162  * @return true if there are more values. Otherwise false.
163  *
164  * @relatesalso as_hashmap_iterator
165  */
167 
168 /**
169  * Attempts to get the next value from the iterator.
170  * This will return the next value, and iterate past the value.
171  *
172  * @param iterator The iterator to get the next value from.
173  *
174  * @return The next value in the list if available. Otherwise NULL.
175  *
176  * @relatesalso as_hashmap_iterator
177  */