Main Page
Modules
Data Structures
Files
File List
Globals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Friends
Macros
Groups
Pages
aerospike
as_record_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
#pragma once
18
19
#ifdef __cplusplus
20
extern
"C"
{
21
#endif
22
23
#include <
aerospike/as_bin.h
>
24
#include <
aerospike/as_bytes.h
>
25
#include <
aerospike/as_integer.h
>
26
#include <
aerospike/as_key.h
>
27
#include <
aerospike/as_list.h
>
28
#include <
aerospike/as_map.h
>
29
#include <
aerospike/as_rec.h
>
30
#include <
aerospike/as_record.h
>
31
#include <
aerospike/as_string.h
>
32
#include <
aerospike/as_util.h
>
33
#include <
aerospike/as_val.h
>
34
35
#include <stdbool.h>
36
#include <stdint.h>
37
38
/******************************************************************************
39
* TYPES
40
*****************************************************************************/
41
42
/**
43
* Iterator over bins of a record.
44
*
45
* ## Initialization
46
*
47
* The as_record_iterator can be initialized via:
48
*
49
* - as_record_iterator_init() — initializes a stack allocated
50
* as_record_iterator.
51
* - as_record_iterator_new() — allocated and initializes an
52
* as_record_iterator on the heap.
53
*
54
* Both of the function require the record on which it will iterate.
55
*
56
* To initialize an as_record_iterator on the stack:
57
*
58
* ~~~~~~~~~~{.c}
59
* as_record_iterator it;
60
* as_record_iterator_init(&it, record);
61
* ~~~~~~~~~~
62
*
63
* To initialize an as_record_iterator on the heap:
64
*
65
* ~~~~~~~~~~{.c}
66
* as_record_iterator * it as_record_iterator_new(record);
67
* ~~~~~~~~~~
68
*
69
* ## Destruction
70
*
71
* When you no longer require the iterator, you should release it and
72
* associated resource via as_record_iterator_destroy():
73
*
74
* ~~~~~~~~~~{.c}
75
* as_record_iterator_destroy(it);
76
* ~~~~~~~~~~
77
*
78
* ## Usage
79
*
80
* With an initialized as_record_iterator, you can traverse the bins of
81
* a record.
82
*
83
* Traversal is usually performed by first checking to see if
84
* the there are any bins available to traverse to via
85
* as_record_iterator_has_next(), which returns true if there are more bins,
86
* or false if there are no more bins.
87
*
88
* ~~~~~~~~~~{.c}
89
* as_record_iterator_has_next(&it);
90
* ~~~~~~~~~~
91
*
92
* When you are sure there are more bins, then you will use
93
* as_record_iterator_next() to read the next bin. If there are no bins
94
* available, then NULL is returned.
95
*
96
* ~~~~~~~~~~{.c}
97
* as_bin * bin = as_record_iterator_next(&it);
98
* ~~~~~~~~~~
99
*
100
* If as_record_iterator_next() returns a bin, then you can use the following
101
* functions to get information about the bin:
102
*
103
* - as_bin_get_name() — Get the bin's name.
104
* - as_bin_get_value() — Get the bin's value.
105
* - as_bin_get_type() — Get the bin's values' types.
106
*
107
* Most often, a traversal is performed in a while loop. The following is a
108
* simple example:
109
*
110
* ~~~~~~~~~~{.c}
111
* while ( as_record_iterator_has_next(&it) ) {
112
* as_bin * bin = as_record_iterator_next(&it);
113
* char * name = as_bin_get_name(bin);
114
* as_val * value = (as_val *) as_bin_get_value(bin);
115
* }
116
* ~~~~~~~~~~
117
*
118
* @ingroup as_record_object
119
*/
120
typedef
struct
as_record_iterator_s {
121
122
/**
123
* @private
124
* If true, then as_record_iterator_destroy() will free this object.
125
*/
126
bool
_free
;
127
128
/**
129
* The record being iterated over.
130
*/
131
const
as_record
*
record
;
132
133
/**
134
* Current position of the iterator
135
*/
136
uint32_t
pos
;
137
138
}
as_record_iterator
;
139
140
/******************************************************************************
141
* FUNCTIONS
142
*****************************************************************************/
143
144
/**
145
* Create and initialize a heap allocated as_record_iterator for the
146
* specified record.
147
*
148
* ~~~~~~~~~~{.c}
149
* as_record_iterator * it = as_record_iterator_new(rec);
150
*
151
* while ( as_record_iterator_has_next(&it) ) {
152
* as_bin * bin = as_record_iterator_next(&it);
153
* }
154
*
155
* as_record_iterator_destroy(&it);
156
* ~~~~~~~~~~
157
*
158
* @param record The record to iterate over.
159
*
160
* @return On success, a new as_record_iterator. Otherwise an error occurred.
161
*
162
* @relates as_record_iterator
163
* @ingroup as_record_object
164
*/
165
as_record_iterator
*
as_record_iterator_new
(
const
as_record
* record);
166
167
/**
168
* Initializes a stack allocated as_record_iterator for the specified record.
169
*
170
* ~~~~~~~~~~{.c}
171
* as_record_iterator it;
172
* as_record_iterator_init(&it, rec);
173
*
174
* while ( as_record_iterator_has_next(&it) ) {
175
* as_bin * bin = as_record_iterator_next(&it);
176
* }
177
*
178
* as_record_iterator_destroy(&it);
179
* ~~~~~~~~~~
180
*
181
* When you are finished using the `as_record` instance, you should release the
182
* resources allocated to it by calling `as_record_destroy()`.
183
*
184
* @param iterator The iterator to initialize.
185
* @param record The record to iterate over
186
*
187
* @return On success, a new as_record_iterator. Otherwise an error occurred.
188
*
189
* @relates as_record_iterator
190
* @ingroup as_record_object
191
*/
192
as_record_iterator
*
as_record_iterator_init
(
as_record_iterator
* iterator,
const
as_record
* record);
193
194
/**
195
* Destroy the as_record_iterator and associated resources.
196
*
197
* @param iterator The iterator to destroy.
198
*
199
* @relates as_record_iterator
200
* @ingroup as_record_object
201
*/
202
void
as_record_iterator_destroy
(
as_record_iterator
* iterator);
203
204
/**
205
* Test if there are more bins in the iterator.
206
*
207
* @param iterator The iterator to test.
208
*
209
* @return the number of bins in the record.
210
*
211
* @relates as_record_iterator
212
* @ingroup as_record_object
213
*/
214
bool
as_record_iterator_has_next
(
const
as_record_iterator
* iterator);
215
216
/**
217
* Read the next bin from the iterator.
218
*
219
* @param iterator The iterator to read from.
220
*
221
* @return The next bin from the iterator.
222
*
223
* @relates as_record_iterator
224
* @ingroup as_record_object
225
*/
226
as_bin
*
as_record_iterator_next
(
as_record_iterator
* iterator);
227
228
229
#ifdef __cplusplus
230
}
// end extern "C"
231
#endif