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