LCOV - code coverage report
Current view: top level - glib - garray.c (source / functions) Hit Total Coverage
Test: unnamed Lines: 504 507 99.4 %
Date: 2019-11-15 20:35:02 Functions: 68 68 100.0 %
Branches: 166 174 95.4 %

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

Generated by: LCOV version 1.14