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-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
96
as_iterator
_
;
97
98
/**
99
* The hashmap
100
*/
101
const
as_hashmap
*
map
;
102
103
/**
104
* Current entry
105
*/
106
as_hashmap_element
*
curr
;
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
*/
118
as_pair
pair
;
119
120
}
as_hashmap_iterator
;
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
*/
136
as_hashmap_iterator
*
as_hashmap_iterator_init
(
as_hashmap_iterator
* iterator,
const
as_hashmap
* map);
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
*/
147
as_hashmap_iterator
*
as_hashmap_iterator_new
(
const
as_hashmap
* map);
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
*/
156
void
as_hashmap_iterator_destroy
(
as_hashmap_iterator
* iterator);
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
*/
172
bool
as_hashmap_iterator_has_next
(
const
as_hashmap_iterator
* iterator);
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
*/
184
const
as_val
*
as_hashmap_iterator_next
(
as_hashmap_iterator
* iterator);