LCOV - code coverage report
Current view: top level - glib - garray.c (source / functions) Hit Total Coverage
Test: unnamed Lines: 505 508 99.4 %
Date: 2020-05-28 10:14:32 Functions: 69 69 100.0 %
Branches: 170 178 95.5 %

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

Generated by: LCOV version 1.14