17deb630ce5ba06ffbb5ce32945326332664af4b
[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 */
35 struct iterator_t {
36
37 /**
38 * @brief Moves to the next element, if available.
39 *
40 * @param this calling object
41 * @return
42 * - TRUE, if more elements are avaiable,
43 * - FALSE otherwise
44 */
45 bool (*has_next) (iterator_t *this);
46
47 /**
48 * @brief Returns the current value at the iterator position.
49 *
50 * @param this calling object
51 * @param [out]value value is set to the current value at iterator position
52 * @return
53 * - SUCCESS, or
54 * - FAILED if iterator is on an invalid state
55 */
56 status_t (*current) (iterator_t *this, void **value);
57
58 /**
59 * @brief Inserts a new item before the given iterator position.
60 *
61 * The iterator position is not changed after inserting
62 *
63 * @param this calling iterator
64 * @param [in]item value to insert in list
65 * @return
66 * - SUCCESS if succeeded,
67 * - FAILED otherwise
68 */
69 status_t (*insert_before) (iterator_t *this, void *item);
70
71 /**
72 * @brief Inserts a new item after the given iterator position.
73 *
74 * The iterator position is not changed after inserting.
75 *
76 * @param this calling iterator
77 * @param [in]item value to insert in list
78 * @return
79 * - SUCCESS if succeeded,
80 * - FAILED otherwise
81 */
82 status_t (*insert_after) (iterator_t *this, void *item);
83
84 /**
85 * @brief removes an element from list at the given iterator position.
86 *
87 * The position of the iterator is set in the following order:
88 * - to the item before, if available
89 * - otherwise to the item after, if available
90 * - otherwise it gets reseted
91 *
92 * @param linked_list calling object
93 * @return
94 * - SUCCESS if succeeded,
95 * - FAILED otherwise
96 */
97 status_t (*remove) (iterator_t *iterator);
98
99 /**
100 * @brief Resets the iterator position.
101 *
102 * After reset, the iterator stands NOT on an element.
103 * A call to has_next is necessary to do any other operations
104 * with the resetted iterator.
105 *
106 * @param this calling object
107 * @return
108 * - SUCCESS if succeeded,
109 * - FAILED otherwise
110 */
111 status_t (*reset) (iterator_t *this);
112
113 /**
114 * @brief Destroys an iterator.
115 *
116 * @param this iterator to destroy
117 * @return
118 * - SUCCESS if succeeded,
119 * - FAILED otherwise
120 */
121 status_t (*destroy) (iterator_t *this);
122 };
123
124 #endif /*ITERATOR_H_*/