Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
as_hashmap_iterator.h
Go to the documentation of this file.
1
/*
2
* Copyright 2008-2015 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
*/
110
as_hashmap_element
*
curr
;
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
*/
122
as_pair
pair
;
123
124
}
as_hashmap_iterator
;
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
*/
140
as_hashmap_iterator
*
as_hashmap_iterator_init
(
as_hashmap_iterator
* iterator,
const
as_hashmap
* map);
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
*/
151
as_hashmap_iterator
*
as_hashmap_iterator_new
(
const
as_hashmap
* map);
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
*/
160
void
as_hashmap_iterator_destroy
(
as_hashmap_iterator
* iterator);
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
*/
176
bool
as_hashmap_iterator_has_next
(
const
as_hashmap_iterator
* iterator);
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
*/
188
const
as_val
*
as_hashmap_iterator_next
(
as_hashmap_iterator
* iterator);
189
190
#ifdef __cplusplus
191
}
// end extern "C"
192
#endif