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