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-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 
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  */
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  */
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  */
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  */
223 
224