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  * #GValueArray is deprecated in favour of #GArray since GLib 2.32. It
  45  * is possible to create a #GArray that behaves like a #GValueArray by
  46  * using the size of #GValue as the element size, and by setting
  47  * g_value_unset() as the clear function using g_array_set_clear_func(),
  48  * for instance, the following code:
  49  *
  50  * |[
  51  *   GValueArray *array = g_value_array_new (10);
  52  * ]|
  53  *
  54  * can be replaced by:
  55  *
  56  * |[
  57  *   GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
  58  *   g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
  59  * ]|
  60  */
  61
  62
  63 #ifdef  DISABLE_MEM_POOLS
  64 #  define       GROUP_N_VALUES  (1)     /* power of 2 !! */
  65 #else
  66 #  define       GROUP_N_VALUES  (8)     /* power of 2 !! */
  67 #endif
  68
  69
  70 /* --- functions --- */
  71 /**
  72  * g_value_array_get_nth:
  73  * @value_array: #GValueArray to get a value from
  74  * @index_: index of the value of interest
  75  *
  76  * Return a pointer to the value at @index_ containd in @value_array.
  77  *
  78  * Returns: (transfer none): pointer to a value at @index_ in @value_array
  79  *
  80  * Deprecated: 2.32: Use g_array_index() instead.
  81  */
  82 GValue*
  83 g_value_array_get_nth (GValueArray *value_array,
  84                        guint        index)
  85 {
  86   g_return_val_if_fail (value_array != NULL, NULL);
  87   g_return_val_if_fail (index < value_array->n_values, NULL);
  88
  89   return value_array->values + index;
  90 }
  91
  92 static inline void
  93 value_array_grow (GValueArray *value_array,
  94                   guint        n_values,
  95                   gboolean     zero_init)
  96 {
  97   g_return_if_fail (n_values >= value_array->n_values);
  98
  99   value_array->n_values = n_values;
 100   if (value_array->n_values > value_array->n_prealloced)
 101     {
 102       guint i = value_array->n_prealloced;
 103
 104       value_array->n_prealloced = (value_array->n_values + GROUP_N_VALUES - 1) & ~(GROUP_N_VALUES - 1);
 105       value_array->values = g_renew (GValue, value_array->values, value_array->n_prealloced);
 106       if (!zero_init)
 107         i = value_array->n_values;
 108       memset (value_array->values + i, 0,
 109               (value_array->n_prealloced - i) * sizeof (value_array->values[0]));
 110     }
 111 }
 112
 113 static inline void
 114 value_array_shrink (GValueArray *value_array)
 115 {
 116 #ifdef  DISABLE_MEM_POOLS
 117   if (value_array->n_prealloced >= value_array->n_values + GROUP_N_VALUES)
 118     {
 119       value_array->n_prealloced = (value_array->n_values + GROUP_N_VALUES - 1) & ~(GROUP_N_VALUES - 1);
 120       value_array->values = g_renew (GValue, value_array->values, value_array->n_prealloced);
 121     }
 122 #endif
 123 }
 124
 125 /**
 126  * g_value_array_new:
 127  * @n_prealloced: number of values to preallocate space for
 128  *
 129  * Allocate and initialize a new #GValueArray, optionally preserve space
 130  * for @n_prealloced elements. New arrays always contain 0 elements,
 131  * regardless of the value of @n_prealloced.
 132  *
 133  * Returns: a newly allocated #GValueArray with 0 values
 134  *
 135  * Deprecated: 2.32: Use #GArray and g_array_sized_new() instead.
 136  */
 137 GValueArray*
 138 g_value_array_new (guint n_prealloced)
 139 {
 140   GValueArray *value_array = g_slice_new (GValueArray);
 141
 142   value_array->n_values = 0;
 143   value_array->n_prealloced = 0;
 144   value_array->values = NULL;
 145   value_array_grow (value_array, n_prealloced, TRUE);
 146   value_array->n_values = 0;
 147
 148   return value_array;
 149 }
 150
 151 /**
 152  * g_value_array_free:
 153  * @value_array: #GValueArray to free
 154  *
 155  * Free a #GValueArray including its contents.
 156  *
 157  * Deprecated: 2.32: Use #GArray and g_array_unref() instead.
 158  */
 159 void
 160 g_value_array_free (GValueArray *value_array)
 161 {
 162   guint i;
 163
 164   g_return_if_fail (value_array != NULL);
 165
 166   for (i = 0; i < value_array->n_values; i++)
 167     {
 168       GValue *value = value_array->values + i;
 169
 170       if (G_VALUE_TYPE (value) != 0) /* we allow unset values in the array */
 171         g_value_unset (value);
 172     }
 173   g_free (value_array->values);
 174   g_slice_free (GValueArray, value_array);
 175 }
 176
 177 /**
 178  * g_value_array_copy:
 179  * @value_array: #GValueArray to copy
 180  *
 181  * Construct an exact copy of a #GValueArray by duplicating all its
 182  * contents.
 183  *
 184  * Returns: (transfer full): Newly allocated copy of #GValueArray
 185  *
 186  * Deprecated: 2.32: Use #GArray and g_array_ref() instead.
 187  */
 188 GValueArray*
 189 g_value_array_copy (const GValueArray *value_array)
 190 {
 191   GValueArray *new_array;
 192   guint i;
 193
 194   g_return_val_if_fail (value_array != NULL, NULL);
 195
 196   new_array = g_slice_new (GValueArray);
 197   new_array->n_values = 0;
 198   new_array->values = NULL;
 199   new_array->n_prealloced = 0;
 200   value_array_grow (new_array, value_array->n_values, TRUE);
 201   for (i = 0; i < new_array->n_values; i++)
 202     if (G_VALUE_TYPE (value_array->values + i) != 0)
 203       {
 204         GValue *value = new_array->values + i;
 205
 206         g_value_init (value, G_VALUE_TYPE (value_array->values + i));
 207         g_value_copy (value_array->values + i, value);
 208       }
 209   return new_array;
 210 }
 211
 212 /**
 213  * g_value_array_prepend:
 214  * @value_array: #GValueArray to add an element to
 215  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 216  *
 217  * Insert a copy of @value as first element of @value_array. If @value is
 218  * %NULL, an uninitialized value is prepended.
 219  *
 220  *
 221  * Returns: (transfer none): the #GValueArray passed in as @value_array
 222  *
 223  * Deprecated: 2.32: Use #GArray and g_array_prepend_val() instead.
 224  */
 225 GValueArray*
 226 g_value_array_prepend (GValueArray  *value_array,
 227                        const GValue *value)
 228 {
 229   g_return_val_if_fail (value_array != NULL, NULL);
 230
 231   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 232   return g_value_array_insert (value_array, 0, value);
 233   G_GNUC_END_IGNORE_DEPRECATIONS
 234 }
 235
 236 /**
 237  * g_value_array_append:
 238  * @value_array: #GValueArray to add an element to
 239  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 240  *
 241  * Insert a copy of @value as last element of @value_array. If @value is
 242  * %NULL, an uninitialized value is appended.
 243  *
 244  * Returns: (transfer none): the #GValueArray passed in as @value_array
 245  *
 246  * Deprecated: 2.32: Use #GArray and g_array_append_val() instead.
 247  */
 248 GValueArray*
 249 g_value_array_append (GValueArray  *value_array,
 250                       const GValue *value)
 251 {
 252   g_return_val_if_fail (value_array != NULL, NULL);
 253
 254   G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 255   return g_value_array_insert (value_array, value_array->n_values, value);
 256   G_GNUC_END_IGNORE_DEPRECATIONS
 257 }
 258
 259 /**
 260  * g_value_array_insert:
 261  * @value_array: #GValueArray to add an element to
 262  * @index_: insertion position, must be &lt;= value_array-&gt;n_values
 263  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 264  *
 265  * Insert a copy of @value at specified position into @value_array. If @value
 266  * is %NULL, an uninitialized value is inserted.
 267  *
 268  * Returns: (transfer none): the #GValueArray passed in as @value_array
 269  *
 270  * Deprecated: 2.32: Use #GArray and g_array_insert_val() instead.
 271  */
 272 GValueArray*
 273 g_value_array_insert (GValueArray  *value_array,
 274                       guint         index,
 275                       const GValue *value)
 276 {
 277   guint i;
 278
 279   g_return_val_if_fail (value_array != NULL, NULL);
 280   g_return_val_if_fail (index <= value_array->n_values, value_array);
 281
 282   i = value_array->n_values;
 283   value_array_grow (value_array, value_array->n_values + 1, FALSE);
 284   if (index + 1 < value_array->n_values)
 285     memmove (value_array->values + index + 1, value_array->values + index,
 286              (i - index) * sizeof (value_array->values[0]));
 287   memset (value_array->values + index, 0, sizeof (value_array->values[0]));
 288   if (value)
 289     {
 290       g_value_init (value_array->values + index, G_VALUE_TYPE (value));
 291       g_value_copy (value, value_array->values + index);
 292     }
 293   return value_array;
 294 }
 295
 296 /**
 297  * g_value_array_remove:
 298  * @value_array: #GValueArray to remove an element from
 299  * @index_: position of value to remove, which must be less than
 300  *          <code>value_array-><link
 301  *          linkend="GValueArray.n-values">n_values</link></code>
 302  *
 303  * Remove the value at position @index_ from @value_array.
 304  *
 305  * Returns: (transfer none): the #GValueArray passed in as @value_array
 306  *
 307  * Deprecated: 2.32: Use #GArray and g_array_remove_index() instead.
 308  */
 309 GValueArray*
 310 g_value_array_remove (GValueArray *value_array,
 311                       guint        index)
 312 {
 313   g_return_val_if_fail (value_array != NULL, NULL);
 314   g_return_val_if_fail (index < value_array->n_values, value_array);
 315
 316   if (G_VALUE_TYPE (value_array->values + index) != 0)
 317     g_value_unset (value_array->values + index);
 318   value_array->n_values--;
 319   if (index < value_array->n_values)
 320     memmove (value_array->values + index, value_array->values + index + 1,
 321              (value_array->n_values - index) * sizeof (value_array->values[0]));
 322   value_array_shrink (value_array);
 323   if (value_array->n_prealloced > value_array->n_values)
 324     memset (value_array->values + value_array->n_values, 0, sizeof (value_array->values[0]));
 325
 326   return value_array;
 327 }
 328
 329 /**
 330  * g_value_array_sort:
 331  * @value_array: #GValueArray to sort
 332  * @compare_func: (scope call): function to compare elements
 333  *
 334  * Sort @value_array using @compare_func to compare the elements according to
 335  * the semantics of #GCompareFunc.
 336  *
 337  * The current implementation uses the same sorting algorithm as standard
 338  * C qsort() function.
 339  *
 340  * Returns: (transfer none): the #GValueArray passed in as @value_array
 341  *
 342  * Deprecated: 2.32: Use #GArray and g_array_sort().
 343  */
 344 GValueArray*
 345 g_value_array_sort (GValueArray *value_array,
 346                     GCompareFunc compare_func)
 347 {
 348   g_return_val_if_fail (compare_func != NULL, NULL);
 349
 350   if (value_array->n_values)
 351     qsort (value_array->values,
 352            value_array->n_values,
 353            sizeof (value_array->values[0]),
 354            compare_func);
 355   return value_array;
 356 }
 357
 358 /**
 359  * g_value_array_sort_with_data:
 360  * @value_array: #GValueArray to sort
 361  * @compare_func: (scope call): function to compare elements
 362  * @user_data: (closure): extra data argument provided for @compare_func
 363  *
 364  * Sort @value_array using @compare_func to compare the elements according
 365  * to the semantics of #GCompareDataFunc.
 366  *
 367  * The current implementation uses the same sorting algorithm as standard
 368  * C qsort() function.
 369  *
 370  * Rename to: g_value_array_sort
 371  * Returns: (transfer none): the #GValueArray passed in as @value_array
 372  *
 373  * Deprecated: 2.32: Use #GArray and g_array_sort_with_data().
 374  */
 375 GValueArray*
 376 g_value_array_sort_with_data (GValueArray     *value_array,
 377                               GCompareDataFunc compare_func,
 378                               gpointer         user_data)
 379 {
 380   g_return_val_if_fail (value_array != NULL, NULL);
 381   g_return_val_if_fail (compare_func != NULL, NULL);
 382
 383   if (value_array->n_values)
 384     g_qsort_with_data (value_array->values,
 385                        value_array->n_values,
 386                        sizeof (value_array->values[0]),
 387                        compare_func, user_data);
 388   return value_array;
 389 }