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