docs/reference/gobject/tmpl/value_arrays.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Value arrays
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A #GValueArray is a container structure to maintain an array of #GValue elements.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The prime purpose of a #GValueArray is for it to be used as an object property
  10 that holds an array of values. A #GValueArray wraps an array of #GValue elements
  11 in order for it to be used as a boxed type through %G_TYPE_VALUE_ARRAY.
  12 </para>
  13
  14 <!-- ##### SECTION See_Also ##### -->
  15 <para>
  16 #GValue, #GParamSpecValueArray, g_param_spec_value_array()
  17 </para>
  18
  19 <!-- ##### STRUCT GValueArray ##### -->
  20 <para>
  21 </para>
  22
  23 @n_values:     number of values contained in the array
  24 @values:       array of values
  25
  26 <!-- ##### FUNCTION g_value_array_get_nth ##### -->
  27 <para>
  28 Return a pointer to the value at @index containd in @value_array.
  29 </para>
  30
  31 @value_array: #GValueArray to get a value from
  32 @index:       index of the value of interest
  33 @Returns:     pointer to a value at @index in @value_array
  34
  35
  36 <!-- ##### FUNCTION g_value_array_new ##### -->
  37 <para>
  38 Allocate and initialize a new #GValueArray, optionally preserve space
  39 for @n_prealloced elements. New arrays always contain 0 elements,
  40 regardless of the value of @n_prealloced.
  41 </para>
  42
  43 @n_prealloced: number of values to preallocate space for
  44 @Returns:      a newly allocated #GValueArray with 0 values
  45
  46
  47 <!-- ##### FUNCTION g_value_array_copy ##### -->
  48 <para>
  49 Construct an exact copy of a #GValueArray by duplicating all its
  50 contents.
  51 </para>
  52
  53 @value_array: #GValueArray to copy
  54 @Returns:     Newly allocated copy of #GValueArray
  55
  56
  57 <!-- ##### FUNCTION g_value_array_free ##### -->
  58 <para>
  59 Free a #GValueArray including its contents.
  60 </para>
  61
  62 @value_array:
  63
  64
  65 <!-- ##### FUNCTION g_value_array_append ##### -->
  66 <para>
  67 Insert a copy of @value as last element of @value_array.
  68 </para>
  69
  70 @value_array: #GValueArray to add an element to
  71 @value:       #GValue to copy into #GValueArray
  72 @Returns:     the #GValueArray passed in as @value_array
  73
  74
  75 <!-- ##### FUNCTION g_value_array_prepend ##### -->
  76 <para>
  77 Insert a copy of @value as first element of @value_array.
  78 </para>
  79
  80 @value_array: #GValueArray to add an element to
  81 @value:       #GValue to copy into #GValueArray
  82 @Returns:     the #GValueArray passed in as @value_array
  83
  84
  85 <!-- ##### FUNCTION g_value_array_insert ##### -->
  86 <para>
  87 Insert a copy of @value at specified position into @value_array.
  88 </para>
  89
  90 @value_array: #GValueArray to add an element to
  91 @index:       insertion position, must be &lt;= value_array-&gt;n_values
  92 @value:       #GValue to copy into #GValueArray
  93 @Returns:     the #GValueArray passed in as @value_array
  94
  95
  96 <!-- ##### FUNCTION g_value_array_remove ##### -->
  97 <para>
  98 Remove the value at position @index from @value_array.
  99 </para>
 100
 101 @value_array: #GValueArray to remove an element from
 102 @index:       position of value to remove, must be &lt; value_array->n_values
 103 @Returns:     the #GValueArray passed in as @value_array
 104
 105
 106 <!-- ##### FUNCTION g_value_array_sort ##### -->
 107 <para>
 108 Sort @value_array using @compare_func to compare the elements accoring to
 109 the semantics of #GCompareFunc.
 110 </para>
 111
 112 <para>
 113 The current implementation uses Quick-Sort as sorting algorithm.
 114 </para>
 115
 116 @value_array:  #GValueArray to sort
 117 @compare_func: function to compare elements
 118 @Returns:      the #GValueArray passed in as @value_array
 119
 120
 121 <!-- ##### FUNCTION g_value_array_sort_with_data ##### -->
 122 <para>
 123 Sort @value_array using @compare_func to compare the elements accoring
 124 to the semantics of #GCompareDataFunc.
 125 </para>
 126
 127 <para>
 128 The current implementation uses Quick-Sort as sorting algorithm.
 129 </para>
 130
 131 @value_array:   #GValueArray to sort
 132 @compare_func:  function to compare elements
 133 @user_data:     extra data argument provided for @compare_func
 134 @Returns:       the #GValueArray passed in as @value_array
 135
 136