Branch data Line data Source code
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 : : /*
28 : : * MT safe
29 : : */
30 : :
31 : : #include "config.h"
32 : :
33 : : #include <string.h>
34 : : #include <stdlib.h>
35 : :
36 : : #include "garray.h"
37 : :
38 : : #include "galloca.h"
39 : : #include "gbytes.h"
40 : : #include "ghash.h"
41 : : #include "gslice.h"
42 : : #include "gmem.h"
43 : : #include "gtestutils.h"
44 : : #include "gthread.h"
45 : : #include "gmessages.h"
46 : : #include "gqsort.h"
47 : : #include "grefcount.h"
48 : : #include "gutilsprivate.h"
49 : :
50 : : #define MIN_ARRAY_SIZE 16
51 : :
52 : : typedef struct _GRealArray GRealArray;
53 : :
54 : : /**
55 : : * GArray:
56 : : * @data: a pointer to the element data. The data may be moved as
57 : : * elements are added to the #GArray.
58 : : * @len: the number of elements in the #GArray not including the
59 : : * possible terminating zero element.
60 : : *
61 : : * Contains the public fields of a GArray.
62 : : */
63 : : struct _GRealArray
64 : : {
65 : : guint8 *data;
66 : : guint len;
67 : : guint elt_capacity;
68 : : guint elt_size;
69 : : guint zero_terminated : 1;
70 : : guint clear : 1;
71 : : gatomicrefcount ref_count;
72 : : GDestroyNotify clear_func;
73 : : };
74 : :
75 : : /**
76 : : * g_array_index:
77 : : * @a: a #GArray
78 : : * @t: the type of the elements
79 : : * @i: the index of the element to return
80 : : *
81 : : * Returns the element of a #GArray at the given index. The return
82 : : * value is cast to the given type. This is the main way to read or write an
83 : : * element in a #GArray.
84 : : *
85 : : * Writing an element is typically done by reference, as in the following
86 : : * example. This example gets a pointer to an element in a #GArray, and then
87 : : * writes to a field in it:
88 : : * |[<!-- language="C" -->
89 : : * EDayViewEvent *event;
90 : : * // This gets a pointer to the 4th element in the array of
91 : : * // EDayViewEvent structs.
92 : : * event = &g_array_index (events, EDayViewEvent, 3);
93 : : * event->start_time = g_get_current_time ();
94 : : * ]|
95 : : *
96 : : * This example reads from and writes to an array of integers:
97 : : * |[<!-- language="C" -->
98 : : * g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint));
99 : : * for (guint i = 0; i < 10; i++)
100 : : * g_array_append_val (int_array, i);
101 : : *
102 : : * guint *my_int = &g_array_index (int_array, guint, 1);
103 : : * g_print ("Int at index 1 is %u; decrementing it\n", *my_int);
104 : : * *my_int = *my_int - 1;
105 : : * ]|
106 : : *
107 : : * Returns: the element of the #GArray at the index given by @i
108 : : */
109 : :
110 : : #define g_array_elt_len(array,i) ((gsize)(array)->elt_size * (i))
111 : : #define g_array_elt_pos(array,i) ((array)->data + g_array_elt_len((array),(i)))
112 : : #define g_array_elt_zero(array, pos, len) \
113 : : (memset (g_array_elt_pos ((array), pos), 0, g_array_elt_len ((array), len)))
114 : : #define g_array_zero_terminate(array) G_STMT_START{ \
115 : : if ((array)->zero_terminated) \
116 : : g_array_elt_zero ((array), (array)->len, 1); \
117 : : }G_STMT_END
118 : :
119 : : static void g_array_maybe_expand (GRealArray *array,
120 : : guint len);
121 : :
122 : : /**
123 : : * g_array_new:
124 : : * @zero_terminated: %TRUE if the array should have an extra element at
125 : : * the end which is set to 0
126 : : * @clear_: %TRUE if #GArray elements should be automatically cleared
127 : : * to 0 when they are allocated
128 : : * @element_size: the size of each element in bytes
129 : : *
130 : : * Creates a new #GArray with a reference count of 1.
131 : : *
132 : : * Returns: the new #GArray
133 : : */
134 : : GArray*
135 : 7235 : g_array_new (gboolean zero_terminated,
136 : : gboolean clear,
137 : : guint elt_size)
138 : : {
139 : 7235 : g_return_val_if_fail (elt_size > 0, NULL);
140 : : #if (UINT_WIDTH / 8) >= GLIB_SIZEOF_SIZE_T
141 : : g_return_val_if_fail (elt_size <= G_MAXSIZE / 2 - 1, NULL);
142 : : #endif
143 : :
144 : 7235 : return g_array_sized_new (zero_terminated, clear, elt_size, 0);
145 : : }
146 : :
147 : : /**
148 : : * g_array_new_take: (skip)
149 : : * @data: (array length=len) (transfer full) (nullable): an array of
150 : : * elements of @element_size, or %NULL for an empty array
151 : : * @len: the number of elements in @data
152 : : * @clear: %TRUE if #GArray elements should be automatically cleared
153 : : * to 0 when they are allocated
154 : : * @element_size: the size of each element in bytes
155 : : *
156 : : * Creates a new #GArray with @data as array data, @len as length and a
157 : : * reference count of 1.
158 : : *
159 : : * This avoids having to copy the data manually, when it can just be
160 : : * inherited.
161 : : * After this call, @data belongs to the #GArray and may no longer be
162 : : * modified by the caller. The memory of @data has to be dynamically
163 : : * allocated and will eventually be freed with g_free().
164 : : *
165 : : * In case the elements need to be cleared when the array is freed, use
166 : : * g_array_set_clear_func() to set a #GDestroyNotify function to perform
167 : : * such task.
168 : : *
169 : : * Do not use it if @len or @element_size are greater than %G_MAXUINT.
170 : : * #GArray stores the length of its data in #guint, which may be shorter
171 : : * than #gsize.
172 : : *
173 : : * Returns: (transfer full): A new #GArray
174 : : *
175 : : * Since: 2.76
176 : : */
177 : : GArray *
178 : 5 : g_array_new_take (gpointer data,
179 : : gsize len,
180 : : gboolean clear,
181 : : gsize element_size)
182 : : {
183 : : GRealArray *rarray;
184 : : GArray *array;
185 : :
186 : 5 : g_return_val_if_fail (data != NULL || len == 0, NULL);
187 : 5 : g_return_val_if_fail (len <= G_MAXUINT, NULL);
188 : 5 : g_return_val_if_fail (element_size <= G_MAXUINT, NULL);
189 : :
190 : 5 : array = g_array_sized_new (FALSE, clear, element_size, 0);
191 : 5 : rarray = (GRealArray *) array;
192 : 5 : rarray->data = (guint8 *) g_steal_pointer (&data);
193 : 5 : rarray->len = len;
194 : 5 : rarray->elt_capacity = len;
195 : :
196 : 5 : return array;
197 : : }
198 : :
199 : : /**
200 : : * g_array_new_take_zero_terminated: (skip)
201 : : * @data: (array zero-terminated=1): an array of elements of @element_size
202 : : * @clear: %TRUE if #GArray elements should be automatically cleared
203 : : * to 0 when they are allocated
204 : : * @element_size: the size of each element in bytes
205 : : *
206 : : * Creates a new #GArray with @data as array data, computing the length of it
207 : : * and setting the reference count to 1.
208 : : *
209 : : * This avoids having to copy the data manually, when it can just be
210 : : * inherited.
211 : : * After this call, @data belongs to the #GArray and may no longer be
212 : : * modified by the caller. The memory of @data has to be dynamically
213 : : * allocated and will eventually be freed with g_free().
214 : : *
215 : : * The length is calculated by iterating through @data until the first %NULL
216 : : * element is found.
217 : : *
218 : : * In case the elements need to be cleared when the array is freed, use
219 : : * g_array_set_clear_func() to set a #GDestroyNotify function to perform
220 : : * such task.
221 : : *
222 : : * Do not use it if @data length or @element_size are greater than %G_MAXUINT.
223 : : * #GArray stores the length of its data in #guint, which may be shorter
224 : : * than #gsize.
225 : : *
226 : : * Returns: (transfer full): A new #GArray
227 : : *
228 : : * Since: 2.76
229 : : */
230 : : GArray *
231 : 2 : g_array_new_take_zero_terminated (gpointer data,
232 : : gboolean clear,
233 : : gsize element_size)
234 : : {
235 : : GArray *array;
236 : 2 : gsize len = 0;
237 : :
238 : 2 : g_return_val_if_fail (element_size <= G_MAXUINT, NULL);
239 : :
240 : 2 : if (data != NULL)
241 : : {
242 : 2 : guint8 *array_data = data;
243 : :
244 : 2 : for (gsize i = 0; ; ++i)
245 : 10255 : {
246 : 10257 : const guint8 *element_start = array_data + (i * element_size);
247 : :
248 : 10257 : if (*element_start == 0 &&
249 : 41 : memcmp (element_start, element_start + 1, element_size - 1) == 0)
250 : 2 : break;
251 : :
252 : 10255 : len += 1;
253 : : }
254 : : }
255 : :
256 : 2 : g_return_val_if_fail (len <= G_MAXUINT, NULL);
257 : :
258 : 2 : array = g_array_new_take (data, len, clear, element_size);
259 : 2 : ((GRealArray *)array)->zero_terminated = TRUE;
260 : :
261 : 2 : return array;
262 : : }
263 : :
264 : : /**
265 : : * g_array_steal:
266 : : * @array: a #GArray.
267 : : * @len: (optional) (out): pointer to retrieve the number of
268 : : * elements of the original array
269 : : *
270 : : * Frees the data in the array and resets the size to zero, while
271 : : * the underlying array is preserved for use elsewhere and returned
272 : : * to the caller.
273 : : *
274 : : * If the array was created with the @zero_terminate property
275 : : * set to %TRUE, the returned data is zero terminated too.
276 : : *
277 : : * If array elements contain dynamically-allocated memory,
278 : : * the array elements should also be freed by the caller.
279 : : *
280 : : * A short example of use:
281 : : * |[<!-- language="C" -->
282 : : * ...
283 : : * gpointer data;
284 : : * gsize data_len;
285 : : * data = g_array_steal (some_array, &data_len);
286 : : * ...
287 : : * ]|
288 : :
289 : : * Returns: (transfer full): the element data, which should be
290 : : * freed using g_free().
291 : : *
292 : : * Since: 2.64
293 : : */
294 : : gpointer
295 : 8 : g_array_steal (GArray *array,
296 : : gsize *len)
297 : : {
298 : : GRealArray *rarray;
299 : : gpointer segment;
300 : :
301 : 8 : g_return_val_if_fail (array != NULL, NULL);
302 : :
303 : 8 : rarray = (GRealArray *) array;
304 : 8 : segment = (gpointer) rarray->data;
305 : :
306 : 8 : if (len != NULL)
307 : 6 : *len = rarray->len;
308 : :
309 : 8 : rarray->data = NULL;
310 : 8 : rarray->len = 0;
311 : 8 : rarray->elt_capacity = 0;
312 : 8 : return segment;
313 : : }
314 : :
315 : : /**
316 : : * g_array_sized_new:
317 : : * @zero_terminated: %TRUE if the array should have an extra element at
318 : : * the end with all bits cleared
319 : : * @clear_: %TRUE if all bits in the array should be cleared to 0 on
320 : : * allocation
321 : : * @element_size: size of each element in the array
322 : : * @reserved_size: number of elements preallocated
323 : : *
324 : : * Creates a new #GArray with @reserved_size elements preallocated and
325 : : * a reference count of 1. This avoids frequent reallocation, if you
326 : : * are going to add many elements to the array. Note however that the
327 : : * size of the array is still 0.
328 : : *
329 : : * Returns: the new #GArray
330 : : */
331 : : GArray*
332 : 7859 : g_array_sized_new (gboolean zero_terminated,
333 : : gboolean clear,
334 : : guint elt_size,
335 : : guint reserved_size)
336 : : {
337 : : GRealArray *array;
338 : :
339 : 7859 : g_return_val_if_fail (elt_size > 0, NULL);
340 : : #if (UINT_WIDTH / 8) >= GLIB_SIZEOF_SIZE_T
341 : : g_return_val_if_fail (elt_size <= G_MAXSIZE / 2 - 1, NULL);
342 : : #endif
343 : :
344 : 7859 : array = g_slice_new (GRealArray);
345 : :
346 : 7859 : array->data = NULL;
347 : 7859 : array->len = 0;
348 : 7859 : array->elt_capacity = 0;
349 : 7859 : array->zero_terminated = (zero_terminated ? 1 : 0);
350 : 7859 : array->clear = (clear ? 1 : 0);
351 : 7859 : array->elt_size = elt_size;
352 : 7859 : array->clear_func = NULL;
353 : :
354 : 7859 : g_atomic_ref_count_init (&array->ref_count);
355 : :
356 : 7859 : if (array->zero_terminated || reserved_size != 0)
357 : : {
358 : 236 : g_array_maybe_expand (array, reserved_size);
359 : 236 : g_assert (array->data != NULL);
360 : 236 : g_array_zero_terminate (array);
361 : : }
362 : :
363 : 7859 : return (GArray*) array;
364 : : }
365 : :
366 : : /**
367 : : * g_array_set_clear_func:
368 : : * @array: A #GArray
369 : : * @clear_func: a function to clear an element of @array
370 : : *
371 : : * Sets a function to clear an element of @array.
372 : : *
373 : : * The @clear_func will be called when an element in the array
374 : : * data segment is removed and when the array is freed and data
375 : : * segment is deallocated as well. @clear_func will be passed a
376 : : * pointer to the element to clear, rather than the element itself.
377 : : *
378 : : * Note that in contrast with other uses of #GDestroyNotify
379 : : * functions, @clear_func is expected to clear the contents of
380 : : * the array element it is given, but not free the element itself.
381 : : *
382 : : * |[<!-- language="C" -->
383 : : * typedef struct
384 : : * {
385 : : * gchar *str;
386 : : * GObject *obj;
387 : : * } ArrayElement;
388 : : *
389 : : * static void
390 : : * array_element_clear (ArrayElement *element)
391 : : * {
392 : : * g_clear_pointer (&element->str, g_free);
393 : : * g_clear_object (&element->obj);
394 : : * }
395 : : *
396 : : * // main code
397 : : * GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement));
398 : : * g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear);
399 : : * // assign data to the structure
400 : : * g_array_free (garray, TRUE);
401 : : * ]|
402 : : *
403 : : * Since: 2.32
404 : : */
405 : : void
406 : 11 : g_array_set_clear_func (GArray *array,
407 : : GDestroyNotify clear_func)
408 : : {
409 : 11 : GRealArray *rarray = (GRealArray *) array;
410 : :
411 : 11 : g_return_if_fail (array != NULL);
412 : :
413 : 11 : rarray->clear_func = clear_func;
414 : : }
415 : :
416 : : /**
417 : : * g_array_ref:
418 : : * @array: A #GArray
419 : : *
420 : : * Atomically increments the reference count of @array by one.
421 : : * This function is thread-safe and may be called from any thread.
422 : : *
423 : : * Returns: The passed in #GArray
424 : : *
425 : : * Since: 2.22
426 : : */
427 : : GArray *
428 : 6 : g_array_ref (GArray *array)
429 : : {
430 : 6 : GRealArray *rarray = (GRealArray*) array;
431 : 6 : g_return_val_if_fail (array, NULL);
432 : :
433 : 6 : g_atomic_ref_count_inc (&rarray->ref_count);
434 : :
435 : 6 : return array;
436 : : }
437 : :
438 : : typedef enum
439 : : {
440 : : FREE_SEGMENT = 1 << 0,
441 : : PRESERVE_WRAPPER = 1 << 1
442 : : } ArrayFreeFlags;
443 : :
444 : : static gchar *array_free (GRealArray *, ArrayFreeFlags);
445 : :
446 : : /**
447 : : * g_array_unref:
448 : : * @array: A #GArray
449 : : *
450 : : * Atomically decrements the reference count of @array by one. If the
451 : : * reference count drops to 0, all memory allocated by the array is
452 : : * released. This function is thread-safe and may be called from any
453 : : * thread.
454 : : *
455 : : * Since: 2.22
456 : : */
457 : : void
458 : 141 : g_array_unref (GArray *array)
459 : : {
460 : 141 : GRealArray *rarray = (GRealArray*) array;
461 : 141 : g_return_if_fail (array);
462 : :
463 : 141 : if (g_atomic_ref_count_dec (&rarray->ref_count))
464 : 137 : array_free (rarray, FREE_SEGMENT);
465 : : }
466 : :
467 : : /**
468 : : * g_array_get_element_size:
469 : : * @array: A #GArray
470 : : *
471 : : * Gets the size of the elements in @array.
472 : : *
473 : : * Returns: Size of each element, in bytes
474 : : *
475 : : * Since: 2.22
476 : : */
477 : : guint
478 : 1 : g_array_get_element_size (GArray *array)
479 : : {
480 : 1 : GRealArray *rarray = (GRealArray*) array;
481 : :
482 : 1 : g_return_val_if_fail (array, 0);
483 : :
484 : 1 : return rarray->elt_size;
485 : : }
486 : :
487 : : /**
488 : : * g_array_free:
489 : : * @array: a #GArray
490 : : * @free_segment: if %TRUE the actual element data is freed as well
491 : : *
492 : : * Frees the memory allocated for the #GArray. If @free_segment is
493 : : * %TRUE it frees the memory block holding the elements as well. Pass
494 : : * %FALSE if you want to free the #GArray wrapper but preserve the
495 : : * underlying array for use elsewhere. If the reference count of
496 : : * @array is greater than one, the #GArray wrapper is preserved but
497 : : * the size of @array will be set to zero.
498 : : *
499 : : * If array contents point to dynamically-allocated memory, they should
500 : : * be freed separately if @free_seg is %TRUE and no @clear_func
501 : : * function has been set for @array.
502 : : *
503 : : * This function is not thread-safe. If using a #GArray from multiple
504 : : * threads, use only the atomic g_array_ref() and g_array_unref()
505 : : * functions.
506 : : *
507 : : * Returns: the element data if @free_segment is %FALSE, otherwise
508 : : * %NULL. The element data should be freed using g_free().
509 : : */
510 : : gchar*
511 : 7661 : g_array_free (GArray *farray,
512 : : gboolean free_segment)
513 : : {
514 : 7661 : GRealArray *array = (GRealArray*) farray;
515 : : ArrayFreeFlags flags;
516 : :
517 : 7661 : g_return_val_if_fail (array, NULL);
518 : :
519 : 7661 : flags = (free_segment ? FREE_SEGMENT : 0);
520 : :
521 : : /* if others are holding a reference, preserve the wrapper but do free/return the data */
522 : 7661 : if (!g_atomic_ref_count_dec (&array->ref_count))
523 : 2 : flags |= PRESERVE_WRAPPER;
524 : :
525 : 7661 : return array_free (array, flags);
526 : : }
527 : :
528 : : static gchar *
529 : 7798 : array_free (GRealArray *array,
530 : : ArrayFreeFlags flags)
531 : : {
532 : : gchar *segment;
533 : :
534 : 7798 : if (flags & FREE_SEGMENT)
535 : : {
536 : 7204 : if (array->clear_func != NULL)
537 : : {
538 : : guint i;
539 : :
540 : 125 : for (i = 0; i < array->len; i++)
541 : 114 : array->clear_func (g_array_elt_pos (array, i));
542 : : }
543 : :
544 : 7204 : g_free (array->data);
545 : 7204 : segment = NULL;
546 : : }
547 : : else
548 : 594 : segment = (gchar*) array->data;
549 : :
550 : 7798 : if (flags & PRESERVE_WRAPPER)
551 : : {
552 : 2 : array->data = NULL;
553 : 2 : array->len = 0;
554 : 2 : array->elt_capacity = 0;
555 : : }
556 : : else
557 : : {
558 : 7796 : g_slice_free1 (sizeof (GRealArray), array);
559 : : }
560 : :
561 : 7798 : return segment;
562 : : }
563 : :
564 : : /**
565 : : * g_array_append_vals:
566 : : * @array: a #GArray
567 : : * @data: (not nullable): a pointer to the elements to append to the end of the array
568 : : * @len: the number of elements to append
569 : : *
570 : : * Adds @len elements onto the end of the array.
571 : : *
572 : : * Returns: the #GArray
573 : : */
574 : : /**
575 : : * g_array_append_val:
576 : : * @a: a #GArray
577 : : * @v: the value to append to the #GArray
578 : : *
579 : : * Adds the value on to the end of the array. The array will grow in
580 : : * size automatically if necessary.
581 : : *
582 : : * g_array_append_val() is a macro which uses a reference to the value
583 : : * parameter @v. This means that you cannot use it with literal values
584 : : * such as "27". You must use variables.
585 : : *
586 : : * Returns: the #GArray
587 : : */
588 : : GArray*
589 : 277928 : g_array_append_vals (GArray *farray,
590 : : gconstpointer data,
591 : : guint len)
592 : : {
593 : 277928 : GRealArray *array = (GRealArray*) farray;
594 : :
595 : 277928 : g_return_val_if_fail (array, NULL);
596 : :
597 : 277928 : if (len == 0)
598 : 5 : return farray;
599 : :
600 : 277923 : g_array_maybe_expand (array, len);
601 : :
602 : 277923 : memcpy (g_array_elt_pos (array, array->len), data,
603 : 277923 : g_array_elt_len (array, len));
604 : :
605 : 277923 : array->len += len;
606 : :
607 : 277923 : g_array_zero_terminate (array);
608 : :
609 : 277923 : return farray;
610 : : }
611 : :
612 : : /**
613 : : * g_array_prepend_vals:
614 : : * @array: a #GArray
615 : : * @data: (nullable): a pointer to the elements to prepend to the start of the array
616 : : * @len: the number of elements to prepend, which may be zero
617 : : *
618 : : * Adds @len elements onto the start of the array.
619 : : *
620 : : * @data may be %NULL if (and only if) @len is zero. If @len is zero, this
621 : : * function is a no-op.
622 : : *
623 : : * This operation is slower than g_array_append_vals() since the
624 : : * existing elements in the array have to be moved to make space for
625 : : * the new elements.
626 : : *
627 : : * Returns: the #GArray
628 : : */
629 : : /**
630 : : * g_array_prepend_val:
631 : : * @a: a #GArray
632 : : * @v: the value to prepend to the #GArray
633 : : *
634 : : * Adds the value on to the start of the array. The array will grow in
635 : : * size automatically if necessary.
636 : : *
637 : : * This operation is slower than g_array_append_val() since the
638 : : * existing elements in the array have to be moved to make space for
639 : : * the new element.
640 : : *
641 : : * g_array_prepend_val() is a macro which uses a reference to the value
642 : : * parameter @v. This means that you cannot use it with literal values
643 : : * such as "27". You must use variables.
644 : : *
645 : : * Returns: the #GArray
646 : : */
647 : : GArray*
648 : 10523 : g_array_prepend_vals (GArray *farray,
649 : : gconstpointer data,
650 : : guint len)
651 : : {
652 : 10523 : GRealArray *array = (GRealArray*) farray;
653 : :
654 : 10523 : g_return_val_if_fail (array, NULL);
655 : :
656 : 10523 : if (len == 0)
657 : 8 : return farray;
658 : :
659 : 10515 : g_array_maybe_expand (array, len);
660 : :
661 : 10515 : memmove (g_array_elt_pos (array, len), g_array_elt_pos (array, 0),
662 : 10515 : g_array_elt_len (array, array->len));
663 : :
664 : 10515 : memcpy (g_array_elt_pos (array, 0), data, g_array_elt_len (array, len));
665 : :
666 : 10515 : array->len += len;
667 : :
668 : 10515 : g_array_zero_terminate (array);
669 : :
670 : 10515 : return farray;
671 : : }
672 : :
673 : : /**
674 : : * g_array_insert_vals:
675 : : * @array: a #GArray
676 : : * @index_: the index to place the elements at
677 : : * @data: (nullable): a pointer to the elements to insert
678 : : * @len: the number of elements to insert
679 : : *
680 : : * Inserts @len elements into a #GArray at the given index.
681 : : *
682 : : * If @index_ is greater than the array’s current length, the array is expanded.
683 : : * The elements between the old end of the array and the newly inserted elements
684 : : * will be initialised to zero if the array was configured to clear elements;
685 : : * otherwise their values will be undefined.
686 : : *
687 : : * If @index_ is less than the array’s current length, new entries will be
688 : : * inserted into the array, and the existing entries above @index_ will be moved
689 : : * upwards.
690 : : *
691 : : * @data may be %NULL if (and only if) @len is zero. If @len is zero, this
692 : : * function is a no-op.
693 : : *
694 : : * Returns: the #GArray
695 : : */
696 : : /**
697 : : * g_array_insert_val:
698 : : * @a: a #GArray
699 : : * @i: the index to place the element at
700 : : * @v: the value to insert into the array
701 : : *
702 : : * Inserts an element into an array at the given index.
703 : : *
704 : : * g_array_insert_val() is a macro which uses a reference to the value
705 : : * parameter @v. This means that you cannot use it with literal values
706 : : * such as "27". You must use variables.
707 : : *
708 : : * Returns: the #GArray
709 : : */
710 : : GArray*
711 : 6499 : g_array_insert_vals (GArray *farray,
712 : : guint index_,
713 : : gconstpointer data,
714 : : guint len)
715 : : {
716 : 6499 : GRealArray *array = (GRealArray*) farray;
717 : :
718 : 6499 : g_return_val_if_fail (array, NULL);
719 : :
720 : 6499 : if (len == 0)
721 : 8 : return farray;
722 : :
723 : : /* Is the index off the end of the array, and hence do we need to over-allocate
724 : : * and clear some elements? */
725 : 6491 : if (index_ >= array->len)
726 : : {
727 : 3004 : g_array_maybe_expand (array, index_ - array->len + len);
728 : 3004 : return g_array_append_vals (g_array_set_size (farray, index_), data, len);
729 : : }
730 : :
731 : 3487 : g_array_maybe_expand (array, len);
732 : :
733 : 3487 : memmove (g_array_elt_pos (array, len + index_),
734 : 3487 : g_array_elt_pos (array, index_),
735 : 3487 : g_array_elt_len (array, array->len - index_));
736 : :
737 : 3487 : memcpy (g_array_elt_pos (array, index_), data, g_array_elt_len (array, len));
738 : :
739 : 3487 : array->len += len;
740 : :
741 : 3487 : g_array_zero_terminate (array);
742 : :
743 : 3487 : return farray;
744 : : }
745 : :
746 : : /**
747 : : * g_array_set_size:
748 : : * @array: a #GArray
749 : : * @length: the new size of the #GArray
750 : : *
751 : : * Sets the size of the array, expanding it if necessary. If the array
752 : : * was created with @clear_ set to %TRUE, the new elements are set to 0.
753 : : *
754 : : * Returns: the #GArray
755 : : */
756 : : GArray*
757 : 6535 : g_array_set_size (GArray *farray,
758 : : guint length)
759 : : {
760 : 6535 : GRealArray *array = (GRealArray*) farray;
761 : :
762 : 6535 : g_return_val_if_fail (array, NULL);
763 : :
764 : 6535 : if (length > array->len)
765 : : {
766 : 2080 : g_array_maybe_expand (array, length - array->len);
767 : :
768 : 2080 : if (array->clear)
769 : 2071 : g_array_elt_zero (array, array->len, length - array->len);
770 : : }
771 : 4455 : else if (length < array->len)
772 : 43 : g_array_remove_range (farray, length, array->len - length);
773 : :
774 : 6535 : array->len = length;
775 : :
776 : 6535 : g_array_zero_terminate (array);
777 : :
778 : 6535 : return farray;
779 : : }
780 : :
781 : : /**
782 : : * g_array_remove_index:
783 : : * @array: a #GArray
784 : : * @index_: the index of the element to remove
785 : : *
786 : : * Removes the element at the given index from a #GArray. The following
787 : : * elements are moved down one place.
788 : : *
789 : : * Returns: the #GArray
790 : : */
791 : : GArray*
792 : 130 : g_array_remove_index (GArray *farray,
793 : : guint index_)
794 : : {
795 : 130 : GRealArray* array = (GRealArray*) farray;
796 : :
797 : 130 : g_return_val_if_fail (array, NULL);
798 : :
799 : 130 : g_return_val_if_fail (index_ < array->len, NULL);
800 : :
801 : 130 : if (array->clear_func != NULL)
802 : 1 : array->clear_func (g_array_elt_pos (array, index_));
803 : :
804 : 130 : if (index_ != array->len - 1)
805 : 32 : memmove (g_array_elt_pos (array, index_),
806 : 32 : g_array_elt_pos (array, index_ + 1),
807 : 32 : g_array_elt_len (array, array->len - index_ - 1));
808 : :
809 : 130 : array->len -= 1;
810 : :
811 : 130 : if (G_UNLIKELY (g_mem_gc_friendly))
812 : 130 : g_array_elt_zero (array, array->len, 1);
813 : : else
814 : 0 : g_array_zero_terminate (array);
815 : :
816 : 130 : return farray;
817 : : }
818 : :
819 : : /**
820 : : * g_array_remove_index_fast:
821 : : * @array: a @GArray
822 : : * @index_: the index of the element to remove
823 : : *
824 : : * Removes the element at the given index from a #GArray. The last
825 : : * element in the array is used to fill in the space, so this function
826 : : * does not preserve the order of the #GArray. But it is faster than
827 : : * g_array_remove_index().
828 : : *
829 : : * Returns: the #GArray
830 : : */
831 : : GArray*
832 : 21 : g_array_remove_index_fast (GArray *farray,
833 : : guint index_)
834 : : {
835 : 21 : GRealArray* array = (GRealArray*) farray;
836 : :
837 : 21 : g_return_val_if_fail (array, NULL);
838 : :
839 : 21 : g_return_val_if_fail (index_ < array->len, NULL);
840 : :
841 : 21 : if (array->clear_func != NULL)
842 : 1 : array->clear_func (g_array_elt_pos (array, index_));
843 : :
844 : 21 : if (index_ != array->len - 1)
845 : 21 : memcpy (g_array_elt_pos (array, index_),
846 : 21 : g_array_elt_pos (array, array->len - 1),
847 : 21 : g_array_elt_len (array, 1));
848 : :
849 : 21 : array->len -= 1;
850 : :
851 : 21 : if (G_UNLIKELY (g_mem_gc_friendly))
852 : 21 : g_array_elt_zero (array, array->len, 1);
853 : : else
854 : 0 : g_array_zero_terminate (array);
855 : :
856 : 21 : return farray;
857 : : }
858 : :
859 : : /**
860 : : * g_array_remove_range:
861 : : * @array: a @GArray
862 : : * @index_: the index of the first element to remove
863 : : * @length: the number of elements to remove
864 : : *
865 : : * Removes the given number of elements starting at the given index
866 : : * from a #GArray. The following elements are moved to close the gap.
867 : : *
868 : : * Returns: the #GArray
869 : : *
870 : : * Since: 2.4
871 : : */
872 : : GArray*
873 : 59 : g_array_remove_range (GArray *farray,
874 : : guint index_,
875 : : guint length)
876 : : {
877 : 59 : GRealArray *array = (GRealArray*) farray;
878 : :
879 : 59 : g_return_val_if_fail (array, NULL);
880 : 59 : g_return_val_if_fail (index_ <= array->len, NULL);
881 : 59 : g_return_val_if_fail (index_ <= G_MAXUINT - length, NULL);
882 : 59 : g_return_val_if_fail (index_ + length <= array->len, NULL);
883 : :
884 : 59 : if (array->clear_func != NULL)
885 : : {
886 : : guint i;
887 : :
888 : 24 : for (i = 0; i < length; i++)
889 : 22 : array->clear_func (g_array_elt_pos (array, index_ + i));
890 : : }
891 : :
892 : 59 : if (index_ + length != array->len)
893 : 6 : memmove (g_array_elt_pos (array, index_),
894 : 6 : g_array_elt_pos (array, index_ + length),
895 : 6 : (array->len - (index_ + length)) * array->elt_size);
896 : :
897 : 59 : array->len -= length;
898 : 59 : if (G_UNLIKELY (g_mem_gc_friendly))
899 : 59 : g_array_elt_zero (array, array->len, length);
900 : : else
901 : 0 : g_array_zero_terminate (array);
902 : :
903 : 59 : return farray;
904 : : }
905 : :
906 : : /**
907 : : * g_array_sort:
908 : : * @array: a #GArray
909 : : * @compare_func: comparison function
910 : : *
911 : : * Sorts a #GArray using @compare_func which should be a qsort()-style
912 : : * comparison function (returns less than zero for first arg is less
913 : : * than second arg, zero for equal, greater zero if first arg is
914 : : * greater than second arg).
915 : : *
916 : : * This is guaranteed to be a stable sort since version 2.32.
917 : : */
918 : : void
919 : 1387 : g_array_sort (GArray *farray,
920 : : GCompareFunc compare_func)
921 : : {
922 : 1387 : GRealArray *array = (GRealArray*) farray;
923 : :
924 : 1387 : g_return_if_fail (array != NULL);
925 : :
926 : : /* Don't use qsort as we want a guaranteed stable sort */
927 : 1387 : if (array->len > 0)
928 : 1383 : g_sort_array (array->data,
929 : 1383 : array->len,
930 : 1383 : array->elt_size,
931 : : (GCompareDataFunc) compare_func,
932 : : NULL);
933 : : }
934 : :
935 : : /**
936 : : * g_array_sort_with_data:
937 : : * @array: a #GArray
938 : : * @compare_func: comparison function
939 : : * @user_data: data to pass to @compare_func
940 : : *
941 : : * Like g_array_sort(), but the comparison function receives an extra
942 : : * user data argument.
943 : : *
944 : : * This is guaranteed to be a stable sort since version 2.32.
945 : : *
946 : : * There used to be a comment here about making the sort stable by
947 : : * using the addresses of the elements in the comparison function.
948 : : * This did not actually work, so any such code should be removed.
949 : : */
950 : : void
951 : 9 : g_array_sort_with_data (GArray *farray,
952 : : GCompareDataFunc compare_func,
953 : : gpointer user_data)
954 : : {
955 : 9 : GRealArray *array = (GRealArray*) farray;
956 : :
957 : 9 : g_return_if_fail (array != NULL);
958 : :
959 : 9 : if (array->len > 0)
960 : 5 : g_sort_array (array->data,
961 : 5 : array->len,
962 : 5 : array->elt_size,
963 : : compare_func,
964 : : user_data);
965 : : }
966 : :
967 : : /**
968 : : * g_array_binary_search:
969 : : * @array: a #GArray.
970 : : * @target: a pointer to the item to look up.
971 : : * @compare_func: A #GCompareFunc used to locate @target.
972 : : * @out_match_index: (optional) (out): return location
973 : : * for the index of the element, if found.
974 : : *
975 : : * Checks whether @target exists in @array by performing a binary
976 : : * search based on the given comparison function @compare_func which
977 : : * get pointers to items as arguments. If the element is found, %TRUE
978 : : * is returned and the element’s index is returned in @out_match_index
979 : : * (if non-%NULL). Otherwise, %FALSE is returned and @out_match_index
980 : : * is undefined. If @target exists multiple times in @array, the index
981 : : * of the first instance is returned. This search is using a binary
982 : : * search, so the @array must absolutely be sorted to return a correct
983 : : * result (if not, the function may produce false-negative).
984 : : *
985 : : * This example defines a comparison function and search an element in a #GArray:
986 : : * |[<!-- language="C" -->
987 : : * static gint
988 : : * cmpint (gconstpointer a, gconstpointer b)
989 : : * {
990 : : * const gint *_a = a;
991 : : * const gint *_b = b;
992 : : *
993 : : * return *_a - *_b;
994 : : * }
995 : : * ...
996 : : * gint i = 424242;
997 : : * guint matched_index;
998 : : * gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_index);
999 : : * ...
1000 : : * ]|
1001 : : *
1002 : : * Returns: %TRUE if @target is one of the elements of @array, %FALSE otherwise.
1003 : : *
1004 : : * Since: 2.62
1005 : : */
1006 : : gboolean
1007 : 20022 : g_array_binary_search (GArray *array,
1008 : : gconstpointer target,
1009 : : GCompareFunc compare_func,
1010 : : guint *out_match_index)
1011 : : {
1012 : 20022 : gboolean result = FALSE;
1013 : 20022 : GRealArray *_array = (GRealArray *) array;
1014 : 20022 : guint left, middle = 0, right;
1015 : : gint val;
1016 : :
1017 : 20022 : g_return_val_if_fail (_array != NULL, FALSE);
1018 : 20021 : g_return_val_if_fail (compare_func != NULL, FALSE);
1019 : :
1020 : 20020 : if (G_LIKELY(_array->len))
1021 : : {
1022 : 20019 : left = 0;
1023 : 20019 : right = _array->len - 1;
1024 : :
1025 : 247349 : while (left <= right)
1026 : : {
1027 : 247342 : middle = left + (right - left) / 2;
1028 : :
1029 : 247342 : val = compare_func (_array->data + (_array->elt_size * middle), target);
1030 : 247342 : if (val == 0)
1031 : : {
1032 : 20006 : result = TRUE;
1033 : 20006 : break;
1034 : : }
1035 : 227336 : else if (val < 0)
1036 : 118075 : left = middle + 1;
1037 : 109261 : else if (/* val > 0 && */ middle > 0)
1038 : 109255 : right = middle - 1;
1039 : : else
1040 : 6 : break; /* element not found */
1041 : : }
1042 : : }
1043 : :
1044 : 20020 : if (result && out_match_index != NULL)
1045 : 10000 : *out_match_index = middle;
1046 : :
1047 : 20020 : return result;
1048 : : }
1049 : :
1050 : : static void
1051 : 297245 : g_array_maybe_expand (GRealArray *array,
1052 : : guint len)
1053 : : {
1054 : : guint max_len, want_len;
1055 : :
1056 : : /* The maximum array length is derived from following constraints:
1057 : : * - The number of bytes must fit into a gsize / 2.
1058 : : * - The number of elements must fit into guint.
1059 : : * - zero terminated arrays must leave space for the terminating element
1060 : : */
1061 : 297245 : max_len = MIN (G_MAXSIZE / 2 / array->elt_size, G_MAXUINT) - array->zero_terminated;
1062 : :
1063 : : /* Detect potential overflow */
1064 : 297245 : if G_UNLIKELY ((max_len - array->len) < len)
1065 : 0 : g_error ("adding %u to array would overflow", len);
1066 : :
1067 : 297245 : want_len = array->len + len + array->zero_terminated;
1068 : 297245 : if (want_len > array->elt_capacity)
1069 : : {
1070 : 8648 : gsize want_alloc = g_nearest_pow (g_array_elt_len (array, want_len));
1071 : 8648 : g_assert (want_alloc >= g_array_elt_len (array, want_len));
1072 : 8648 : want_alloc = MAX (want_alloc, MIN_ARRAY_SIZE);
1073 : :
1074 : 8648 : array->data = g_realloc (array->data, want_alloc);
1075 : :
1076 : 8648 : if (G_UNLIKELY (g_mem_gc_friendly))
1077 : 7507 : memset (g_array_elt_pos (array, array->elt_capacity), 0,
1078 : 7507 : g_array_elt_len (array, want_len - array->elt_capacity));
1079 : :
1080 : 8648 : array->elt_capacity = MIN (want_alloc / array->elt_size, G_MAXUINT);
1081 : : }
1082 : 297245 : }
1083 : :
1084 : : typedef struct _GRealPtrArray GRealPtrArray;
1085 : :
1086 : : /**
1087 : : * GPtrArray:
1088 : : * @pdata: points to the array of pointers, which may be moved when the
1089 : : * array grows
1090 : : * @len: number of pointers in the array
1091 : : *
1092 : : * Contains the public fields of a pointer array.
1093 : : */
1094 : : struct _GRealPtrArray
1095 : : {
1096 : : gpointer *pdata;
1097 : : guint len;
1098 : : guint alloc;
1099 : : gatomicrefcount ref_count;
1100 : : guint8 null_terminated : 1; /* always either 0 or 1, so it can be added to array lengths */
1101 : : GDestroyNotify element_free_func;
1102 : : };
1103 : :
1104 : : /**
1105 : : * g_ptr_array_index:
1106 : : * @array: a #GPtrArray
1107 : : * @index_: the index of the pointer to return
1108 : : *
1109 : : * Returns the pointer at the given index of the pointer array.
1110 : : *
1111 : : * This does not perform bounds checking on the given @index_,
1112 : : * so you are responsible for checking it against the array length.
1113 : : *
1114 : : * Returns: the pointer at the given index
1115 : : */
1116 : :
1117 : : static void g_ptr_array_maybe_expand (GRealPtrArray *array,
1118 : : guint len);
1119 : :
1120 : : static void
1121 : 1642862 : ptr_array_maybe_null_terminate (GRealPtrArray *rarray)
1122 : : {
1123 : 1642862 : if (G_UNLIKELY (rarray->null_terminated))
1124 : 52519 : rarray->pdata[rarray->len] = NULL;
1125 : 1642862 : }
1126 : :
1127 : : static GPtrArray *
1128 : 108048 : ptr_array_new (guint reserved_size,
1129 : : GDestroyNotify element_free_func,
1130 : : gboolean null_terminated)
1131 : : {
1132 : : GRealPtrArray *array;
1133 : :
1134 : 108048 : array = g_slice_new (GRealPtrArray);
1135 : :
1136 : 108048 : array->pdata = NULL;
1137 : 108048 : array->len = 0;
1138 : 108048 : array->alloc = 0;
1139 : 108048 : array->null_terminated = null_terminated ? 1 : 0;
1140 : 108048 : array->element_free_func = element_free_func;
1141 : :
1142 : 108048 : g_atomic_ref_count_init (&array->ref_count);
1143 : :
1144 : 108048 : if (reserved_size != 0)
1145 : : {
1146 : 758 : if (G_LIKELY (reserved_size < G_MAXUINT) &&
1147 : : null_terminated)
1148 : 104 : reserved_size++;
1149 : :
1150 : 758 : g_ptr_array_maybe_expand (array, reserved_size);
1151 : 758 : g_assert (array->pdata != NULL);
1152 : :
1153 : 758 : if (null_terminated)
1154 : : {
1155 : : /* don't use ptr_array_maybe_null_terminate(). It helps the compiler
1156 : : * to see when @null_terminated is false and thereby inline
1157 : : * ptr_array_new() and possibly remove the code entirely. */
1158 : 104 : array->pdata[0] = NULL;
1159 : : }
1160 : : }
1161 : :
1162 : 108048 : return (GPtrArray *) array;
1163 : : }
1164 : :
1165 : : /**
1166 : : * g_ptr_array_new:
1167 : : *
1168 : : * Creates a new #GPtrArray with a reference count of 1.
1169 : : *
1170 : : * Returns: the new #GPtrArray
1171 : : */
1172 : : GPtrArray*
1173 : 105662 : g_ptr_array_new (void)
1174 : : {
1175 : 105662 : return ptr_array_new (0, NULL, FALSE);
1176 : : }
1177 : :
1178 : : /**
1179 : : * g_ptr_array_new_take: (skip)
1180 : : * @data: (array length=len) (transfer full) (nullable): an array of pointers,
1181 : : * or %NULL for an empty array
1182 : : * @len: the number of pointers in @data
1183 : : * @element_free_func: (nullable): A function to free elements on @array
1184 : : * destruction or %NULL
1185 : : *
1186 : : * Creates a new #GPtrArray with @data as pointers, @len as length and a
1187 : : * reference count of 1.
1188 : : *
1189 : : * This avoids having to copy such data manually.
1190 : : * After this call, @data belongs to the #GPtrArray and may no longer be
1191 : : * modified by the caller. The memory of @data has to be dynamically
1192 : : * allocated and will eventually be freed with g_free().
1193 : : *
1194 : : * It also sets @element_free_func for freeing each element when the array is
1195 : : * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
1196 : : * with @free_segment set to %TRUE or when removing elements.
1197 : : *
1198 : : * Do not use it if @len is greater than %G_MAXUINT. #GPtrArray
1199 : : * stores the length of its data in #guint, which may be shorter than
1200 : : * #gsize.
1201 : : *
1202 : : * Returns: (transfer full): A new #GPtrArray
1203 : : *
1204 : : * Since: 2.76
1205 : : */
1206 : : GPtrArray *
1207 : 77 : g_ptr_array_new_take (gpointer *data,
1208 : : gsize len,
1209 : : GDestroyNotify element_free_func)
1210 : : {
1211 : : GPtrArray *array;
1212 : : GRealPtrArray *rarray;
1213 : :
1214 : 77 : g_return_val_if_fail (data != NULL || len == 0, NULL);
1215 : 76 : g_return_val_if_fail (len <= G_MAXUINT, NULL);
1216 : :
1217 : 76 : array = ptr_array_new (0, element_free_func, FALSE);
1218 : 76 : rarray = (GRealPtrArray *)array;
1219 : :
1220 : 76 : rarray->pdata = g_steal_pointer (&data);
1221 : 76 : rarray->len = len;
1222 : 76 : rarray->alloc = len;
1223 : :
1224 : 76 : return array;
1225 : : }
1226 : :
1227 : : /**
1228 : : * g_ptr_array_new_take_null_terminated: (skip)
1229 : : * @data: (array zero-terminated=1) (transfer full) (nullable): an array
1230 : : * of pointers, %NULL terminated, or %NULL for an empty array
1231 : : * @element_free_func: (nullable): a function to free elements on @array
1232 : : * destruction or %NULL
1233 : : *
1234 : : * Creates a new #GPtrArray with @data as pointers, computing the length of it
1235 : : * and setting the reference count to 1.
1236 : : *
1237 : : * This avoids having to copy such data manually.
1238 : : * After this call, @data belongs to the #GPtrArray and may no longer be
1239 : : * modified by the caller. The memory of @data has to be dynamically
1240 : : * allocated and will eventually be freed with g_free().
1241 : : *
1242 : : * The length is calculated by iterating through @data until the first %NULL
1243 : : * element is found.
1244 : : *
1245 : : * It also sets @element_free_func for freeing each element when the array is
1246 : : * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
1247 : : * with @free_segment set to %TRUE or when removing elements.
1248 : : *
1249 : : * Do not use it if the @data length is greater than %G_MAXUINT. #GPtrArray
1250 : : * stores the length of its data in #guint, which may be shorter than
1251 : : * #gsize.
1252 : : *
1253 : : * Returns: (transfer full): A new #GPtrArray
1254 : : *
1255 : : * Since: 2.76
1256 : : */
1257 : : GPtrArray *
1258 : 72 : g_ptr_array_new_take_null_terminated (gpointer *data,
1259 : : GDestroyNotify element_free_func)
1260 : : {
1261 : : GPtrArray *array;
1262 : 72 : gsize len = 0;
1263 : :
1264 : 72 : if (data != NULL)
1265 : : {
1266 : 20142 : for (gsize i = 0; data[i] != NULL; ++i)
1267 : 20071 : len += 1;
1268 : : }
1269 : :
1270 : 72 : g_return_val_if_fail (len <= G_MAXUINT, NULL);
1271 : :
1272 : 72 : array = g_ptr_array_new_take (g_steal_pointer (&data), len, element_free_func);
1273 : 72 : ((GRealPtrArray *)array)->null_terminated = TRUE;
1274 : :
1275 : 72 : return array;
1276 : : }
1277 : :
1278 : : static GPtrArray *
1279 : 8 : ptr_array_new_from_array (gpointer *data,
1280 : : gsize len,
1281 : : GCopyFunc copy_func,
1282 : : gpointer copy_func_user_data,
1283 : : GDestroyNotify element_free_func,
1284 : : gboolean null_terminated)
1285 : : {
1286 : : GPtrArray *array;
1287 : : GRealPtrArray *rarray;
1288 : :
1289 : 8 : g_assert (data != NULL || len == 0);
1290 : 8 : g_assert (len <= G_MAXUINT);
1291 : :
1292 : 8 : array = ptr_array_new (len, element_free_func, null_terminated);
1293 : 8 : rarray = (GRealPtrArray *)array;
1294 : :
1295 : 8 : if (copy_func != NULL)
1296 : : {
1297 : 20002 : for (gsize i = 0; i < len; i++)
1298 : 20000 : rarray->pdata[i] = copy_func (data[i], copy_func_user_data);
1299 : : }
1300 : 6 : else if (len != 0)
1301 : : {
1302 : 3 : memcpy (rarray->pdata, data, len * sizeof (gpointer));
1303 : : }
1304 : :
1305 : 8 : if (null_terminated && rarray->pdata != NULL)
1306 : 3 : rarray->pdata[len] = NULL;
1307 : :
1308 : 8 : rarray->len = len;
1309 : :
1310 : 8 : return array;
1311 : : }
1312 : :
1313 : : /**
1314 : : * g_ptr_array_new_from_array: (skip)
1315 : : * @data: (array length=len) (transfer none) (nullable): an array of pointers,
1316 : : * or %NULL for an empty array
1317 : : * @len: the number of pointers in @data
1318 : : * @copy_func: (nullable): a copy function used to copy every element in the
1319 : : * array or %NULL.
1320 : : * @copy_func_user_data: user data passed to @copy_func, or %NULL
1321 : : * @element_free_func: (nullable): a function to free elements on @array
1322 : : * destruction or %NULL
1323 : : *
1324 : : * Creates a new #GPtrArray, copying @len pointers from @data, and setting
1325 : : * the array’s reference count to 1.
1326 : : *
1327 : : * This avoids having to manually add each element one by one.
1328 : : *
1329 : : * If @copy_func is provided, then it is used to copy each element before
1330 : : * adding them to the new array. If it is %NULL then the pointers are copied
1331 : : * directly.
1332 : : *
1333 : : * It also sets @element_free_func for freeing each element when the array is
1334 : : * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
1335 : : * with @free_segment set to %TRUE or when removing elements.
1336 : : *
1337 : : * Do not use it if @len is greater than %G_MAXUINT. #GPtrArray
1338 : : * stores the length of its data in #guint, which may be shorter than
1339 : : * #gsize.
1340 : : *
1341 : : * Returns: (transfer full): A new #GPtrArray
1342 : : *
1343 : : * Since: 2.76
1344 : : */
1345 : : GPtrArray *
1346 : 4 : g_ptr_array_new_from_array (gpointer *data,
1347 : : gsize len,
1348 : : GCopyFunc copy_func,
1349 : : gpointer copy_func_user_data,
1350 : : GDestroyNotify element_free_func)
1351 : : {
1352 : 4 : g_return_val_if_fail (data != NULL || len == 0, NULL);
1353 : 3 : g_return_val_if_fail (len <= G_MAXUINT, NULL);
1354 : :
1355 : 3 : return ptr_array_new_from_array (
1356 : : data, len, copy_func, copy_func_user_data, element_free_func, FALSE);
1357 : : }
1358 : :
1359 : : /**
1360 : : * g_ptr_array_new_from_null_terminated_array: (skip)
1361 : : * @data: (array zero-terminated=1) (transfer none) (nullable): an array of
1362 : : * pointers, %NULL terminated; or %NULL for an empty array
1363 : : * @copy_func: (nullable): a copy function used to copy every element in the
1364 : : * array or %NULL.
1365 : : * @copy_func_user_data: user data passed to @copy_func, or %NULL
1366 : : * @element_free_func: (nullable): a function to free elements on @array
1367 : : * destruction or %NULL
1368 : : *
1369 : : * Creates a new #GPtrArray copying the pointers from @data after having
1370 : : * computed the length of it and with a reference count of 1.
1371 : : * This avoids having to manually add each element one by one.
1372 : : * If @copy_func is provided, then it is used to copy the data in the new
1373 : : * array.
1374 : : * It also set @element_free_func for freeing each element when the array is
1375 : : * destroyed either via g_ptr_array_unref(), when g_ptr_array_free() is called
1376 : : * with @free_segment set to %TRUE or when removing elements.
1377 : : *
1378 : : * Do not use it if the @data has more than %G_MAXUINT elements. #GPtrArray
1379 : : * stores the length of its data in #guint, which may be shorter than
1380 : : * #gsize.
1381 : : *
1382 : : * Returns: (transfer full): A new #GPtrArray
1383 : : *
1384 : : * Since: 2.76
1385 : : */
1386 : : GPtrArray *
1387 : 5 : g_ptr_array_new_from_null_terminated_array (gpointer *data,
1388 : : GCopyFunc copy_func,
1389 : : gpointer copy_func_user_data,
1390 : : GDestroyNotify element_free_func)
1391 : : {
1392 : 5 : gsize len = 0;
1393 : :
1394 : 5 : if (data != NULL)
1395 : : {
1396 : 20008 : for (gsize i = 0; data[i] != NULL; ++i)
1397 : 20004 : len += 1;
1398 : : }
1399 : :
1400 : 5 : g_assert (data != NULL || len == 0);
1401 : 5 : g_return_val_if_fail (len <= G_MAXUINT, NULL);
1402 : :
1403 : 5 : return ptr_array_new_from_array (
1404 : : data, len, copy_func, copy_func_user_data, element_free_func, TRUE);
1405 : : }
1406 : :
1407 : : /**
1408 : : * g_ptr_array_steal:
1409 : : * @array: a #GPtrArray.
1410 : : * @len: (optional) (out): pointer to retrieve the number of
1411 : : * elements of the original array
1412 : : *
1413 : : * Frees the data in the array and resets the size to zero, while
1414 : : * the underlying array is preserved for use elsewhere and returned
1415 : : * to the caller.
1416 : : *
1417 : : * Note that if the array is %NULL terminated this may still return
1418 : : * %NULL if the length of the array was zero and pdata was not yet
1419 : : * allocated.
1420 : : *
1421 : : * Even if set, the #GDestroyNotify function will never be called
1422 : : * on the current contents of the array and the caller is
1423 : : * responsible for freeing the array elements.
1424 : : *
1425 : : * An example of use:
1426 : : * |[<!-- language="C" -->
1427 : : * g_autoptr(GPtrArray) chunk_buffer = g_ptr_array_new_with_free_func (g_bytes_unref);
1428 : : *
1429 : : * // Some part of your application appends a number of chunks to the pointer array.
1430 : : * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("hello", 5));
1431 : : * g_ptr_array_add (chunk_buffer, g_bytes_new_static ("world", 5));
1432 : : *
1433 : : * …
1434 : : *
1435 : : * // Periodically, the chunks need to be sent as an array-and-length to some
1436 : : * // other part of the program.
1437 : : * GBytes **chunks;
1438 : : * gsize n_chunks;
1439 : : *
1440 : : * chunks = g_ptr_array_steal (chunk_buffer, &n_chunks);
1441 : : * for (gsize i = 0; i < n_chunks; i++)
1442 : : * {
1443 : : * // Do something with each chunk here, and then free them, since
1444 : : * // g_ptr_array_steal() transfers ownership of all the elements and the
1445 : : * // array to the caller.
1446 : : * …
1447 : : *
1448 : : * g_bytes_unref (chunks[i]);
1449 : : * }
1450 : : *
1451 : : * g_free (chunks);
1452 : : *
1453 : : * // After calling g_ptr_array_steal(), the pointer array can be reused for the
1454 : : * // next set of chunks.
1455 : : * g_assert (chunk_buffer->len == 0);
1456 : : * ]|
1457 : : *
1458 : : * Returns: (transfer full) (nullable): the element data, which should be
1459 : : * freed using g_free(). This may be %NULL if the array doesn’t have any
1460 : : * elements (i.e. if `*len` is zero).
1461 : : *
1462 : : * Since: 2.64
1463 : : */
1464 : : gpointer *
1465 : 579 : g_ptr_array_steal (GPtrArray *array,
1466 : : gsize *len)
1467 : : {
1468 : : GRealPtrArray *rarray;
1469 : : gpointer *segment;
1470 : :
1471 : 579 : g_return_val_if_fail (array != NULL, NULL);
1472 : :
1473 : 579 : rarray = (GRealPtrArray *) array;
1474 : 579 : segment = (gpointer *) rarray->pdata;
1475 : :
1476 : 579 : if (len != NULL)
1477 : 11 : *len = rarray->len;
1478 : :
1479 : 579 : rarray->pdata = NULL;
1480 : 579 : rarray->len = 0;
1481 : 579 : rarray->alloc = 0;
1482 : 579 : return segment;
1483 : : }
1484 : :
1485 : : /**
1486 : : * g_ptr_array_copy:
1487 : : * @array: #GPtrArray to duplicate
1488 : : * @func: (nullable): a copy function used to copy every element in the array
1489 : : * @user_data: user data passed to the copy function @func, or %NULL
1490 : : *
1491 : : * Makes a full (deep) copy of a #GPtrArray.
1492 : : *
1493 : : * @func, as a #GCopyFunc, takes two arguments, the data to be copied
1494 : : * and a @user_data pointer. On common processor architectures, it's safe to
1495 : : * pass %NULL as @user_data if the copy function takes only one argument. You
1496 : : * may get compiler warnings from this though if compiling with GCC’s
1497 : : * `-Wcast-function-type` warning.
1498 : : *
1499 : : * If @func is %NULL, then only the pointers (and not what they are
1500 : : * pointing to) are copied to the new #GPtrArray.
1501 : : *
1502 : : * The copy of @array will have the same #GDestroyNotify for its elements as
1503 : : * @array. The copy will also be %NULL terminated if (and only if) the source
1504 : : * array is.
1505 : : *
1506 : : * Returns: (transfer full): a deep copy of the initial #GPtrArray.
1507 : : *
1508 : : * Since: 2.62
1509 : : **/
1510 : : GPtrArray *
1511 : 8 : g_ptr_array_copy (GPtrArray *array,
1512 : : GCopyFunc func,
1513 : : gpointer user_data)
1514 : : {
1515 : 8 : GRealPtrArray *rarray = (GRealPtrArray *) array;
1516 : : GPtrArray *new_array;
1517 : :
1518 : 8 : g_return_val_if_fail (array != NULL, NULL);
1519 : :
1520 : 6 : new_array = ptr_array_new (0,
1521 : : rarray->element_free_func,
1522 : 6 : rarray->null_terminated);
1523 : :
1524 : 6 : if (rarray->alloc > 0)
1525 : : {
1526 : 4 : g_ptr_array_maybe_expand ((GRealPtrArray *) new_array, array->len + rarray->null_terminated);
1527 : :
1528 : 4 : if (array->len > 0)
1529 : : {
1530 : 4 : if (func != NULL)
1531 : : {
1532 : : guint i;
1533 : :
1534 : 202 : for (i = 0; i < array->len; i++)
1535 : 200 : new_array->pdata[i] = func (array->pdata[i], user_data);
1536 : : }
1537 : : else
1538 : : {
1539 : 2 : memcpy (new_array->pdata, array->pdata,
1540 : 2 : array->len * sizeof (*array->pdata));
1541 : : }
1542 : :
1543 : 4 : new_array->len = array->len;
1544 : : }
1545 : :
1546 : 4 : ptr_array_maybe_null_terminate ((GRealPtrArray *) new_array);
1547 : : }
1548 : :
1549 : 6 : return new_array;
1550 : : }
1551 : :
1552 : : /**
1553 : : * g_ptr_array_sized_new:
1554 : : * @reserved_size: number of pointers preallocated
1555 : : *
1556 : : * Creates a new #GPtrArray with @reserved_size pointers preallocated
1557 : : * and a reference count of 1. This avoids frequent reallocation, if
1558 : : * you are going to add many pointers to the array. Note however that
1559 : : * the size of the array is still 0.
1560 : : *
1561 : : * Returns: the new #GPtrArray
1562 : : */
1563 : : GPtrArray*
1564 : 326 : g_ptr_array_sized_new (guint reserved_size)
1565 : : {
1566 : 326 : return ptr_array_new (reserved_size, NULL, FALSE);
1567 : : }
1568 : :
1569 : : /**
1570 : : * g_array_copy:
1571 : : * @array: A #GArray.
1572 : : *
1573 : : * Create a shallow copy of a #GArray. If the array elements consist of
1574 : : * pointers to data, the pointers are copied but the actual data is not.
1575 : : *
1576 : : * Returns: (transfer container): A copy of @array.
1577 : : *
1578 : : * Since: 2.62
1579 : : **/
1580 : : GArray *
1581 : 10 : g_array_copy (GArray *array)
1582 : : {
1583 : 10 : GRealArray *rarray = (GRealArray *) array;
1584 : : GRealArray *new_rarray;
1585 : :
1586 : 10 : g_return_val_if_fail (rarray != NULL, NULL);
1587 : :
1588 : : new_rarray =
1589 : 6 : (GRealArray *) g_array_sized_new (rarray->zero_terminated, rarray->clear,
1590 : : rarray->elt_size, rarray->elt_capacity);
1591 : 6 : new_rarray->len = rarray->len;
1592 : 6 : if (rarray->len > 0)
1593 : 5 : memcpy (new_rarray->data, rarray->data, rarray->len * rarray->elt_size);
1594 : :
1595 : 6 : g_array_zero_terminate (new_rarray);
1596 : :
1597 : 6 : return (GArray *) new_rarray;
1598 : : }
1599 : :
1600 : : /**
1601 : : * g_ptr_array_new_with_free_func:
1602 : : * @element_free_func: (nullable): A function to free elements with
1603 : : * destroy @array or %NULL
1604 : : *
1605 : : * Creates a new #GPtrArray with a reference count of 1 and use
1606 : : * @element_free_func for freeing each element when the array is destroyed
1607 : : * either via g_ptr_array_unref(), when g_ptr_array_free() is called with
1608 : : * @free_segment set to %TRUE or when removing elements.
1609 : : *
1610 : : * Returns: (transfer full): A new #GPtrArray
1611 : : *
1612 : : * Since: 2.22
1613 : : */
1614 : : GPtrArray*
1615 : 1473 : g_ptr_array_new_with_free_func (GDestroyNotify element_free_func)
1616 : : {
1617 : 1473 : return ptr_array_new (0, element_free_func, FALSE);
1618 : : }
1619 : :
1620 : : /**
1621 : : * g_ptr_array_new_full:
1622 : : * @reserved_size: number of pointers preallocated
1623 : : * @element_free_func: (nullable): A function to free elements with
1624 : : * destroy @array or %NULL
1625 : : *
1626 : : * Creates a new #GPtrArray with @reserved_size pointers preallocated
1627 : : * and a reference count of 1. This avoids frequent reallocation, if
1628 : : * you are going to add many pointers to the array. Note however that
1629 : : * the size of the array is still 0. It also set @element_free_func
1630 : : * for freeing each element when the array is destroyed either via
1631 : : * g_ptr_array_unref(), when g_ptr_array_free() is called with
1632 : : * @free_segment set to %TRUE or when removing elements.
1633 : : *
1634 : : * Returns: (transfer full): A new #GPtrArray
1635 : : *
1636 : : * Since: 2.30
1637 : : */
1638 : : GPtrArray*
1639 : 326 : g_ptr_array_new_full (guint reserved_size,
1640 : : GDestroyNotify element_free_func)
1641 : : {
1642 : 326 : return ptr_array_new (reserved_size, element_free_func, FALSE);
1643 : : }
1644 : :
1645 : : /**
1646 : : * g_ptr_array_new_null_terminated:
1647 : : * @reserved_size: number of pointers preallocated.
1648 : : * If @null_terminated is %TRUE, the actually allocated
1649 : : * buffer size is @reserved_size plus 1, unless @reserved_size
1650 : : * is zero, in which case no initial buffer gets allocated.
1651 : : * @element_free_func: (nullable): A function to free elements with
1652 : : * destroy @array or %NULL
1653 : : * @null_terminated: whether to make the array as %NULL terminated.
1654 : : *
1655 : : * Like g_ptr_array_new_full() but also allows to set the array to
1656 : : * be %NULL terminated. A %NULL terminated pointer array has an
1657 : : * additional %NULL pointer after the last element, beyond the
1658 : : * current length.
1659 : : *
1660 : : * #GPtrArray created by other constructors are not automatically %NULL
1661 : : * terminated.
1662 : : *
1663 : : * Note that if the @array's length is zero and currently no
1664 : : * data array is allocated, then pdata will still be %NULL.
1665 : : * %GPtrArray will only %NULL terminate pdata, if an actual
1666 : : * array is allocated. It does not guarantee that an array
1667 : : * is always allocated. In other words, if the length is zero,
1668 : : * then pdata may either point to a %NULL terminated array of length
1669 : : * zero or be %NULL.
1670 : : *
1671 : : * Returns: (transfer full): A new #GPtrArray
1672 : : *
1673 : : * Since: 2.74
1674 : : */
1675 : : GPtrArray *
1676 : 171 : g_ptr_array_new_null_terminated (guint reserved_size,
1677 : : GDestroyNotify element_free_func,
1678 : : gboolean null_terminated)
1679 : : {
1680 : 171 : return ptr_array_new (reserved_size, element_free_func, null_terminated);
1681 : : }
1682 : :
1683 : : /**
1684 : : * g_ptr_array_set_free_func:
1685 : : * @array: A #GPtrArray
1686 : : * @element_free_func: (nullable): A function to free elements with
1687 : : * destroy @array or %NULL
1688 : : *
1689 : : * Sets a function for freeing each element when @array is destroyed
1690 : : * either via g_ptr_array_unref(), when g_ptr_array_free() is called
1691 : : * with @free_segment set to %TRUE or when removing elements.
1692 : : *
1693 : : * Since: 2.22
1694 : : */
1695 : : void
1696 : 76 : g_ptr_array_set_free_func (GPtrArray *array,
1697 : : GDestroyNotify element_free_func)
1698 : : {
1699 : 76 : GRealPtrArray *rarray = (GRealPtrArray *)array;
1700 : :
1701 : 76 : g_return_if_fail (array);
1702 : :
1703 : 76 : rarray->element_free_func = element_free_func;
1704 : : }
1705 : :
1706 : : /**
1707 : : * g_ptr_array_is_null_terminated:
1708 : : * @array: the #GPtrArray
1709 : : *
1710 : : * Gets whether the @array was constructed as %NULL-terminated.
1711 : : *
1712 : : * This will only return %TRUE for arrays constructed by passing %TRUE to the
1713 : : * `null_terminated` argument of g_ptr_array_new_null_terminated(). It will not
1714 : : * return %TRUE for normal arrays which have had a %NULL element appended to
1715 : : * them.
1716 : : *
1717 : : * Returns: %TRUE if the array is made to be %NULL terminated.
1718 : : *
1719 : : * Since: 2.74
1720 : : */
1721 : : gboolean
1722 : 20094 : g_ptr_array_is_null_terminated (GPtrArray *array)
1723 : : {
1724 : 20094 : g_return_val_if_fail (array, FALSE);
1725 : :
1726 : 20094 : return ((GRealPtrArray *) array)->null_terminated;
1727 : : }
1728 : :
1729 : : /**
1730 : : * g_ptr_array_ref:
1731 : : * @array: a #GPtrArray
1732 : : *
1733 : : * Atomically increments the reference count of @array by one.
1734 : : * This function is thread-safe and may be called from any thread.
1735 : : *
1736 : : * Returns: The passed in #GPtrArray
1737 : : *
1738 : : * Since: 2.22
1739 : : */
1740 : : GPtrArray*
1741 : 268 : g_ptr_array_ref (GPtrArray *array)
1742 : : {
1743 : 268 : GRealPtrArray *rarray = (GRealPtrArray *)array;
1744 : :
1745 : 268 : g_return_val_if_fail (array, NULL);
1746 : :
1747 : 268 : g_atomic_ref_count_inc (&rarray->ref_count);
1748 : :
1749 : 268 : return array;
1750 : : }
1751 : :
1752 : : static gpointer *ptr_array_free (GPtrArray *, ArrayFreeFlags);
1753 : :
1754 : : /**
1755 : : * g_ptr_array_unref:
1756 : : * @array: A #GPtrArray
1757 : : *
1758 : : * Atomically decrements the reference count of @array by one. If the
1759 : : * reference count drops to 0, the effect is the same as calling
1760 : : * g_ptr_array_free() with @free_segment set to %TRUE. This function
1761 : : * is thread-safe and may be called from any thread.
1762 : : *
1763 : : * Since: 2.22
1764 : : */
1765 : : void
1766 : 8724 : g_ptr_array_unref (GPtrArray *array)
1767 : : {
1768 : 8724 : GRealPtrArray *rarray = (GRealPtrArray *)array;
1769 : :
1770 : 8724 : g_return_if_fail (array);
1771 : :
1772 : 8724 : if (g_atomic_ref_count_dec (&rarray->ref_count))
1773 : 8459 : ptr_array_free (array, FREE_SEGMENT);
1774 : : }
1775 : :
1776 : : /**
1777 : : * g_ptr_array_free:
1778 : : * @array: a #GPtrArray
1779 : : * @free_seg: if %TRUE the actual pointer array is freed as well
1780 : : *
1781 : : * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
1782 : : * it frees the memory block holding the elements as well. Pass %FALSE
1783 : : * if you want to free the #GPtrArray wrapper but preserve the
1784 : : * underlying array for use elsewhere. If the reference count of @array
1785 : : * is greater than one, the #GPtrArray wrapper is preserved but the
1786 : : * size of @array will be set to zero.
1787 : : *
1788 : : * If array contents point to dynamically-allocated memory, they should
1789 : : * be freed separately if @free_seg is %TRUE and no #GDestroyNotify
1790 : : * function has been set for @array.
1791 : : *
1792 : : * Note that if the array is %NULL terminated and @free_seg is %FALSE
1793 : : * then this will always return an allocated %NULL terminated buffer.
1794 : : * If pdata is previously %NULL, a new buffer will be allocated.
1795 : : *
1796 : : * This function is not thread-safe. If using a #GPtrArray from multiple
1797 : : * threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref()
1798 : : * functions.
1799 : : *
1800 : : * Returns: (transfer full) (nullable): the pointer array if @free_seg is
1801 : : * %FALSE, otherwise %NULL. The pointer array should be freed using g_free().
1802 : : */
1803 : : gpointer*
1804 : 98549 : g_ptr_array_free (GPtrArray *array,
1805 : : gboolean free_segment)
1806 : : {
1807 : 98549 : GRealPtrArray *rarray = (GRealPtrArray *)array;
1808 : : ArrayFreeFlags flags;
1809 : :
1810 : 98549 : g_return_val_if_fail (rarray, NULL);
1811 : :
1812 : 98549 : flags = (free_segment ? FREE_SEGMENT : 0);
1813 : :
1814 : : /* if others are holding a reference, preserve the wrapper but
1815 : : * do free/return the data
1816 : : *
1817 : : * Coverity doesn’t understand this and assumes it’s a leak, so comment this
1818 : : * out.
1819 : : */
1820 : : #ifndef __COVERITY__
1821 : 98549 : if (!g_atomic_ref_count_dec (&rarray->ref_count))
1822 : 3 : flags |= PRESERVE_WRAPPER;
1823 : : #endif
1824 : :
1825 : 98549 : return ptr_array_free (array, flags);
1826 : : }
1827 : :
1828 : : static gpointer *
1829 : 107008 : ptr_array_free (GPtrArray *array,
1830 : : ArrayFreeFlags flags)
1831 : : {
1832 : 107008 : GRealPtrArray *rarray = (GRealPtrArray *)array;
1833 : : gpointer *segment;
1834 : :
1835 : 107008 : if (flags & FREE_SEGMENT)
1836 : : {
1837 : : /* Data here is stolen and freed manually. It is an
1838 : : * error to attempt to access the array data (including
1839 : : * mutating the array bounds) during destruction).
1840 : : *
1841 : : * https://bugzilla.gnome.org/show_bug.cgi?id=769064
1842 : : */
1843 : 20111 : gpointer *stolen_pdata = g_steal_pointer (&rarray->pdata);
1844 : 20111 : if (rarray->element_free_func != NULL)
1845 : : {
1846 : : guint i;
1847 : :
1848 : 164406 : for (i = 0; i < rarray->len; ++i)
1849 : 162845 : rarray->element_free_func (stolen_pdata[i]);
1850 : : }
1851 : :
1852 : 20111 : g_free (stolen_pdata);
1853 : 20111 : segment = NULL;
1854 : : }
1855 : : else
1856 : : {
1857 : 86897 : segment = rarray->pdata;
1858 : 86897 : if (!segment && rarray->null_terminated)
1859 : 2 : segment = (gpointer *) g_new0 (char *, 1);
1860 : : }
1861 : :
1862 : 107008 : if (flags & PRESERVE_WRAPPER)
1863 : : {
1864 : 3 : rarray->pdata = NULL;
1865 : 3 : rarray->len = 0;
1866 : 3 : rarray->alloc = 0;
1867 : : }
1868 : : else
1869 : : {
1870 : 107005 : g_slice_free1 (sizeof (GRealPtrArray), rarray);
1871 : : }
1872 : :
1873 : 107008 : return segment;
1874 : : }
1875 : :
1876 : : static void
1877 : 1643613 : g_ptr_array_maybe_expand (GRealPtrArray *array,
1878 : : guint len)
1879 : : {
1880 : : guint max_len;
1881 : :
1882 : : /* The maximum array length is derived from following constraints:
1883 : : * - The number of bytes must fit into a gsize / 2.
1884 : : * - The number of elements must fit into guint.
1885 : : */
1886 : 1643613 : max_len = MIN (G_MAXSIZE / 2 / sizeof (gpointer), G_MAXUINT);
1887 : :
1888 : : /* Detect potential overflow */
1889 : 1643613 : if G_UNLIKELY ((max_len - array->len) < len)
1890 : 0 : g_error ("adding %u to array would overflow", len);
1891 : :
1892 : 1643613 : if ((array->len + len) > array->alloc)
1893 : : {
1894 : 230337 : guint old_alloc = array->alloc;
1895 : 230337 : gsize want_alloc = g_nearest_pow (sizeof (gpointer) * (array->len + len));
1896 : 230337 : want_alloc = MAX (want_alloc, MIN_ARRAY_SIZE);
1897 : 230337 : array->alloc = MIN (want_alloc / sizeof (gpointer), G_MAXUINT);
1898 : 230337 : array->pdata = g_realloc (array->pdata, want_alloc);
1899 : 230337 : if (G_UNLIKELY (g_mem_gc_friendly))
1900 : 1383390 : for ( ; old_alloc < array->alloc; old_alloc++)
1901 : 1168835 : array->pdata [old_alloc] = NULL;
1902 : : }
1903 : 1643613 : }
1904 : :
1905 : : /**
1906 : : * g_ptr_array_set_size:
1907 : : * @array: a #GPtrArray
1908 : : * @length: the new length of the pointer array
1909 : : *
1910 : : * Sets the size of the array. When making the array larger,
1911 : : * newly-added elements will be set to %NULL. When making it smaller,
1912 : : * if @array has a non-%NULL #GDestroyNotify function then it will be
1913 : : * called for the removed elements.
1914 : : */
1915 : : void
1916 : 1611048 : g_ptr_array_set_size (GPtrArray *array,
1917 : : gint length)
1918 : : {
1919 : 1611048 : GRealPtrArray *rarray = (GRealPtrArray *)array;
1920 : : guint length_unsigned;
1921 : :
1922 : 1611048 : g_return_if_fail (rarray);
1923 : 1611048 : g_return_if_fail (rarray->len == 0 || (rarray->len != 0 && rarray->pdata != NULL));
1924 : 1611048 : g_return_if_fail (length >= 0);
1925 : :
1926 : 1611048 : length_unsigned = (guint) length;
1927 : :
1928 : 1611048 : if (length_unsigned > rarray->len)
1929 : : {
1930 : : guint i;
1931 : :
1932 : 1 : if (G_UNLIKELY (rarray->null_terminated) &&
1933 : 0 : length_unsigned - rarray->len > G_MAXUINT - 1)
1934 : 0 : g_error ("array would overflow");
1935 : :
1936 : 1 : g_ptr_array_maybe_expand (rarray, (length_unsigned - rarray->len) + rarray->null_terminated);
1937 : :
1938 : : /* This is not
1939 : : * memset (array->pdata + array->len, 0,
1940 : : * sizeof (gpointer) * (length_unsigned - array->len));
1941 : : * to make it really portable. Remember (void*)NULL needn't be
1942 : : * bitwise zero. It of course is silly not to use memset (..,0,..).
1943 : : */
1944 : 18 : for (i = rarray->len; i < length_unsigned; i++)
1945 : 17 : rarray->pdata[i] = NULL;
1946 : :
1947 : 1 : rarray->len = length_unsigned;
1948 : :
1949 : 1 : ptr_array_maybe_null_terminate (rarray);
1950 : : }
1951 : 1611047 : else if (length_unsigned < rarray->len)
1952 : 689164 : g_ptr_array_remove_range (array, length_unsigned, rarray->len - length_unsigned);
1953 : : }
1954 : :
1955 : : static gpointer
1956 : 129024 : ptr_array_remove_index (GPtrArray *array,
1957 : : guint index_,
1958 : : gboolean fast,
1959 : : gboolean free_element)
1960 : : {
1961 : 129024 : GRealPtrArray *rarray = (GRealPtrArray *) array;
1962 : : gpointer result;
1963 : :
1964 : 129024 : g_return_val_if_fail (rarray, NULL);
1965 : 129024 : g_return_val_if_fail (rarray->len == 0 || (rarray->len != 0 && rarray->pdata != NULL), NULL);
1966 : :
1967 : 129024 : g_return_val_if_fail (index_ < rarray->len, NULL);
1968 : :
1969 : 129024 : result = rarray->pdata[index_];
1970 : :
1971 : 129024 : if (rarray->element_free_func != NULL && free_element)
1972 : 858 : rarray->element_free_func (rarray->pdata[index_]);
1973 : :
1974 : 129024 : if (index_ != rarray->len - 1 && !fast)
1975 : 97 : memmove (rarray->pdata + index_, rarray->pdata + index_ + 1,
1976 : 97 : sizeof (gpointer) * (rarray->len - index_ - 1));
1977 : 128927 : else if (index_ != rarray->len - 1)
1978 : 104166 : rarray->pdata[index_] = rarray->pdata[rarray->len - 1];
1979 : :
1980 : 129024 : rarray->len -= 1;
1981 : :
1982 : 129024 : if (rarray->null_terminated || G_UNLIKELY (g_mem_gc_friendly))
1983 : 129023 : rarray->pdata[rarray->len] = NULL;
1984 : :
1985 : 129024 : return result;
1986 : : }
1987 : :
1988 : : /**
1989 : : * g_ptr_array_remove_index:
1990 : : * @array: a #GPtrArray
1991 : : * @index_: the index of the pointer to remove
1992 : : *
1993 : : * Removes the pointer at the given index from the pointer array.
1994 : : * The following elements are moved down one place. If @array has
1995 : : * a non-%NULL #GDestroyNotify function it is called for the removed
1996 : : * element. If so, the return value from this function will potentially point
1997 : : * to freed memory (depending on the #GDestroyNotify implementation).
1998 : : *
1999 : : * Returns: (nullable): the pointer which was removed
2000 : : */
2001 : : gpointer
2002 : 421 : g_ptr_array_remove_index (GPtrArray *array,
2003 : : guint index_)
2004 : : {
2005 : 421 : return ptr_array_remove_index (array, index_, FALSE, TRUE);
2006 : : }
2007 : :
2008 : : /**
2009 : : * g_ptr_array_remove_index_fast:
2010 : : * @array: a #GPtrArray
2011 : : * @index_: the index of the pointer to remove
2012 : : *
2013 : : * Removes the pointer at the given index from the pointer array.
2014 : : * The last element in the array is used to fill in the space, so
2015 : : * this function does not preserve the order of the array. But it
2016 : : * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
2017 : : * #GDestroyNotify function it is called for the removed element. If so, the
2018 : : * return value from this function will potentially point to freed memory
2019 : : * (depending on the #GDestroyNotify implementation).
2020 : : *
2021 : : * Returns: (nullable): the pointer which was removed
2022 : : */
2023 : : gpointer
2024 : 128594 : g_ptr_array_remove_index_fast (GPtrArray *array,
2025 : : guint index_)
2026 : : {
2027 : 128594 : return ptr_array_remove_index (array, index_, TRUE, TRUE);
2028 : : }
2029 : :
2030 : : /**
2031 : : * g_ptr_array_steal_index:
2032 : : * @array: a #GPtrArray
2033 : : * @index_: the index of the pointer to steal
2034 : : *
2035 : : * Removes the pointer at the given index from the pointer array.
2036 : : * The following elements are moved down one place. The #GDestroyNotify for
2037 : : * @array is *not* called on the removed element; ownership is transferred to
2038 : : * the caller of this function.
2039 : : *
2040 : : * Returns: (transfer full) (nullable): the pointer which was removed
2041 : : * Since: 2.58
2042 : : */
2043 : : gpointer
2044 : 2 : g_ptr_array_steal_index (GPtrArray *array,
2045 : : guint index_)
2046 : : {
2047 : 2 : return ptr_array_remove_index (array, index_, FALSE, FALSE);
2048 : : }
2049 : :
2050 : : /**
2051 : : * g_ptr_array_steal_index_fast:
2052 : : * @array: a #GPtrArray
2053 : : * @index_: the index of the pointer to steal
2054 : : *
2055 : : * Removes the pointer at the given index from the pointer array.
2056 : : * The last element in the array is used to fill in the space, so
2057 : : * this function does not preserve the order of the array. But it
2058 : : * is faster than g_ptr_array_steal_index(). The #GDestroyNotify for @array is
2059 : : * *not* called on the removed element; ownership is transferred to the caller
2060 : : * of this function.
2061 : : *
2062 : : * Returns: (transfer full) (nullable): the pointer which was removed
2063 : : * Since: 2.58
2064 : : */
2065 : : gpointer
2066 : 7 : g_ptr_array_steal_index_fast (GPtrArray *array,
2067 : : guint index_)
2068 : : {
2069 : 7 : return ptr_array_remove_index (array, index_, TRUE, FALSE);
2070 : : }
2071 : :
2072 : : /**
2073 : : * g_ptr_array_remove_range:
2074 : : * @array: a @GPtrArray
2075 : : * @index_: the index of the first pointer to remove
2076 : : * @length: the number of pointers to remove
2077 : : *
2078 : : * Removes the given number of pointers starting at the given index
2079 : : * from a #GPtrArray. The following elements are moved to close the
2080 : : * gap. If @array has a non-%NULL #GDestroyNotify function it is
2081 : : * called for the removed elements.
2082 : : *
2083 : : * Returns: the @array
2084 : : *
2085 : : * Since: 2.4
2086 : : */
2087 : : GPtrArray*
2088 : 689169 : g_ptr_array_remove_range (GPtrArray *array,
2089 : : guint index_,
2090 : : guint length)
2091 : : {
2092 : 689169 : GRealPtrArray *rarray = (GRealPtrArray *)array;
2093 : : guint i;
2094 : :
2095 : 689169 : g_return_val_if_fail (rarray != NULL, NULL);
2096 : 689169 : g_return_val_if_fail (rarray->len == 0 || (rarray->len != 0 && rarray->pdata != NULL), NULL);
2097 : 689169 : g_return_val_if_fail (index_ <= rarray->len, NULL);
2098 : 689169 : g_return_val_if_fail (index_ <= G_MAXUINT - length, NULL);
2099 : 689169 : g_return_val_if_fail (length == 0 || index_ + length <= rarray->len, NULL);
2100 : :
2101 : 689169 : if (length == 0)
2102 : 1 : return array;
2103 : :
2104 : 689168 : if (rarray->element_free_func != NULL)
2105 : : {
2106 : 307 : for (i = index_; i < index_ + length; i++)
2107 : 260 : rarray->element_free_func (rarray->pdata[i]);
2108 : : }
2109 : :
2110 : 689168 : if (index_ + length != rarray->len)
2111 : : {
2112 : 3 : memmove (&rarray->pdata[index_],
2113 : 3 : &rarray->pdata[index_ + length],
2114 : 3 : (rarray->len - (index_ + length)) * sizeof (gpointer));
2115 : : }
2116 : :
2117 : 689168 : rarray->len -= length;
2118 : 689168 : if (G_UNLIKELY (g_mem_gc_friendly))
2119 : : {
2120 : 1416874 : for (i = 0; i < length; i++)
2121 : 727713 : rarray->pdata[rarray->len + i] = NULL;
2122 : : }
2123 : : else
2124 : 7 : ptr_array_maybe_null_terminate (rarray);
2125 : :
2126 : 689168 : return array;
2127 : : }
2128 : :
2129 : : /**
2130 : : * g_ptr_array_remove:
2131 : : * @array: a #GPtrArray
2132 : : * @data: the pointer to remove
2133 : : *
2134 : : * Removes the first occurrence of the given pointer from the pointer
2135 : : * array. The following elements are moved down one place. If @array
2136 : : * has a non-%NULL #GDestroyNotify function it is called for the
2137 : : * removed element.
2138 : : *
2139 : : * It returns %TRUE if the pointer was removed, or %FALSE if the
2140 : : * pointer was not found.
2141 : : *
2142 : : * Returns: %TRUE if the pointer is removed, %FALSE if the pointer
2143 : : * is not found in the array
2144 : : */
2145 : : gboolean
2146 : 395 : g_ptr_array_remove (GPtrArray *array,
2147 : : gpointer data)
2148 : : {
2149 : : guint i;
2150 : :
2151 : 395 : g_return_val_if_fail (array, FALSE);
2152 : 395 : g_return_val_if_fail (array->len == 0 || (array->len != 0 && array->pdata != NULL), FALSE);
2153 : :
2154 : 499 : for (i = 0; i < array->len; i += 1)
2155 : : {
2156 : 498 : if (array->pdata[i] == data)
2157 : : {
2158 : 394 : g_ptr_array_remove_index (array, i);
2159 : 394 : return TRUE;
2160 : : }
2161 : : }
2162 : :
2163 : 1 : return FALSE;
2164 : : }
2165 : :
2166 : : /**
2167 : : * g_ptr_array_remove_fast:
2168 : : * @array: a #GPtrArray
2169 : : * @data: the pointer to remove
2170 : : *
2171 : : * Removes the first occurrence of the given pointer from the pointer
2172 : : * array. The last element in the array is used to fill in the space,
2173 : : * so this function does not preserve the order of the array. But it
2174 : : * is faster than g_ptr_array_remove(). If @array has a non-%NULL
2175 : : * #GDestroyNotify function it is called for the removed element.
2176 : : *
2177 : : * It returns %TRUE if the pointer was removed, or %FALSE if the
2178 : : * pointer was not found.
2179 : : *
2180 : : * Returns: %TRUE if the pointer was found in the array
2181 : : */
2182 : : gboolean
2183 : 127754 : g_ptr_array_remove_fast (GPtrArray *array,
2184 : : gpointer data)
2185 : : {
2186 : 127754 : GRealPtrArray *rarray = (GRealPtrArray *)array;
2187 : : guint i;
2188 : :
2189 : 127754 : g_return_val_if_fail (rarray, FALSE);
2190 : 127754 : g_return_val_if_fail (rarray->len == 0 || (rarray->len != 0 && rarray->pdata != NULL), FALSE);
2191 : :
2192 : 352400 : for (i = 0; i < rarray->len; i += 1)
2193 : : {
2194 : 352399 : if (rarray->pdata[i] == data)
2195 : : {
2196 : 127753 : g_ptr_array_remove_index_fast (array, i);
2197 : 127753 : return TRUE;
2198 : : }
2199 : : }
2200 : :
2201 : 1 : return FALSE;
2202 : : }
2203 : :
2204 : : /**
2205 : : * g_ptr_array_add:
2206 : : * @array: a #GPtrArray
2207 : : * @data: the pointer to add
2208 : : *
2209 : : * Adds a pointer to the end of the pointer array. The array will grow
2210 : : * in size automatically if necessary.
2211 : : */
2212 : : void
2213 : 1632742 : g_ptr_array_add (GPtrArray *array,
2214 : : gpointer data)
2215 : : {
2216 : 1632742 : GRealPtrArray *rarray = (GRealPtrArray *)array;
2217 : :
2218 : 1632742 : g_return_if_fail (rarray);
2219 : 1632742 : g_return_if_fail (rarray->len == 0 || (rarray->len != 0 && rarray->pdata != NULL));
2220 : :
2221 : 1632742 : g_ptr_array_maybe_expand (rarray, 1u + rarray->null_terminated);
2222 : :
2223 : 1632742 : rarray->pdata[rarray->len++] = data;
2224 : :
2225 : 1632742 : ptr_array_maybe_null_terminate (rarray);
2226 : : }
2227 : :
2228 : : /**
2229 : : * g_ptr_array_extend:
2230 : : * @array_to_extend: a #GPtrArray.
2231 : : * @array: (transfer none): a #GPtrArray to add to the end of @array_to_extend.
2232 : : * @func: (nullable): a copy function used to copy every element in the array
2233 : : * @user_data: user data passed to the copy function @func, or %NULL
2234 : : *
2235 : : * Adds all pointers of @array to the end of the array @array_to_extend.
2236 : : * The array will grow in size automatically if needed. @array_to_extend is
2237 : : * modified in-place.
2238 : : *
2239 : : * @func, as a #GCopyFunc, takes two arguments, the data to be copied
2240 : : * and a @user_data pointer. On common processor architectures, it's safe to
2241 : : * pass %NULL as @user_data if the copy function takes only one argument. You
2242 : : * may get compiler warnings from this though if compiling with GCC’s
2243 : : * `-Wcast-function-type` warning.
2244 : : *
2245 : : * If @func is %NULL, then only the pointers (and not what they are
2246 : : * pointing to) are copied to the new #GPtrArray.
2247 : : *
2248 : : * Whether @array_to_extend is %NULL terminated stays unchanged by this function.
2249 : : *
2250 : : * Since: 2.62
2251 : : **/
2252 : : void
2253 : 16 : g_ptr_array_extend (GPtrArray *array_to_extend,
2254 : : GPtrArray *array,
2255 : : GCopyFunc func,
2256 : : gpointer user_data)
2257 : : {
2258 : 16 : GRealPtrArray *rarray_to_extend = (GRealPtrArray *) array_to_extend;
2259 : :
2260 : 16 : g_return_if_fail (array_to_extend != NULL);
2261 : 14 : g_return_if_fail (array != NULL);
2262 : :
2263 : 12 : if (array->len == 0u)
2264 : 4 : return;
2265 : :
2266 : 8 : if (G_UNLIKELY (array->len == G_MAXUINT) &&
2267 : : rarray_to_extend->null_terminated)
2268 : 0 : g_error ("adding %u to array would overflow", array->len);
2269 : :
2270 : 8 : g_ptr_array_maybe_expand (rarray_to_extend, array->len + rarray_to_extend->null_terminated);
2271 : :
2272 : 8 : if (func != NULL)
2273 : : {
2274 : : guint i;
2275 : :
2276 : 102 : for (i = 0; i < array->len; i++)
2277 : 100 : rarray_to_extend->pdata[i + rarray_to_extend->len] =
2278 : 100 : func (array->pdata[i], user_data);
2279 : : }
2280 : 6 : else if (array->len > 0)
2281 : : {
2282 : 6 : memcpy (rarray_to_extend->pdata + rarray_to_extend->len, array->pdata,
2283 : 6 : array->len * sizeof (*array->pdata));
2284 : : }
2285 : :
2286 : 8 : rarray_to_extend->len += array->len;
2287 : :
2288 : 8 : ptr_array_maybe_null_terminate (rarray_to_extend);
2289 : : }
2290 : :
2291 : : /**
2292 : : * g_ptr_array_extend_and_steal:
2293 : : * @array_to_extend: (transfer none): a #GPtrArray.
2294 : : * @array: (transfer container): a #GPtrArray to add to the end of
2295 : : * @array_to_extend.
2296 : : *
2297 : : * Adds all the pointers in @array to the end of @array_to_extend, transferring
2298 : : * ownership of each element from @array to @array_to_extend and modifying
2299 : : * @array_to_extend in-place. @array is then freed.
2300 : : *
2301 : : * As with g_ptr_array_free(), @array will be destroyed if its reference count
2302 : : * is 1. If its reference count is higher, it will be decremented and the
2303 : : * length of @array set to zero.
2304 : : *
2305 : : * Since: 2.62
2306 : : **/
2307 : : void
2308 : 2 : g_ptr_array_extend_and_steal (GPtrArray *array_to_extend,
2309 : : GPtrArray *array)
2310 : : {
2311 : : gpointer *pdata;
2312 : :
2313 : 2 : g_ptr_array_extend (array_to_extend, array, NULL, NULL);
2314 : :
2315 : : /* Get rid of @array without triggering the GDestroyNotify attached
2316 : : * to the elements moved from @array to @array_to_extend. */
2317 : 2 : pdata = g_steal_pointer (&array->pdata);
2318 : 2 : array->len = 0;
2319 : 2 : ((GRealPtrArray *) array)->alloc = 0;
2320 : 2 : g_ptr_array_unref (array);
2321 : 2 : g_free (pdata);
2322 : 2 : }
2323 : :
2324 : : /**
2325 : : * g_ptr_array_insert:
2326 : : * @array: a #GPtrArray
2327 : : * @index_: the index to place the new element at, or -1 to append
2328 : : * @data: the pointer to add.
2329 : : *
2330 : : * Inserts an element into the pointer array at the given index. The
2331 : : * array will grow in size automatically if necessary.
2332 : : *
2333 : : * Since: 2.40
2334 : : */
2335 : : void
2336 : 10100 : g_ptr_array_insert (GPtrArray *array,
2337 : : gint index_,
2338 : : gpointer data)
2339 : : {
2340 : 10100 : GRealPtrArray *rarray = (GRealPtrArray *)array;
2341 : : guint real_index;
2342 : :
2343 : 10100 : g_return_if_fail (rarray);
2344 : 10100 : g_return_if_fail (index_ >= -1);
2345 : 10100 : g_return_if_fail (index_ < 0 || (guint) index_ <= rarray->len);
2346 : :
2347 : 10100 : g_ptr_array_maybe_expand (rarray, 1u + rarray->null_terminated);
2348 : :
2349 : 10100 : real_index = (index_ >= 0) ? (guint) index_ : rarray->len;
2350 : :
2351 : 10100 : if (real_index < rarray->len)
2352 : 10068 : memmove (&(rarray->pdata[real_index + 1]),
2353 : 10068 : &(rarray->pdata[real_index]),
2354 : 10068 : (rarray->len - real_index) * sizeof (gpointer));
2355 : :
2356 : 10100 : rarray->len++;
2357 : 10100 : rarray->pdata[real_index] = data;
2358 : :
2359 : 10100 : ptr_array_maybe_null_terminate (rarray);
2360 : : }
2361 : :
2362 : : /* Please keep this doc-comment in sync with pointer_array_sort_example()
2363 : : * in glib/tests/array-test.c */
2364 : : /**
2365 : : * g_ptr_array_sort:
2366 : : * @array: a #GPtrArray
2367 : : * @compare_func: comparison function
2368 : : *
2369 : : * Sorts the array, using @compare_func which should be a qsort()-style
2370 : : * comparison function (returns less than zero for first arg is less
2371 : : * than second arg, zero for equal, greater than zero if first arg is
2372 : : * greater than second arg).
2373 : : *
2374 : : * Note that the comparison function for g_ptr_array_sort() doesn't
2375 : : * take the pointers from the array as arguments, it takes pointers to
2376 : : * the pointers in the array.
2377 : : *
2378 : : * Use g_ptr_array_sort_values() if you want to use normal
2379 : : * #GCompareFuncs, otherwise here is a full example of use:
2380 : : *
2381 : : * |[<!-- language="C" -->
2382 : : * typedef struct
2383 : : * {
2384 : : * gchar *name;
2385 : : * gint size;
2386 : : * } FileListEntry;
2387 : : *
2388 : : * static gint
2389 : : * sort_filelist (gconstpointer a, gconstpointer b)
2390 : : * {
2391 : : * const FileListEntry *entry1 = *((FileListEntry **) a);
2392 : : * const FileListEntry *entry2 = *((FileListEntry **) b);
2393 : : *
2394 : : * return g_ascii_strcasecmp (entry1->name, entry2->name);
2395 : : * }
2396 : : *
2397 : : * …
2398 : : * g_autoptr (GPtrArray) file_list = NULL;
2399 : : *
2400 : : * // initialize file_list array and load with many FileListEntry entries
2401 : : * ...
2402 : : * // now sort it with
2403 : : * g_ptr_array_sort (file_list, sort_filelist);
2404 : : * ]|
2405 : : *
2406 : : * This is guaranteed to be a stable sort since version 2.32.
2407 : : */
2408 : : void
2409 : 201 : g_ptr_array_sort (GPtrArray *array,
2410 : : GCompareFunc compare_func)
2411 : : {
2412 : 201 : g_return_if_fail (array != NULL);
2413 : :
2414 : : /* Don't use qsort as we want a guaranteed stable sort */
2415 : 201 : if (array->len > 0)
2416 : 198 : g_sort_array (array->pdata,
2417 : 198 : array->len,
2418 : : sizeof (gpointer),
2419 : : (GCompareDataFunc) compare_func,
2420 : : NULL);
2421 : : }
2422 : :
2423 : : /* Please keep this doc-comment in sync with
2424 : : * pointer_array_sort_with_data_example() in glib/tests/array-test.c */
2425 : : /**
2426 : : * g_ptr_array_sort_with_data:
2427 : : * @array: a #GPtrArray
2428 : : * @compare_func: comparison function
2429 : : * @user_data: data to pass to @compare_func
2430 : : *
2431 : : * Like g_ptr_array_sort(), but the comparison function has an extra
2432 : : * user data argument.
2433 : : *
2434 : : * Note that the comparison function for g_ptr_array_sort_with_data()
2435 : : * doesn't take the pointers from the array as arguments, it takes
2436 : : * pointers to the pointers in the array.
2437 : : *
2438 : : * Use g_ptr_array_sort_values_with_data() if you want to use normal
2439 : : * #GCompareDataFuncs, otherwise here is a full example of use:
2440 : : *
2441 : : * |[<!-- language="C" -->
2442 : : * typedef enum { SORT_NAME, SORT_SIZE } SortMode;
2443 : : *
2444 : : * typedef struct
2445 : : * {
2446 : : * gchar *name;
2447 : : * gint size;
2448 : : * } FileListEntry;
2449 : : *
2450 : : * static gint
2451 : : * sort_filelist (gconstpointer a, gconstpointer b, gpointer user_data)
2452 : : * {
2453 : : * gint order;
2454 : : * const SortMode sort_mode = GPOINTER_TO_INT (user_data);
2455 : : * const FileListEntry *entry1 = *((FileListEntry **) a);
2456 : : * const FileListEntry *entry2 = *((FileListEntry **) b);
2457 : : *
2458 : : * switch (sort_mode)
2459 : : * {
2460 : : * case SORT_NAME:
2461 : : * order = g_ascii_strcasecmp (entry1->name, entry2->name);
2462 : : * break;
2463 : : * case SORT_SIZE:
2464 : : * order = entry1->size - entry2->size;
2465 : : * break;
2466 : : * default:
2467 : : * order = 0;
2468 : : * break;
2469 : : * }
2470 : : * return order;
2471 : : * }
2472 : : *
2473 : : * ...
2474 : : * g_autoptr (GPtrArray) file_list = NULL;
2475 : : * SortMode sort_mode;
2476 : : *
2477 : : * // initialize file_list array and load with many FileListEntry entries
2478 : : * ...
2479 : : * // now sort it with
2480 : : * sort_mode = SORT_NAME;
2481 : : * g_ptr_array_sort_with_data (file_list,
2482 : : * sort_filelist,
2483 : : * GINT_TO_POINTER (sort_mode));
2484 : : * ]|
2485 : : *
2486 : : * This is guaranteed to be a stable sort since version 2.32.
2487 : : */
2488 : : void
2489 : 105 : g_ptr_array_sort_with_data (GPtrArray *array,
2490 : : GCompareDataFunc compare_func,
2491 : : gpointer user_data)
2492 : : {
2493 : 105 : g_return_if_fail (array != NULL);
2494 : :
2495 : 105 : if (array->len > 0)
2496 : 102 : g_sort_array (array->pdata,
2497 : 102 : array->len,
2498 : : sizeof (gpointer),
2499 : : compare_func,
2500 : : user_data);
2501 : : }
2502 : :
2503 : : static inline gint
2504 : 121332 : compare_ptr_array_values (gconstpointer a, gconstpointer b, gpointer user_data)
2505 : : {
2506 : 121332 : gconstpointer aa = *((gconstpointer *) a);
2507 : 121332 : gconstpointer bb = *((gconstpointer *) b);
2508 : 121332 : GCompareFunc compare_func = user_data;
2509 : :
2510 : 121332 : return compare_func (aa, bb);
2511 : : }
2512 : :
2513 : : /**
2514 : : * g_ptr_array_sort_values:
2515 : : * @array: a #GPtrArray
2516 : : * @compare_func: a #GCompareFunc comparison function
2517 : : *
2518 : : * Sorts the array, using @compare_func which should be a qsort()-style
2519 : : * comparison function (returns less than zero for first arg is less
2520 : : * than second arg, zero for equal, greater than zero if first arg is
2521 : : * greater than second arg).
2522 : : *
2523 : : * This is guaranteed to be a stable sort.
2524 : : *
2525 : : * Since: 2.76
2526 : : */
2527 : : void
2528 : 97 : g_ptr_array_sort_values (GPtrArray *array,
2529 : : GCompareFunc compare_func)
2530 : : {
2531 : 97 : g_ptr_array_sort_with_data (array, compare_ptr_array_values, compare_func);
2532 : 97 : }
2533 : :
2534 : : typedef struct
2535 : : {
2536 : : GCompareDataFunc compare_func;
2537 : : gpointer user_data;
2538 : : } GPtrArraySortValuesData;
2539 : :
2540 : : static inline gint
2541 : 120484 : compare_ptr_array_values_with_data (gconstpointer a,
2542 : : gconstpointer b,
2543 : : gpointer user_data)
2544 : : {
2545 : 120484 : gconstpointer aa = *((gconstpointer *) a);
2546 : 120484 : gconstpointer bb = *((gconstpointer *) b);
2547 : 120484 : GPtrArraySortValuesData *data = user_data;
2548 : :
2549 : 120484 : return data->compare_func (aa, bb, data->user_data);
2550 : : }
2551 : :
2552 : : /**
2553 : : * g_ptr_array_sort_values_with_data:
2554 : : * @array: a #GPtrArray
2555 : : * @compare_func: a #GCompareDataFunc comparison function
2556 : : * @user_data: data to pass to @compare_func
2557 : : *
2558 : : * Like g_ptr_array_sort_values(), but the comparison function has an extra
2559 : : * user data argument.
2560 : : *
2561 : : * This is guaranteed to be a stable sort.
2562 : : *
2563 : : * Since: 2.76
2564 : : */
2565 : : void
2566 : 4 : g_ptr_array_sort_values_with_data (GPtrArray *array,
2567 : : GCompareDataFunc compare_func,
2568 : : gpointer user_data)
2569 : : {
2570 : 4 : g_ptr_array_sort_with_data (array, compare_ptr_array_values_with_data,
2571 : 4 : &(GPtrArraySortValuesData){
2572 : : .compare_func = compare_func,
2573 : : .user_data = user_data,
2574 : : });
2575 : 4 : }
2576 : :
2577 : : /**
2578 : : * g_ptr_array_foreach:
2579 : : * @array: a #GPtrArray
2580 : : * @func: the function to call for each array element
2581 : : * @user_data: user data to pass to the function
2582 : : *
2583 : : * Calls a function for each element of a #GPtrArray. @func must not
2584 : : * add elements to or remove elements from the array.
2585 : : *
2586 : : * Since: 2.4
2587 : : */
2588 : : void
2589 : 5984 : g_ptr_array_foreach (GPtrArray *array,
2590 : : GFunc func,
2591 : : gpointer user_data)
2592 : : {
2593 : : guint i;
2594 : :
2595 : 5984 : g_return_if_fail (array);
2596 : :
2597 : 45986 : for (i = 0; i < array->len; i++)
2598 : 40002 : (*func) (array->pdata[i], user_data);
2599 : : }
2600 : :
2601 : : /**
2602 : : * g_ptr_array_find: (skip)
2603 : : * @haystack: pointer array to be searched
2604 : : * @needle: pointer to look for
2605 : : * @index_: (optional) (out): return location for the index of
2606 : : * the element, if found
2607 : : *
2608 : : * Checks whether @needle exists in @haystack. If the element is found, %TRUE is
2609 : : * returned and the element’s index is returned in @index_ (if non-%NULL).
2610 : : * Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists
2611 : : * multiple times in @haystack, the index of the first instance is returned.
2612 : : *
2613 : : * This does pointer comparisons only. If you want to use more complex equality
2614 : : * checks, such as string comparisons, use g_ptr_array_find_with_equal_func().
2615 : : *
2616 : : * Returns: %TRUE if @needle is one of the elements of @haystack
2617 : : * Since: 2.54
2618 : : */
2619 : : gboolean
2620 : 10 : g_ptr_array_find (GPtrArray *haystack,
2621 : : gconstpointer needle,
2622 : : guint *index_)
2623 : : {
2624 : 10 : return g_ptr_array_find_with_equal_func (haystack, needle, NULL, index_);
2625 : : }
2626 : :
2627 : : /**
2628 : : * g_ptr_array_find_with_equal_func: (skip)
2629 : : * @haystack: pointer array to be searched
2630 : : * @needle: pointer to look for
2631 : : * @equal_func: (nullable): the function to call for each element, which should
2632 : : * return %TRUE when the desired element is found; or %NULL to use pointer
2633 : : * equality
2634 : : * @index_: (optional) (out): return location for the index of
2635 : : * the element, if found
2636 : : *
2637 : : * Checks whether @needle exists in @haystack, using the given @equal_func.
2638 : : * If the element is found, %TRUE is returned and the element’s index is
2639 : : * returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_
2640 : : * is undefined. If @needle exists multiple times in @haystack, the index of
2641 : : * the first instance is returned.
2642 : : *
2643 : : * @equal_func is called with the element from the array as its first parameter,
2644 : : * and @needle as its second parameter. If @equal_func is %NULL, pointer
2645 : : * equality is used.
2646 : : *
2647 : : * Returns: %TRUE if @needle is one of the elements of @haystack
2648 : : * Since: 2.54
2649 : : */
2650 : : gboolean
2651 : 24 : g_ptr_array_find_with_equal_func (GPtrArray *haystack,
2652 : : gconstpointer needle,
2653 : : GEqualFunc equal_func,
2654 : : guint *index_)
2655 : : {
2656 : : guint i;
2657 : :
2658 : 24 : g_return_val_if_fail (haystack != NULL, FALSE);
2659 : :
2660 : 24 : if (equal_func == NULL)
2661 : 11 : equal_func = g_direct_equal;
2662 : :
2663 : 55 : for (i = 0; i < haystack->len; i++)
2664 : : {
2665 : 50 : if (equal_func (g_ptr_array_index (haystack, i), needle))
2666 : : {
2667 : 19 : if (index_ != NULL)
2668 : 5 : *index_ = i;
2669 : 19 : return TRUE;
2670 : : }
2671 : : }
2672 : :
2673 : 5 : return FALSE;
2674 : : }
2675 : :
2676 : : /**
2677 : : * GByteArray:
2678 : : * @data: a pointer to the element data. The data may be moved as
2679 : : * elements are added to the #GByteArray
2680 : : * @len: the number of elements in the #GByteArray
2681 : : *
2682 : : * Contains the public fields of a GByteArray.
2683 : : */
2684 : :
2685 : : /**
2686 : : * g_byte_array_new:
2687 : : *
2688 : : * Creates a new #GByteArray with a reference count of 1.
2689 : : *
2690 : : * Returns: (transfer full): the new #GByteArray
2691 : : */
2692 : : GByteArray*
2693 : 441 : g_byte_array_new (void)
2694 : : {
2695 : 441 : return (GByteArray *)g_array_sized_new (FALSE, FALSE, 1, 0);
2696 : : }
2697 : :
2698 : : /**
2699 : : * g_byte_array_steal:
2700 : : * @array: a #GByteArray.
2701 : : * @len: (optional) (out): pointer to retrieve the number of
2702 : : * elements of the original array
2703 : : *
2704 : : * Frees the data in the array and resets the size to zero, while
2705 : : * the underlying array is preserved for use elsewhere and returned
2706 : : * to the caller.
2707 : : *
2708 : : * Returns: (transfer full): the element data, which should be
2709 : : * freed using g_free().
2710 : : *
2711 : : * Since: 2.64
2712 : : */
2713 : : guint8 *
2714 : 2 : g_byte_array_steal (GByteArray *array,
2715 : : gsize *len)
2716 : : {
2717 : 2 : return (guint8 *) g_array_steal ((GArray *) array, len);
2718 : : }
2719 : :
2720 : : /**
2721 : : * g_byte_array_new_take:
2722 : : * @data: (transfer full) (array length=len): byte data for the array
2723 : : * @len: length of @data
2724 : : *
2725 : : * Creates a byte array containing the @data.
2726 : : * After this call, @data belongs to the #GByteArray and may no longer be
2727 : : * modified by the caller. The memory of @data has to be dynamically
2728 : : * allocated and will eventually be freed with g_free().
2729 : : *
2730 : : * Do not use it if @len is greater than %G_MAXUINT. #GByteArray
2731 : : * stores the length of its data in #guint, which may be shorter than
2732 : : * #gsize.
2733 : : *
2734 : : * Since: 2.32
2735 : : *
2736 : : * Returns: (transfer full): a new #GByteArray
2737 : : */
2738 : : GByteArray*
2739 : 5 : g_byte_array_new_take (guint8 *data,
2740 : : gsize len)
2741 : : {
2742 : : GByteArray *array;
2743 : : GRealArray *real;
2744 : :
2745 : 5 : g_return_val_if_fail (len <= G_MAXUINT, NULL);
2746 : 4 : array = g_byte_array_new ();
2747 : 4 : real = (GRealArray *)array;
2748 : 4 : g_assert (real->data == NULL);
2749 : 4 : g_assert (real->len == 0);
2750 : :
2751 : 4 : real->data = data;
2752 : 4 : real->len = len;
2753 : 4 : real->elt_capacity = len;
2754 : :
2755 : 4 : return array;
2756 : : }
2757 : :
2758 : : /**
2759 : : * g_byte_array_sized_new:
2760 : : * @reserved_size: number of bytes preallocated
2761 : : *
2762 : : * Creates a new #GByteArray with @reserved_size bytes preallocated.
2763 : : * This avoids frequent reallocation, if you are going to add many
2764 : : * bytes to the array. Note however that the size of the array is still
2765 : : * 0.
2766 : : *
2767 : : * Returns: (transfer full): the new #GByteArray
2768 : : */
2769 : : GByteArray*
2770 : 27 : g_byte_array_sized_new (guint reserved_size)
2771 : : {
2772 : 27 : return (GByteArray *)g_array_sized_new (FALSE, FALSE, 1, reserved_size);
2773 : : }
2774 : :
2775 : : /**
2776 : : * g_byte_array_free:
2777 : : * @array: a #GByteArray
2778 : : * @free_segment: if %TRUE the actual byte data is freed as well
2779 : : *
2780 : : * Frees the memory allocated by the #GByteArray. If @free_segment is
2781 : : * %TRUE it frees the actual byte data. If the reference count of
2782 : : * @array is greater than one, the #GByteArray wrapper is preserved but
2783 : : * the size of @array will be set to zero.
2784 : : *
2785 : : * Returns: the element data if @free_segment is %FALSE, otherwise
2786 : : * %NULL. The element data should be freed using g_free().
2787 : : */
2788 : : guint8*
2789 : 437 : g_byte_array_free (GByteArray *array,
2790 : : gboolean free_segment)
2791 : : {
2792 : 437 : return (guint8 *)g_array_free ((GArray *)array, free_segment);
2793 : : }
2794 : :
2795 : : /**
2796 : : * g_byte_array_free_to_bytes:
2797 : : * @array: (transfer full): a #GByteArray
2798 : : *
2799 : : * Transfers the data from the #GByteArray into a new immutable #GBytes.
2800 : : *
2801 : : * The #GByteArray is freed unless the reference count of @array is greater
2802 : : * than one, the #GByteArray wrapper is preserved but the size of @array
2803 : : * will be set to zero.
2804 : : *
2805 : : * This is identical to using g_bytes_new_take() and g_byte_array_free()
2806 : : * together.
2807 : : *
2808 : : * Since: 2.32
2809 : : *
2810 : : * Returns: (transfer full): a new immutable #GBytes representing same
2811 : : * byte data that was in the array
2812 : : */
2813 : : GBytes*
2814 : 1 : g_byte_array_free_to_bytes (GByteArray *array)
2815 : : {
2816 : : gsize length;
2817 : :
2818 : 1 : g_return_val_if_fail (array != NULL, NULL);
2819 : :
2820 : 1 : length = array->len;
2821 : 1 : return g_bytes_new_take (g_byte_array_free (array, FALSE), length);
2822 : : }
2823 : :
2824 : : /**
2825 : : * g_byte_array_ref:
2826 : : * @array: A #GByteArray
2827 : : *
2828 : : * Atomically increments the reference count of @array by one.
2829 : : * This function is thread-safe and may be called from any thread.
2830 : : *
2831 : : * Returns: (transfer full): The passed in #GByteArray
2832 : : *
2833 : : * Since: 2.22
2834 : : */
2835 : : GByteArray*
2836 : 3 : g_byte_array_ref (GByteArray *array)
2837 : : {
2838 : 3 : return (GByteArray *)g_array_ref ((GArray *)array);
2839 : : }
2840 : :
2841 : : /**
2842 : : * g_byte_array_unref:
2843 : : * @array: A #GByteArray
2844 : : *
2845 : : * Atomically decrements the reference count of @array by one. If the
2846 : : * reference count drops to 0, all memory allocated by the array is
2847 : : * released. This function is thread-safe and may be called from any
2848 : : * thread.
2849 : : *
2850 : : * Since: 2.22
2851 : : */
2852 : : void
2853 : 34 : g_byte_array_unref (GByteArray *array)
2854 : : {
2855 : 34 : g_array_unref ((GArray *)array);
2856 : 34 : }
2857 : :
2858 : : /**
2859 : : * g_byte_array_append:
2860 : : * @array: a #GByteArray
2861 : : * @data: the byte data to be added
2862 : : * @len: the number of bytes to add
2863 : : *
2864 : : * Adds the given bytes to the end of the #GByteArray.
2865 : : * The array will grow in size automatically if necessary.
2866 : : *
2867 : : * Returns: (transfer none): the #GByteArray
2868 : : */
2869 : : GByteArray*
2870 : 45148 : g_byte_array_append (GByteArray *array,
2871 : : const guint8 *data,
2872 : : guint len)
2873 : : {
2874 : 45148 : g_array_append_vals ((GArray *)array, (guint8 *)data, len);
2875 : :
2876 : 45148 : return array;
2877 : : }
2878 : :
2879 : : /**
2880 : : * g_byte_array_prepend:
2881 : : * @array: a #GByteArray
2882 : : * @data: the byte data to be added
2883 : : * @len: the number of bytes to add
2884 : : *
2885 : : * Adds the given data to the start of the #GByteArray.
2886 : : * The array will grow in size automatically if necessary.
2887 : : *
2888 : : * Returns: (transfer none): the #GByteArray
2889 : : */
2890 : : GByteArray*
2891 : 10000 : g_byte_array_prepend (GByteArray *array,
2892 : : const guint8 *data,
2893 : : guint len)
2894 : : {
2895 : 10000 : g_array_prepend_vals ((GArray *)array, (guint8 *)data, len);
2896 : :
2897 : 10000 : return array;
2898 : : }
2899 : :
2900 : : /**
2901 : : * g_byte_array_set_size:
2902 : : * @array: a #GByteArray
2903 : : * @length: the new size of the #GByteArray
2904 : : *
2905 : : * Sets the size of the #GByteArray, expanding it if necessary.
2906 : : *
2907 : : * Returns: (transfer none): the #GByteArray
2908 : : */
2909 : : GByteArray*
2910 : 1 : g_byte_array_set_size (GByteArray *array,
2911 : : guint length)
2912 : : {
2913 : 1 : g_array_set_size ((GArray *)array, length);
2914 : :
2915 : 1 : return array;
2916 : : }
2917 : :
2918 : : /**
2919 : : * g_byte_array_remove_index:
2920 : : * @array: a #GByteArray
2921 : : * @index_: the index of the byte to remove
2922 : : *
2923 : : * Removes the byte at the given index from a #GByteArray.
2924 : : * The following bytes are moved down one place.
2925 : : *
2926 : : * Returns: (transfer none): the #GByteArray
2927 : : **/
2928 : : GByteArray*
2929 : 5 : g_byte_array_remove_index (GByteArray *array,
2930 : : guint index_)
2931 : : {
2932 : 5 : g_array_remove_index ((GArray *)array, index_);
2933 : :
2934 : 5 : return array;
2935 : : }
2936 : :
2937 : : /**
2938 : : * g_byte_array_remove_index_fast:
2939 : : * @array: a #GByteArray
2940 : : * @index_: the index of the byte to remove
2941 : : *
2942 : : * Removes the byte at the given index from a #GByteArray. The last
2943 : : * element in the array is used to fill in the space, so this function
2944 : : * does not preserve the order of the #GByteArray. But it is faster
2945 : : * than g_byte_array_remove_index().
2946 : : *
2947 : : * Returns: (transfer none): the #GByteArray
2948 : : */
2949 : : GByteArray*
2950 : 4 : g_byte_array_remove_index_fast (GByteArray *array,
2951 : : guint index_)
2952 : : {
2953 : 4 : g_array_remove_index_fast ((GArray *)array, index_);
2954 : :
2955 : 4 : return array;
2956 : : }
2957 : :
2958 : : /**
2959 : : * g_byte_array_remove_range:
2960 : : * @array: a @GByteArray
2961 : : * @index_: the index of the first byte to remove
2962 : : * @length: the number of bytes to remove
2963 : : *
2964 : : * Removes the given number of bytes starting at the given index from a
2965 : : * #GByteArray. The following elements are moved to close the gap.
2966 : : *
2967 : : * Returns: (transfer none): the #GByteArray
2968 : : *
2969 : : * Since: 2.4
2970 : : */
2971 : : GByteArray*
2972 : 3 : g_byte_array_remove_range (GByteArray *array,
2973 : : guint index_,
2974 : : guint length)
2975 : : {
2976 : 3 : g_return_val_if_fail (array, NULL);
2977 : 3 : g_return_val_if_fail (index_ <= array->len, NULL);
2978 : 3 : g_return_val_if_fail (index_ <= G_MAXUINT - length, NULL);
2979 : 3 : g_return_val_if_fail (index_ + length <= array->len, NULL);
2980 : :
2981 : 3 : return (GByteArray *)g_array_remove_range ((GArray *)array, index_, length);
2982 : : }
2983 : :
2984 : : /**
2985 : : * g_byte_array_sort:
2986 : : * @array: a #GByteArray
2987 : : * @compare_func: (scope call): comparison function
2988 : : *
2989 : : * Sorts a byte array, using @compare_func which should be a
2990 : : * qsort()-style comparison function (returns less than zero for first
2991 : : * arg is less than second arg, zero for equal, greater than zero if
2992 : : * first arg is greater than second arg).
2993 : : *
2994 : : * If two array elements compare equal, their order in the sorted array
2995 : : * is undefined. If you want equal elements to keep their order (i.e.
2996 : : * you want a stable sort) you can write a comparison function that,
2997 : : * if two elements would otherwise compare equal, compares them by
2998 : : * their addresses.
2999 : : */
3000 : : void
3001 : 1 : g_byte_array_sort (GByteArray *array,
3002 : : GCompareFunc compare_func)
3003 : : {
3004 : 1 : g_array_sort ((GArray *)array, compare_func);
3005 : 1 : }
3006 : :
3007 : : /**
3008 : : * g_byte_array_sort_with_data:
3009 : : * @array: a #GByteArray
3010 : : * @compare_func: (scope call): comparison function
3011 : : * @user_data: data to pass to @compare_func
3012 : : *
3013 : : * Like g_byte_array_sort(), but the comparison function takes an extra
3014 : : * user data argument.
3015 : : */
3016 : : void
3017 : 1 : g_byte_array_sort_with_data (GByteArray *array,
3018 : : GCompareDataFunc compare_func,
3019 : : gpointer user_data)
3020 : : {
3021 : 1 : g_array_sort_with_data ((GArray *)array, compare_func, user_data);
3022 : 1 : }
|
