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