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