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