gobject/gvaluearray.c

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 2001 Red Hat, Inc.
   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 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
  15  * Public License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /*
  21  * MT safe
  22  */
  23
  24 #include "config.h"
  25
  26 #include <string.h>
  27 #include <stdlib.h>  /* qsort() */
  28
  29 #include "gvaluearray.h"
  30
  31
  32 /**
  33  * SECTION:value_arrays
  34  * @short_description: A container structure to maintain an array of
  35  *     generic values
  36  * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array()
  37  * @title: Value arrays
  38  *
  39  * The prime purpose of a #GValueArray is for it to be used as an
  40  * object property that holds an array of values. A #GValueArray wraps
  41  * an array of #GValue elements in order for it to be used as a boxed
  42  * type through %G_TYPE_VALUE_ARRAY.
  43  */
  44
  45
  46 #ifdef  DISABLE_MEM_POOLS
  47 #  define       GROUP_N_VALUES  (1)     /* power of 2 !! */
  48 #else
  49 #  define       GROUP_N_VALUES  (8)     /* power of 2 !! */
  50 #endif
  51
  52
  53 /* --- functions --- */
  54 /**
  55  * g_value_array_get_nth:
  56  * @value_array: #GValueArray to get a value from
  57  * @index_: index of the value of interest
  58  *
  59  * Return a pointer to the value at @index_ containd in @value_array.
  60  *
  61  * Returns: (transfer none): pointer to a value at @index_ in @value_array
  62  */
  63 GValue*
  64 g_value_array_get_nth (GValueArray *value_array,
  65                        guint        index)
  66 {
  67   g_return_val_if_fail (value_array != NULL, NULL);
  68   g_return_val_if_fail (index < value_array->n_values, NULL);
  69
  70   return value_array->values + index;
  71 }
  72
  73 static inline void
  74 value_array_grow (GValueArray *value_array,
  75                   guint        n_values,
  76                   gboolean     zero_init)
  77 {
  78   g_return_if_fail (n_values >= value_array->n_values);
  79
  80   value_array->n_values = n_values;
  81   if (value_array->n_values > value_array->n_prealloced)
  82     {
  83       guint i = value_array->n_prealloced;
  84
  85       value_array->n_prealloced = (value_array->n_values + GROUP_N_VALUES - 1) & ~(GROUP_N_VALUES - 1);
  86       value_array->values = g_renew (GValue, value_array->values, value_array->n_prealloced);
  87       if (!zero_init)
  88         i = value_array->n_values;
  89       memset (value_array->values + i, 0,
  90               (value_array->n_prealloced - i) * sizeof (value_array->values[0]));
  91     }
  92 }
  93
  94 static inline void
  95 value_array_shrink (GValueArray *value_array)
  96 {
  97 #ifdef  DISABLE_MEM_POOLS
  98   if (value_array->n_prealloced >= value_array->n_values + GROUP_N_VALUES)
  99     {
 100       value_array->n_prealloced = (value_array->n_values + GROUP_N_VALUES - 1) & ~(GROUP_N_VALUES - 1);
 101       value_array->values = g_renew (GValue, value_array->values, value_array->n_prealloced);
 102     }
 103 #endif
 104 }
 105
 106 /**
 107  * g_value_array_new:
 108  * @n_prealloced: number of values to preallocate space for
 109  *
 110  * Allocate and initialize a new #GValueArray, optionally preserve space
 111  * for @n_prealloced elements. New arrays always contain 0 elements,
 112  * regardless of the value of @n_prealloced.
 113  *
 114  * Returns: a newly allocated #GValueArray with 0 values
 115  */
 116 GValueArray*
 117 g_value_array_new (guint n_prealloced)
 118 {
 119   GValueArray *value_array = g_slice_new (GValueArray);
 120
 121   value_array->n_values = 0;
 122   value_array->n_prealloced = 0;
 123   value_array->values = NULL;
 124   value_array_grow (value_array, n_prealloced, TRUE);
 125   value_array->n_values = 0;
 126
 127   return value_array;
 128 }
 129
 130 /**
 131  * g_value_array_free:
 132  * @value_array: #GValueArray to free
 133  *
 134  * Free a #GValueArray including its contents.
 135  */
 136 void
 137 g_value_array_free (GValueArray *value_array)
 138 {
 139   guint i;
 140
 141   g_return_if_fail (value_array != NULL);
 142
 143   for (i = 0; i < value_array->n_values; i++)
 144     {
 145       GValue *value = value_array->values + i;
 146
 147       if (G_VALUE_TYPE (value) != 0) /* we allow unset values in the array */
 148         g_value_unset (value);
 149     }
 150   g_free (value_array->values);
 151   g_slice_free (GValueArray, value_array);
 152 }
 153
 154 /**
 155  * g_value_array_copy:
 156  * @value_array: #GValueArray to copy
 157  *
 158  * Construct an exact copy of a #GValueArray by duplicating all its
 159  * contents.
 160  *
 161  * Returns: (transfer full): Newly allocated copy of #GValueArray
 162  */
 163 GValueArray*
 164 g_value_array_copy (const GValueArray *value_array)
 165 {
 166   GValueArray *new_array;
 167   guint i;
 168
 169   g_return_val_if_fail (value_array != NULL, NULL);
 170
 171   new_array = g_slice_new (GValueArray);
 172   new_array->n_values = 0;
 173   new_array->values = NULL;
 174   new_array->n_prealloced = 0;
 175   value_array_grow (new_array, value_array->n_values, TRUE);
 176   for (i = 0; i < new_array->n_values; i++)
 177     if (G_VALUE_TYPE (value_array->values + i) != 0)
 178       {
 179         GValue *value = new_array->values + i;
 180
 181         g_value_init (value, G_VALUE_TYPE (value_array->values + i));
 182         g_value_copy (value_array->values + i, value);
 183       }
 184   return new_array;
 185 }
 186
 187 /**
 188  * g_value_array_prepend:
 189  * @value_array: #GValueArray to add an element to
 190  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 191  *
 192  * Insert a copy of @value as first element of @value_array. If @value is
 193  * %NULL, an uninitialized value is prepended.
 194  *
 195  *
 196  * Returns: (transfer none): the #GValueArray passed in as @value_array
 197  */
 198 GValueArray*
 199 g_value_array_prepend (GValueArray  *value_array,
 200                        const GValue *value)
 201 {
 202   g_return_val_if_fail (value_array != NULL, NULL);
 203
 204   return g_value_array_insert (value_array, 0, value);
 205 }
 206
 207 /**
 208  * g_value_array_append:
 209  * @value_array: #GValueArray to add an element to
 210  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 211  *
 212  * Insert a copy of @value as last element of @value_array. If @value is
 213  * %NULL, an uninitialized value is appended.
 214  *
 215  * Returns: (transfer none): the #GValueArray passed in as @value_array
 216  */
 217 GValueArray*
 218 g_value_array_append (GValueArray  *value_array,
 219                       const GValue *value)
 220 {
 221   g_return_val_if_fail (value_array != NULL, NULL);
 222
 223   return g_value_array_insert (value_array, value_array->n_values, value);
 224 }
 225
 226 /**
 227  * g_value_array_insert:
 228  * @value_array: #GValueArray to add an element to
 229  * @index_: insertion position, must be &lt;= value_array-&gt;n_values
 230  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 231  *
 232  * Insert a copy of @value at specified position into @value_array. If @value
 233  * is %NULL, an uninitialized value is inserted.
 234  *
 235  * Returns: (transfer none): the #GValueArray passed in as @value_array
 236  */
 237 GValueArray*
 238 g_value_array_insert (GValueArray  *value_array,
 239                       guint         index,
 240                       const GValue *value)
 241 {
 242   guint i;
 243
 244   g_return_val_if_fail (value_array != NULL, NULL);
 245   g_return_val_if_fail (index <= value_array->n_values, value_array);
 246
 247   i = value_array->n_values;
 248   value_array_grow (value_array, value_array->n_values + 1, FALSE);
 249   if (index + 1 < value_array->n_values)
 250     g_memmove (value_array->values + index + 1, value_array->values + index,
 251                (i - index) * sizeof (value_array->values[0]));
 252   memset (value_array->values + index, 0, sizeof (value_array->values[0]));
 253   if (value)
 254     {
 255       g_value_init (value_array->values + index, G_VALUE_TYPE (value));
 256       g_value_copy (value, value_array->values + index);
 257     }
 258   return value_array;
 259 }
 260
 261 /**
 262  * g_value_array_remove:
 263  * @value_array: #GValueArray to remove an element from
 264  * @index_: position of value to remove, which must be less than
 265  *          <code>value_array-><link
 266  *          linkend="GValueArray.n-values">n_values</link></code>
 267  *
 268  * Remove the value at position @index_ from @value_array.
 269  *
 270  * Returns: (transfer none): the #GValueArray passed in as @value_array
 271  */
 272 GValueArray*
 273 g_value_array_remove (GValueArray *value_array,
 274                       guint        index)
 275 {
 276   g_return_val_if_fail (value_array != NULL, NULL);
 277   g_return_val_if_fail (index < value_array->n_values, value_array);
 278
 279   if (G_VALUE_TYPE (value_array->values + index) != 0)
 280     g_value_unset (value_array->values + index);
 281   value_array->n_values--;
 282   if (index < value_array->n_values)
 283     g_memmove (value_array->values + index, value_array->values + index + 1,
 284                (value_array->n_values - index) * sizeof (value_array->values[0]));
 285   value_array_shrink (value_array);
 286   if (value_array->n_prealloced > value_array->n_values)
 287     memset (value_array->values + value_array->n_values, 0, sizeof (value_array->values[0]));
 288
 289   return value_array;
 290 }
 291
 292 /**
 293  * g_value_array_sort:
 294  * @value_array: #GValueArray to sort
 295  * @compare_func: (scope call): function to compare elements
 296  *
 297  * Sort @value_array using @compare_func to compare the elements according to
 298  * the semantics of #GCompareFunc.
 299  *
 300  * The current implementation uses Quick-Sort as sorting algorithm.
 301  *
 302  * Returns: (transfer none): the #GValueArray passed in as @value_array
 303  */
 304 GValueArray*
 305 g_value_array_sort (GValueArray *value_array,
 306                     GCompareFunc compare_func)
 307 {
 308   g_return_val_if_fail (compare_func != NULL, NULL);
 309
 310   if (value_array->n_values)
 311     qsort (value_array->values,
 312            value_array->n_values,
 313            sizeof (value_array->values[0]),
 314            compare_func);
 315   return value_array;
 316 }
 317
 318 /**
 319  * g_value_array_sort_with_data:
 320  * @value_array: #GValueArray to sort
 321  * @compare_func: (scope call): function to compare elements
 322  * @user_data: (closure): extra data argument provided for @compare_func
 323  *
 324  * Sort @value_array using @compare_func to compare the elements according
 325  * to the semantics of #GCompareDataFunc.
 326  *
 327  * The current implementation uses Quick-Sort as sorting algorithm.
 328  *
 329  * Rename to: g_value_array_sort
 330  * Returns: (transfer none): the #GValueArray passed in as @value_array
 331  */
 332 GValueArray*
 333 g_value_array_sort_with_data (GValueArray     *value_array,
 334                               GCompareDataFunc compare_func,
 335                               gpointer         user_data)
 336 {
 337   g_return_val_if_fail (value_array != NULL, NULL);
 338   g_return_val_if_fail (compare_func != NULL, NULL);
 339
 340   if (value_array->n_values)
 341     g_qsort_with_data (value_array->values,
 342                        value_array->n_values,
 343                        sizeof (value_array->values[0]),
 344                        compare_func, user_data);
 345   return value_array;
 346 }