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