1/*
2 Lightweight C Container Library
3
4 Copyright (c) 2002 Tobias Koenig <tokoe@kde.org>
5
6 Original code was written by Chris Schlaeger <cs@kde.org>
7
8 This library is free software; you can redistribute it and/or
9 modify it under the terms of the GNU Library General Public
10 License as published by the Free Software Foundation; either
11 version 2 of the License, or (at your option) any later version.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Library General Public License for more details.
17
18 You should have received a copy of the GNU Library General Public License
19 along with this library; see the file COPYING.LIB. If not, write to
20 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
21 Boston, MA 02110-1301, USA.
22
23*/
24
25#ifndef _CCONT_H
26#define _CCONT_H
27
28#ifndef NIL
29#define NIL ((void*) 0)
30#endif
31
32#define destr_ctnr(x, y) zero_destr_ctnr(x, y); x=0
33
34struct container {
35 struct container* next;
36 struct container* prev;
37 void* data;
38};
39
40typedef struct container T_CONTAINER;
41typedef struct container* CONTAINER;
42
43typedef long INDEX;
44
45typedef void (*DESTR_FUNC)(void*);
46typedef int (*COMPARE_FUNC)(void*, void*);
47
48/**
49 * Initialize the container @p ctnr.
50 */
51CONTAINER new_ctnr(void);
52
53/**
54 * Remove all entries from @p ctnr and reset its
55 * internal structure. Use @ref new_ctnr() @em before @em
56 * accessing the container again.
57 *
58 * Note: use the 'destr_ctnr' macro to get zeroed pointer
59 * automatically.
60 *
61 * @param destr_func The function that is called to
62 * free the single entries.
63 */
64void zero_destr_ctnr(CONTAINER ctnr, DESTR_FUNC destr_func);
65
66/**
67 * Remove all entries from @p ctnr. There is no need to use
68 * @ref new_ctnr() for subsequent access to the container.
69 *
70 */
71void empty_ctnr(CONTAINER rootNode);
72
73/**
74 * @return the number of entries in @p ctnr.
75 */
76INDEX level_ctnr(CONTAINER ctnr);
77
78/**
79 * Insert a new entry in container.
80 *
81 * @param object A pointer to the object.
82 * @param pos The position where the object should be insert.
83 */
84void insert_ctnr(CONTAINER ctnr, void* object, INDEX pos);
85
86/**
87 * Add a new entry at the end of container.
88 *
89 * @param object The object that should be added.
90 */
91void push_ctnr(CONTAINER ctnr, void* object);
92
93/**
94 * Remove an entry from container.
95 *
96 * @param pos The position of the object that should be removed.
97 *
98 * @return A pointer to the removed object or @p 0L if it doesn't exist.
99 */
100void* remove_at_ctnr(CONTAINER ctnr, INDEX pos);
101
102/**
103 * Remove the first entry of container.
104 *
105 * @return A pointer to the removed object or @p 0L if there is now entry.
106 */
107void* pop_ctnr(CONTAINER ctnr);
108
109/**
110 * @return A pointer to the object at position @a pos
111 * or @p 0L if it doesn't exist.
112 */
113void* get_ctnr(CONTAINER ctnr, INDEX pos);
114
115/**
116 * @return The position of a matching entry.
117 *
118 * @param compare_func A Pointer to the function that is
119 * called to compare all entries in the
120 * container with the given pattern.
121 * @param pattern The pattern for coparison.
122 */
123INDEX search_ctnr(CONTAINER ctnr, COMPARE_FUNC compare_func, void* pattern);
124
125/**
126 * Swap two objects in container.
127 *
128 * @param pos1 Position of the first object.
129 * @param pos2 Position of the second object.
130 */
131void swap_ctnr(CONTAINER ctnr, INDEX pos1, INDEX pos2);
132
133/**
134 * Sort all entries of container.
135 *
136 * @param compare_func A Pointer to the function that is
137 * called to compare to entries of the
138 * container.
139 */
140void bsort_ctnr(CONTAINER ctnr, COMPARE_FUNC compare_func);
141
142/**
143 * Use this function to iterate over the container.
144 *
145 * for (ptr = first_ctnr(ctnr); ptr; ptr = next_ctnr(ctnr)) {
146 * do_anything(ptr);
147 * }
148 *
149 * @return A Pointer to the first object in container.
150 */
151void* first_ctnr(CONTAINER ctnr);
152
153/**
154 * Use this function to iterate over the container.
155 *
156 * @return A Pointer to the next object in container.
157 */
158void* next_ctnr(CONTAINER ctnr);
159
160/**
161 * Use this function to remove the current entry while
162 * iterating over the container.
163 *
164 * @return A Pointer to the removed object or @p 0L if it doesn't exist.
165 */
166void* remove_ctnr(CONTAINER ctnr);
167
168#endif
169