All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
target/Linux-x86_64/include/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 
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  */
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  */
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  */
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  */
229 
230 
void as_record_iterator_destroy(as_record_iterator *iterator)
as_record_iterator * as_record_iterator_init(as_record_iterator *iterator, const as_record *record)
as_bin * as_record_iterator_next(as_record_iterator *iterator)
as_record_iterator * as_record_iterator_new(const as_record *record)
bool as_record_iterator_has_next(const as_record_iterator *iterator)