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: 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: 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: #GValue to copy into #GValueArray
 191  *
 192  * Insert a copy of @value as first element of @value_array.
 193  *
 194  * Returns: the #GValueArray passed in as @value_array
 195  */
 196 GValueArray*
 197 g_value_array_prepend (GValueArray  *value_array,
 198                        const GValue *value)
 199 {
 200   g_return_val_if_fail (value_array != NULL, NULL);
 201
 202   return g_value_array_insert (value_array, 0, value);
 203 }
 204
 205 /**
 206  * g_value_array_append:
 207  * @value_array: #GValueArray to add an element to
 208  * @value: #GValue to copy into #GValueArray
 209  *
 210  * Insert a copy of @value as last element of @value_array.
 211  *
 212  * Returns: the #GValueArray passed in as @value_array
 213  */
 214 GValueArray*
 215 g_value_array_append (GValueArray  *value_array,
 216                       const GValue *value)
 217 {
 218   g_return_val_if_fail (value_array != NULL, NULL);
 219
 220   return g_value_array_insert (value_array, value_array->n_values, value);
 221 }
 222
 223 /**
 224  * g_value_array_insert:
 225  * @value_array: #GValueArray to add an element to
 226  * @index_: insertion position, must be &lt;= value_array-&gt;n_values
 227  * @value: #GValue to copy into #GValueArray
 228  *
 229  * Insert a copy of @value at specified position into @value_array.
 230  *
 231  * Returns: the #GValueArray passed in as @value_array
 232  */
 233 GValueArray*
 234 g_value_array_insert (GValueArray  *value_array,
 235                       guint         index,
 236                       const GValue *value)
 237 {
 238   guint i;
 239
 240   g_return_val_if_fail (value_array != NULL, NULL);
 241   g_return_val_if_fail (index <= value_array->n_values, value_array);
 242
 243   /* we support NULL for "value" as a shortcut for an unset value */
 244
 245   i = value_array->n_values;
 246   value_array_grow (value_array, value_array->n_values + 1, FALSE);
 247   if (index + 1 < value_array->n_values)
 248     g_memmove (value_array->values + index + 1, value_array->values + index,
 249                (i - index) * sizeof (value_array->values[0]));
 250   memset (value_array->values + index, 0, sizeof (value_array->values[0]));
 251   if (value)
 252     {
 253       g_value_init (value_array->values + index, G_VALUE_TYPE (value));
 254       g_value_copy (value, value_array->values + index);
 255     }
 256   return value_array;
 257 }
 258
 259 /**
 260  * g_value_array_remove:
 261  * @value_array: #GValueArray to remove an element from
 262  * @index_: position of value to remove, must be &lt; value_array->n_values
 263  *
 264  * Remove the value at position @index_ from @value_array.
 265  *
 266  * Returns: the #GValueArray passed in as @value_array
 267  */
 268 GValueArray*
 269 g_value_array_remove (GValueArray *value_array,
 270                       guint        index)
 271 {
 272   g_return_val_if_fail (value_array != NULL, NULL);
 273   g_return_val_if_fail (index < value_array->n_values, value_array);
 274
 275   if (G_VALUE_TYPE (value_array->values + index) != 0)
 276     g_value_unset (value_array->values + index);
 277   value_array->n_values--;
 278   if (index < value_array->n_values)
 279     g_memmove (value_array->values + index, value_array->values + index + 1,
 280                (value_array->n_values - index) * sizeof (value_array->values[0]));
 281   value_array_shrink (value_array);
 282   if (value_array->n_prealloced > value_array->n_values)
 283     memset (value_array->values + value_array->n_values, 0, sizeof (value_array->values[0]));
 284
 285   return value_array;
 286 }
 287
 288 /**
 289  * g_value_array_sort:
 290  * @value_array: #GValueArray to sort
 291  * @compare_func: function to compare elements
 292  *
 293  * Sort @value_array using @compare_func to compare the elements accoring to
 294  * the semantics of #GCompareFunc.
 295  *
 296  * The current implementation uses Quick-Sort as sorting algorithm.
 297  *
 298  * Returns: the #GValueArray passed in as @value_array
 299  */
 300 GValueArray*
 301 g_value_array_sort (GValueArray *value_array,
 302                     GCompareFunc compare_func)
 303 {
 304   g_return_val_if_fail (compare_func != NULL, NULL);
 305
 306   if (value_array->n_values)
 307     qsort (value_array->values,
 308            value_array->n_values,
 309            sizeof (value_array->values[0]),
 310            compare_func);
 311   return value_array;
 312 }
 313
 314 /**
 315  * g_value_array_sort_with_data:
 316  * @value_array: #GValueArray to sort
 317  * @compare_func: function to compare elements
 318  * @user_data: extra data argument provided for @compare_func
 319  *
 320  * Sort @value_array using @compare_func to compare the elements accoring
 321  * to the semantics of #GCompareDataFunc.
 322  *
 323  * The current implementation uses Quick-Sort as sorting algorithm.
 324  *
 325  * Returns: the #GValueArray passed in as @value_array
 326  */
 327 GValueArray*
 328 g_value_array_sort_with_data (GValueArray     *value_array,
 329                               GCompareDataFunc compare_func,
 330                               gpointer         user_data)
 331 {
 332   g_return_val_if_fail (value_array != NULL, NULL);
 333   g_return_val_if_fail (compare_func != NULL, NULL);
 334
 335   if (value_array->n_values)
 336     g_qsort_with_data (value_array->values,
 337                        value_array->n_values,
 338                        sizeof (value_array->values[0]),
 339                        compare_func, user_data);
 340   return value_array;
 341 }