All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
as_record_iterator.h
Go to the documentation of this file.
1 /*
2  * Copyright 2008-2016 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 #ifdef __cplusplus
35 extern "C" {
36 #endif
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 
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  */
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  */
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  */
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  */
227 
228 
229 #ifdef __cplusplus
230 } // end extern "C"
231 #endif