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   return g_value_array_insert (value_array, 0, value);
 232 }
 233
 234 /**
 235  * g_value_array_append:
 236  * @value_array: #GValueArray to add an element to
 237  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 238  *
 239  * Insert a copy of @value as last element of @value_array. If @value is
 240  * %NULL, an uninitialized value is appended.
 241  *
 242  * Returns: (transfer none): the #GValueArray passed in as @value_array
 243  *
 244  * Deprecated: 2.32: Use #GArray and g_array_append_val() instead.
 245  */
 246 GValueArray*
 247 g_value_array_append (GValueArray  *value_array,
 248                       const GValue *value)
 249 {
 250   g_return_val_if_fail (value_array != NULL, NULL);
 251
 252   return g_value_array_insert (value_array, value_array->n_values, value);
 253 }
 254
 255 /**
 256  * g_value_array_insert:
 257  * @value_array: #GValueArray to add an element to
 258  * @index_: insertion position, must be &lt;= value_array-&gt;n_values
 259  * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL
 260  *
 261  * Insert a copy of @value at specified position into @value_array. If @value
 262  * is %NULL, an uninitialized value is inserted.
 263  *
 264  * Returns: (transfer none): the #GValueArray passed in as @value_array
 265  *
 266  * Deprecated: 2.32: Use #GArray and g_array_insert_val() instead.
 267  */
 268 GValueArray*
 269 g_value_array_insert (GValueArray  *value_array,
 270                       guint         index,
 271                       const GValue *value)
 272 {
 273   guint i;
 274
 275   g_return_val_if_fail (value_array != NULL, NULL);
 276   g_return_val_if_fail (index <= value_array->n_values, value_array);
 277
 278   i = value_array->n_values;
 279   value_array_grow (value_array, value_array->n_values + 1, FALSE);
 280   if (index + 1 < value_array->n_values)
 281     g_memmove (value_array->values + index + 1, value_array->values + index,
 282                (i - index) * sizeof (value_array->values[0]));
 283   memset (value_array->values + index, 0, sizeof (value_array->values[0]));
 284   if (value)
 285     {
 286       g_value_init (value_array->values + index, G_VALUE_TYPE (value));
 287       g_value_copy (value, value_array->values + index);
 288     }
 289   return value_array;
 290 }
 291
 292 /**
 293  * g_value_array_remove:
 294  * @value_array: #GValueArray to remove an element from
 295  * @index_: position of value to remove, which must be less than
 296  *          <code>value_array-><link
 297  *          linkend="GValueArray.n-values">n_values</link></code>
 298  *
 299  * Remove the value at position @index_ from @value_array.
 300  *
 301  * Returns: (transfer none): the #GValueArray passed in as @value_array
 302  *
 303  * Deprecated: 2.32: Use #GArray and g_array_remove_index() instead.
 304  */
 305 GValueArray*
 306 g_value_array_remove (GValueArray *value_array,
 307                       guint        index)
 308 {
 309   g_return_val_if_fail (value_array != NULL, NULL);
 310   g_return_val_if_fail (index < value_array->n_values, value_array);
 311
 312   if (G_VALUE_TYPE (value_array->values + index) != 0)
 313     g_value_unset (value_array->values + index);
 314   value_array->n_values--;
 315   if (index < value_array->n_values)
 316     g_memmove (value_array->values + index, value_array->values + index + 1,
 317                (value_array->n_values - index) * sizeof (value_array->values[0]));
 318   value_array_shrink (value_array);
 319   if (value_array->n_prealloced > value_array->n_values)
 320     memset (value_array->values + value_array->n_values, 0, sizeof (value_array->values[0]));
 321
 322   return value_array;
 323 }
 324
 325 /**
 326  * g_value_array_sort:
 327  * @value_array: #GValueArray to sort
 328  * @compare_func: (scope call): function to compare elements
 329  *
 330  * Sort @value_array using @compare_func to compare the elements according to
 331  * the semantics of #GCompareFunc.
 332  *
 333  * The current implementation uses Quick-Sort as sorting algorithm.
 334  *
 335  * Returns: (transfer none): the #GValueArray passed in as @value_array
 336  *
 337  * Deprecated: 2.32: Use #GArray and g_array_sort().
 338  */
 339 GValueArray*
 340 g_value_array_sort (GValueArray *value_array,
 341                     GCompareFunc compare_func)
 342 {
 343   g_return_val_if_fail (compare_func != NULL, NULL);
 344
 345   if (value_array->n_values)
 346     qsort (value_array->values,
 347            value_array->n_values,
 348            sizeof (value_array->values[0]),
 349            compare_func);
 350   return value_array;
 351 }
 352
 353 /**
 354  * g_value_array_sort_with_data:
 355  * @value_array: #GValueArray to sort
 356  * @compare_func: (scope call): function to compare elements
 357  * @user_data: (closure): extra data argument provided for @compare_func
 358  *
 359  * Sort @value_array using @compare_func to compare the elements according
 360  * to the semantics of #GCompareDataFunc.
 361  *
 362  * The current implementation uses Quick-Sort as sorting algorithm.
 363  *
 364  * Rename to: g_value_array_sort
 365  * Returns: (transfer none): the #GValueArray passed in as @value_array
 366  *
 367  * Deprecated: 2.32: Use #GArray and g_array_sort_with_data().
 368  */
 369 GValueArray*
 370 g_value_array_sort_with_data (GValueArray     *value_array,
 371                               GCompareDataFunc compare_func,
 372                               gpointer         user_data)
 373 {
 374   g_return_val_if_fail (value_array != NULL, NULL);
 375   g_return_val_if_fail (compare_func != NULL, NULL);
 376
 377   if (value_array->n_values)
 378     g_qsort_with_data (value_array->values,
 379                        value_array->n_values,
 380                        sizeof (value_array->values[0]),
 381                        compare_func, user_data);
 382   return value_array;
 383 }