1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
3 *
4 * SPDX-License-Identifier: LGPL-2.1-or-later
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 */
19
20 /*
21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GLib Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GLib at ftp://ftp.gtk.org/pub/gtk/.
25 */
26
27 #ifndef __G_ARRAY_H__
28 #define __G_ARRAY_H__
29
30 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
31 #error "Only <glib.h> can be included directly."
32 #endif
33
34 #include <glib/gtypes.h>
35
36 G_BEGIN_DECLS
37
38 typedef struct _GBytes GBytes;
39 typedef struct _GArray GArray;
40 typedef struct _GByteArray GByteArray;
41 typedef struct _GPtrArray GPtrArray;
42
43 struct _GArray
44 {
45 gchar *data;
46 guint len;
47 };
48
49 struct _GByteArray
50 {
51 guint8 *data;
52 guint len;
53 };
54
55 struct _GPtrArray
56 {
57 gpointer *pdata;
58 guint len;
59 };
60
61 /* Resizable arrays. remove fills any cleared spot and shortens the
62 * array, while preserving the order. remove_fast will distort the
63 * order by moving the last element to the position of the removed.
64 */
65
66 #define g_array_append_val(a,v) g_array_append_vals (a, &(v), 1)
67 #define g_array_prepend_val(a,v) g_array_prepend_vals (a, &(v), 1)
68 #define g_array_insert_val(a,i,v) g_array_insert_vals (a, i, &(v), 1)
69 #define g_array_index(a,t,i) (((t*) (void *) (a)->data) [(i)])
70
71 GLIB_AVAILABLE_IN_ALL
72 GArray* g_array_new (gboolean zero_terminated,
73 gboolean clear_,
74 guint element_size);
75 GLIB_AVAILABLE_IN_2_76
76 GArray* g_array_new_take (gpointer data,
77 gsize len,
78 gboolean clear,
79 gsize element_size);
80 GLIB_AVAILABLE_IN_2_76
81 GArray* g_array_new_take_zero_terminated (gpointer data,
82 gboolean clear,
83 gsize element_size);
84 GLIB_AVAILABLE_IN_2_64
85 gpointer g_array_steal (GArray *array,
86 gsize *len);
87 GLIB_AVAILABLE_IN_ALL
88 GArray* g_array_sized_new (gboolean zero_terminated,
89 gboolean clear_,
90 guint element_size,
91 guint reserved_size);
92 GLIB_AVAILABLE_IN_2_62
93 GArray* g_array_copy (GArray *array);
94 GLIB_AVAILABLE_IN_ALL
95 gchar* g_array_free (GArray *array,
96 gboolean free_segment);
97 GLIB_AVAILABLE_IN_ALL
98 GArray *g_array_ref (GArray *array);
99 GLIB_AVAILABLE_IN_ALL
100 void g_array_unref (GArray *array);
101 GLIB_AVAILABLE_IN_ALL
102 guint g_array_get_element_size (GArray *array);
103 GLIB_AVAILABLE_IN_ALL
104 GArray* g_array_append_vals (GArray *array,
105 gconstpointer data,
106 guint len);
107 GLIB_AVAILABLE_IN_ALL
108 GArray* g_array_prepend_vals (GArray *array,
109 gconstpointer data,
110 guint len);
111 GLIB_AVAILABLE_IN_ALL
112 GArray* g_array_insert_vals (GArray *array,
113 guint index_,
114 gconstpointer data,
115 guint len);
116 GLIB_AVAILABLE_IN_ALL
117 GArray* g_array_set_size (GArray *array,
118 guint length);
119 GLIB_AVAILABLE_IN_ALL
120 GArray* g_array_remove_index (GArray *array,
121 guint index_);
122 GLIB_AVAILABLE_IN_ALL
123 GArray* g_array_remove_index_fast (GArray *array,
124 guint index_);
125 GLIB_AVAILABLE_IN_ALL
126 GArray* g_array_remove_range (GArray *array,
127 guint index_,
128 guint length);
129 GLIB_AVAILABLE_IN_ALL
130 void g_array_sort (GArray *array,
131 GCompareFunc compare_func);
132 GLIB_AVAILABLE_IN_ALL
133 void g_array_sort_with_data (GArray *array,
134 GCompareDataFunc compare_func,
135 gpointer user_data);
136 GLIB_AVAILABLE_IN_2_62
137 gboolean g_array_binary_search (GArray *array,
138 gconstpointer target,
139 GCompareFunc compare_func,
140 guint *out_match_index);
141 GLIB_AVAILABLE_IN_ALL
142 void g_array_set_clear_func (GArray *array,
143 GDestroyNotify clear_func);
144
145 /* Resizable pointer array. This interface is much less complicated
146 * than the above. Add appends a pointer. Remove fills any cleared
147 * spot and shortens the array. remove_fast will again distort order.
148 */
149 #define g_ptr_array_index(array,index_) ((array)->pdata)[index_]
150 GLIB_AVAILABLE_IN_ALL
151 GPtrArray* g_ptr_array_new (void);
152 GLIB_AVAILABLE_IN_ALL
153 GPtrArray* g_ptr_array_new_with_free_func (GDestroyNotify element_free_func);
154 GLIB_AVAILABLE_IN_2_76
155 GPtrArray* g_ptr_array_new_take (gpointer *data,
156 gsize len,
157 GDestroyNotify element_free_func);
158 GLIB_AVAILABLE_IN_2_76
159 GPtrArray* g_ptr_array_new_from_array (gpointer *data,
160 gsize len,
161 GCopyFunc copy_func,
162 gpointer copy_func_user_data,
163 GDestroyNotify element_free_func);
164 GLIB_AVAILABLE_IN_2_64
165 gpointer* g_ptr_array_steal (GPtrArray *array,
166 gsize *len);
167 GLIB_AVAILABLE_IN_2_62
168 GPtrArray *g_ptr_array_copy (GPtrArray *array,
169 GCopyFunc func,
170 gpointer user_data);
171 GLIB_AVAILABLE_IN_ALL
172 GPtrArray* g_ptr_array_sized_new (guint reserved_size);
173 GLIB_AVAILABLE_IN_ALL
174 GPtrArray* g_ptr_array_new_full (guint reserved_size,
175 GDestroyNotify element_free_func);
176 GLIB_AVAILABLE_IN_2_74
177 GPtrArray* g_ptr_array_new_null_terminated (guint reserved_size,
178 GDestroyNotify element_free_func,
179 gboolean null_terminated);
180 GLIB_AVAILABLE_IN_2_76
181 GPtrArray* g_ptr_array_new_take_null_terminated (gpointer *data,
182 GDestroyNotify element_free_func);
183 GLIB_AVAILABLE_IN_2_76
184 GPtrArray* g_ptr_array_new_from_null_terminated_array (gpointer *data,
185 GCopyFunc copy_func,
186 gpointer copy_func_user_data,
187 GDestroyNotify element_free_func);
188 GLIB_AVAILABLE_IN_ALL
189 gpointer* g_ptr_array_free (GPtrArray *array,
190 gboolean free_seg);
191 GLIB_AVAILABLE_IN_ALL
192 GPtrArray* g_ptr_array_ref (GPtrArray *array);
193 GLIB_AVAILABLE_IN_ALL
194 void g_ptr_array_unref (GPtrArray *array);
195 GLIB_AVAILABLE_IN_ALL
196 void g_ptr_array_set_free_func (GPtrArray *array,
197 GDestroyNotify element_free_func);
198 GLIB_AVAILABLE_IN_ALL
199 void g_ptr_array_set_size (GPtrArray *array,
200 gint length);
201 GLIB_AVAILABLE_IN_ALL
202 gpointer g_ptr_array_remove_index (GPtrArray *array,
203 guint index_);
204 GLIB_AVAILABLE_IN_ALL
205 gpointer g_ptr_array_remove_index_fast (GPtrArray *array,
206 guint index_);
207 GLIB_AVAILABLE_IN_2_58
208 gpointer g_ptr_array_steal_index (GPtrArray *array,
209 guint index_);
210 GLIB_AVAILABLE_IN_2_58
211 gpointer g_ptr_array_steal_index_fast (GPtrArray *array,
212 guint index_);
213 GLIB_AVAILABLE_IN_ALL
214 gboolean g_ptr_array_remove (GPtrArray *array,
215 gpointer data);
216 GLIB_AVAILABLE_IN_ALL
217 gboolean g_ptr_array_remove_fast (GPtrArray *array,
218 gpointer data);
219 GLIB_AVAILABLE_IN_ALL
220 GPtrArray *g_ptr_array_remove_range (GPtrArray *array,
221 guint index_,
222 guint length);
223 GLIB_AVAILABLE_IN_ALL
224 void g_ptr_array_add (GPtrArray *array,
225 gpointer data);
226 GLIB_AVAILABLE_IN_2_62
227 void g_ptr_array_extend (GPtrArray *array_to_extend,
228 GPtrArray *array,
229 GCopyFunc func,
230 gpointer user_data);
231 GLIB_AVAILABLE_IN_2_62
232 void g_ptr_array_extend_and_steal (GPtrArray *array_to_extend,
233 GPtrArray *array);
234 GLIB_AVAILABLE_IN_2_40
235 void g_ptr_array_insert (GPtrArray *array,
236 gint index_,
237 gpointer data);
238 GLIB_AVAILABLE_IN_ALL
239 void g_ptr_array_sort (GPtrArray *array,
240 GCompareFunc compare_func);
241 GLIB_AVAILABLE_IN_ALL
242 void g_ptr_array_sort_with_data (GPtrArray *array,
243 GCompareDataFunc compare_func,
244 gpointer user_data);
245 GLIB_AVAILABLE_IN_2_76
246 void g_ptr_array_sort_values (GPtrArray *array,
247 GCompareFunc compare_func);
248 GLIB_AVAILABLE_IN_2_76
249 void g_ptr_array_sort_values_with_data (GPtrArray *array,
250 GCompareDataFunc compare_func,
251 gpointer user_data);
252 GLIB_AVAILABLE_IN_ALL
253 void g_ptr_array_foreach (GPtrArray *array,
254 GFunc func,
255 gpointer user_data);
256 GLIB_AVAILABLE_IN_2_54
257 gboolean g_ptr_array_find (GPtrArray *haystack,
258 gconstpointer needle,
259 guint *index_);
260 GLIB_AVAILABLE_IN_2_54
261 gboolean g_ptr_array_find_with_equal_func (GPtrArray *haystack,
262 gconstpointer needle,
263 GEqualFunc equal_func,
264 guint *index_);
265
266 GLIB_AVAILABLE_IN_2_74
267 gboolean g_ptr_array_is_null_terminated (GPtrArray *array);
268
269 /* Byte arrays, an array of guint8. Implemented as a GArray,
270 * but type-safe.
271 */
272
273 GLIB_AVAILABLE_IN_ALL
274 GByteArray* g_byte_array_new (void);
275 GLIB_AVAILABLE_IN_ALL
276 GByteArray* g_byte_array_new_take (guint8 *data,
277 gsize len);
278 GLIB_AVAILABLE_IN_2_64
279 guint8* g_byte_array_steal (GByteArray *array,
280 gsize *len);
281 GLIB_AVAILABLE_IN_ALL
282 GByteArray* g_byte_array_sized_new (guint reserved_size);
283 GLIB_AVAILABLE_IN_ALL
284 guint8* g_byte_array_free (GByteArray *array,
285 gboolean free_segment);
286 GLIB_AVAILABLE_IN_ALL
287 GBytes* g_byte_array_free_to_bytes (GByteArray *array);
288 GLIB_AVAILABLE_IN_ALL
289 GByteArray *g_byte_array_ref (GByteArray *array);
290 GLIB_AVAILABLE_IN_ALL
291 void g_byte_array_unref (GByteArray *array);
292 GLIB_AVAILABLE_IN_ALL
293 GByteArray* g_byte_array_append (GByteArray *array,
294 const guint8 *data,
295 guint len);
296 GLIB_AVAILABLE_IN_ALL
297 GByteArray* g_byte_array_prepend (GByteArray *array,
298 const guint8 *data,
299 guint len);
300 GLIB_AVAILABLE_IN_ALL
301 GByteArray* g_byte_array_set_size (GByteArray *array,
302 guint length);
303 GLIB_AVAILABLE_IN_ALL
304 GByteArray* g_byte_array_remove_index (GByteArray *array,
305 guint index_);
306 GLIB_AVAILABLE_IN_ALL
307 GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
308 guint index_);
309 GLIB_AVAILABLE_IN_ALL
310 GByteArray* g_byte_array_remove_range (GByteArray *array,
311 guint index_,
312 guint length);
313 GLIB_AVAILABLE_IN_ALL
314 void g_byte_array_sort (GByteArray *array,
315 GCompareFunc compare_func);
316 GLIB_AVAILABLE_IN_ALL
317 void g_byte_array_sort_with_data (GByteArray *array,
318 GCompareDataFunc compare_func,
319 gpointer user_data);
320
321 G_END_DECLS
322
323 #endif /* __G_ARRAY_H__ */