All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
modules/common/target/Darwin-i386/include/aerospike/as_arraylist_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_arraylist.h>
26 #include <aerospike/as_iterator.h>
27 
28 #include <stdbool.h>
29 #include <stdint.h>
30 
31 /******************************************************************************
32  * TYPES
33  ******************************************************************************/
34 
35 /**
36  * Iterator for as_arraylist.
37  *
38  * To use the iterator, you can either initialize a stack allocated variable,
39  * using `as_arraylist_iterator_init()`:
40  *
41  * ~~~~~~~~~~{.c}
42  * as_arraylist_iterator it;
43  * as_arraylist_iterator_init(&it, &list);
44  * ~~~~~~~~~~
45  *
46  * Or you can create a new heap allocated variable, using
47  * `as_arraylist_iterator_new()`:
48  *
49  * ~~~~~~~~~~{.c}
50  * as_arraylist_iterator * it = as_arraylist_iterator_new(&list);
51  * ~~~~~~~~~~
52  *
53  * To iterate, use `as_arraylist_iterator_has_next()` and
54  * `as_arraylist_iterator_next()`:
55  *
56  * ~~~~~~~~~~{.c}
57  * while ( as_arraylist_iterator_has_next(&it) ) {
58  * const as_val * val = as_arraylist_iterator_next(&it);
59  * }
60  * ~~~~~~~~~~
61  *
62  * When you are finished using the iterator, then you should release the
63  * iterator and associated resources:
64  *
65  * ~~~~~~~~~~{.c}
66  * as_arraylist_iterator_destroy(it);
67  * ~~~~~~~~~~
68  *
69  *
70  * The `as_arraylist_iterator` is a subtype of `as_iterator`. This allows you
71  * to alternatively use `as_iterator` functions, by typecasting
72  * `as_arraylist_iterator` to `as_iterator`.
73  *
74  * ~~~~~~~~~~{.c}
75  * as_arraylist_iterator it;
76  * as_iterator * i = (as_iterator *) as_arraylist_iterator_init(&it, &list);
77  *
78  * while ( as_iterator_has_next(i) ) {
79  * const as_val * as_iterator_next(i);
80  * }
81  *
82  * as_iterator_destroy(i);
83  * ~~~~~~~~~~
84  *
85  * Each of the `as_iterator` functions proxy to the `as_arraylist_iterator`
86  * functions. So, calling `as_iterator_destroy()` is equivalent to calling
87  * `as_arraylist_iterator_destroy()`.
88  *
89  * @extends as_iterator
90  */
91 typedef struct as_arraylist_iterator_s {
92 
93  /**
94  * as_arraylist_iterator is an as_iterator.
95  * You can cast as_arraylist_iterator to as_iterator.
96  */
97  as_iterator _;
98 
99  /**
100  * The as_arraylist being iterated over
101  */
102  const as_arraylist * list;
103 
104  /**
105  * The current position of the iteration
106  */
107  uint32_t pos;
108 
110 
111 /******************************************************************************
112  * FUNCTIONS
113  *****************************************************************************/
114 
115 /**
116  * Initializes a stack allocated as_iterator for as_arraylist.
117  *
118  * @param iterator The iterator to initialize.
119  * @param list The list to iterate.
120  *
121  * @return On success, the initialized iterator. Otherwise NULL.
122  *
123  * @relatesalso as_arraylist_iterator
124  */
126 
127 /**
128  * Creates a new heap allocated as_iterator for as_arraylist.
129  *
130  * @param list The list to iterate.
131  *
132  * @return On success, the new iterator. Otherwise NULL.
133  *
134  * @relatesalso as_arraylist_iterator
135  */
137 
138 /**
139  * Destroy the iterator and releases resources used by the iterator.
140  *
141  * @param iterator The iterator to release
142  *
143  * @relatesalso as_arraylist_iterator
144  */
146 
147 /******************************************************************************
148  * ITERATOR FUNCTIONS
149  *****************************************************************************/
150 
151 /**
152  * Tests if there are more values available in the iterator.
153  *
154  * @param iterator The iterator to be tested.
155  *
156  * @return true if there are more values. Otherwise false.
157  *
158  * @relatesalso as_arraylist_iterator
159  */
161 
162 /**
163  * Attempts to get the next value from the iterator.
164  * This will return the next value, and iterate past the value.
165  *
166  * @param iterator The iterator to get the next value from.
167  *
168  * @return The next value in the list if available. Otherwise NULL.
169  *
170  * @relatesalso as_arraylist_iterator
171  */
void as_arraylist_iterator_destroy(as_arraylist_iterator *iterator)
bool as_arraylist_iterator_has_next(const as_arraylist_iterator *iterator)
const as_val * as_arraylist_iterator_next(as_arraylist_iterator *iterator)
as_arraylist_iterator * as_arraylist_iterator_new(const as_arraylist *list)
as_arraylist_iterator * as_arraylist_iterator_init(as_arraylist_iterator *iterator, const as_arraylist *list)