code cleanups
[strongswan.git] / src / libstrongswan / utils / iterator.h
1 /**
2 * @file iterator.h
3 *
4 * @brief Interface iterator_t.
5 *
6 */
7
8 /*
9 * Copyright (C) 2005-2006 Martin Willi
10 * Copyright (C) 2005 Jan Hutter
11 * Hochschule fuer Technik Rapperswil
12 *
13 * This program is free software; you can redistribute it and/or modify it
14 * under the terms of the GNU General Public License as published by the
15 * Free Software Foundation; either version 2 of the License, or (at your
16 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
17 *
18 * This program is distributed in the hope that it will be useful, but
19 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
20 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
21 * for more details.
22 */
23
24 #ifndef ITERATOR_H_
25 #define ITERATOR_H_
26
27 typedef struct iterator_t iterator_t;
28
29 /**
30 * @brief Iterator interface, allows iteration over collections.
31 *
32 * iterator_t defines an interface for iterating over collections.
33 * It allows searching, deleting, updating and inserting.
34 *
35 * Thanks to JMP for iterator lessons :-)
36 *
37 * @b Constructors:
38 * - via linked_list_t.create_iterator, or
39 * - any other class which supports the iterator_t interface
40 *
41 * @see linked_list_t
42 *
43 * @ingroup utils
44 */
45 struct iterator_t {
46
47 /**
48 * @brief Return number of list items.
49 *
50 * @param this calling object
51 * @return number of list items
52 */
53 int (*get_count) (iterator_t *this);
54
55 /**
56 * @brief Iterate over all items.
57 *
58 * The easy way to iterate over items.
59 *
60 * @param this calling object
61 * @param[out] value item
62 * @return
63 * - TRUE, if there was an element available,
64 * - FALSE otherwise
65 */
66 bool (*iterate) (iterator_t *this, void** value);
67
68 /**
69 * @brief Moves to the next element, if available.
70 *
71 * A newly created iterator_t object doesn't point to any item.
72 * Call iterator_t.has_next first to point it to the first item.
73 *
74 * @param this calling object
75 * @return
76 * - TRUE, if more elements are available,
77 * - FALSE otherwise
78 */
79 bool (*has_next) (iterator_t *this);
80
81 /**
82 * @brief Returns the current value at the iterator position.
83 *
84 * @param this calling object
85 * @param[out] value value is set to the current value at iterator position
86 * @return
87 * - SUCCESS
88 * - FAILED if iterator on an invalid position
89 */
90 status_t (*current) (iterator_t *this, void **value);
91
92 /**
93 * @brief Inserts a new item before the given iterator position.
94 *
95 * The iterator position is not changed after inserting
96 *
97 * @param this calling iterator
98 * @param[in] item value to insert in list
99 */
100 void (*insert_before) (iterator_t *this, void *item);
101
102 /**
103 * @brief Inserts a new item after the given iterator position.
104 *
105 * The iterator position is not changed after inserting.
106 *
107 * @param this calling iterator
108 * @param[in] item value to insert in list
109 */
110 void (*insert_after) (iterator_t *this, void *item);
111
112 /**
113 * @brief Replace the current item at current iterator position.
114 *
115 * The iterator position is not changed after replacing.
116 *
117 * @param this calling iterator
118 * @param[out] old_item old value will be written here(can be NULL)
119 * @param[in] new_item new value
120 *
121 * @return
122 * - SUCCESS
123 * - FAILED if iterator is on an invalid position
124 */
125 status_t (*replace) (iterator_t *this, void **old_item, void *new_item);
126
127 /**
128 * @brief Removes an element from list at the given iterator position.
129 *
130 * The iterator is set the the following position:
131 * - to the item before, if available
132 * - it gets reseted, otherwise
133 *
134 * @param this calling object
135 * @return
136 * - SUCCESS
137 * - FAILED if iterator is on an invalid position
138 */
139 status_t (*remove) (iterator_t *this);
140
141 /**
142 * @brief Resets the iterator position.
143 *
144 * After reset, the iterator_t objects doesn't point to an element.
145 * A call to iterator_t.has_next is necessary to do any other operations
146 * with the resetted iterator.
147 *
148 * @param this calling object
149 */
150 void (*reset) (iterator_t *this);
151
152 /**
153 * @brief Destroys an iterator.
154 *
155 * @param this iterator to destroy
156 *
157 */
158 void (*destroy) (iterator_t *this);
159 };
160
161 #endif /*ITERATOR_H_*/