Value arrays

## Value arrays Value arrays — A container structure to maintain an array of generic values |

## Synopsis

    #include <glib-object.h>

    struct              GValueArray;
    GValue *            g_value_array_get_nth               (GValueArray *value_array,
                                                             guint index_);
    GValueArray *       g_value_array_new                   (guint n_prealloced);
    GValueArray *       g_value_array_copy                  (const GValueArray *value_array);
    void                g_value_array_free                  (GValueArray *value_array);
    GValueArray *       g_value_array_append                (GValueArray *value_array,
                                                             const GValue *value);
    GValueArray *       g_value_array_prepend               (GValueArray *value_array,
                                                             const GValue *value);
    GValueArray *       g_value_array_insert                (GValueArray *value_array,
                                                             guint index_,
                                                             const GValue *value);
    GValueArray *       g_value_array_remove                (GValueArray *value_array,
                                                             guint index_);
    GValueArray *       g_value_array_sort                  (GValueArray *value_array,
                                                             GCompareFunc compare_func);
    GValueArray *       g_value_array_sort_with_data        (GValueArray *value_array,
                                                             GCompareDataFunc compare_func,
                                                             gpointer user_data);

## Description

The prime purpose of a GValueArray is for it to be used as an object property that holds an array of values. A GValueArray wraps an array of GValue elements in order for it to be used as a boxed type through `G_TYPE_VALUE_ARRAY`.

GValueArray is deprecated in favour of GArray since GLib 2.32. It is possible to create a GArray that behaves like a GValueArray by using the size of GValue as the element size, and by setting `g_value_unset()` as the clear function using `g_array_set_clear_func()`, for instance, the following code:

    1
    GValueArray *array = g_value_array_new (10);

can be replaced by:

    1
    2
    GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
    g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);

## Details

### struct GValueArray

    struct GValueArray {
      guint   n_values;
      GValue *values;
    };

A GValueArray contains an array of GValue elements.

guint `n_values`; | number of values contained in the array
GValue *`values`; | array of values

### g_value_array_get_nth ()

    GValue *            g_value_array_get_nth               (GValueArray *value_array,
                                                             guint index_);

### Warning

`g_value_array_get_nth` has been deprecated since version 2.32 and should not be used in newly-written code. Use `g_array_index()` instead.

Return a pointer to the value at `index_` containd in `value_array`.

`value_array` : | GValueArray to get a value from
`index_` : | index of the value of interest
Returns : | pointer to a value at `index_` in `value_array`. [transfer none]

### g_value_array_new ()

    GValueArray *       g_value_array_new                   (guint n_prealloced);

### Warning

`g_value_array_new` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_sized_new()` instead.

Allocate and initialize a new GValueArray, optionally preserve space for `n_prealloced` elements. New arrays always contain 0 elements, regardless of the value of `n_prealloced`.

`n_prealloced` : | number of values to preallocate space for
Returns : | a newly allocated GValueArray with 0 values

### g_value_array_copy ()

    GValueArray *       g_value_array_copy                  (const GValueArray *value_array);

### Warning

`g_value_array_copy` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_ref()` instead.

Construct an exact copy of a GValueArray by duplicating all its contents.

`value_array` : | GValueArray to copy
Returns : | Newly allocated copy of GValueArray. [transfer full]

### g_value_array_free ()

    void                g_value_array_free                  (GValueArray *value_array);

### Warning

`g_value_array_free` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_unref()` instead.

Free a GValueArray including its contents.

`value_array` : | GValueArray to free

### g_value_array_append ()

    GValueArray *       g_value_array_append                (GValueArray *value_array,
                                                             const GValue *value);

### Warning

`g_value_array_append` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_append_val()` instead.

Insert a copy of `value` as last element of `value_array`. If `value` is `NULL`, an uninitialized value is appended.

`value_array` : | GValueArray to add an element to
`value` : | GValue to copy into GValueArray, or `NULL`. [allow-none]
Returns : | the GValueArray passed in as `value_array`. [transfer none]

### g_value_array_prepend ()

    GValueArray *       g_value_array_prepend               (GValueArray *value_array,
                                                             const GValue *value);

### Warning

`g_value_array_prepend` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_prepend_val()` instead.

Insert a copy of `value` as first element of `value_array`. If `value` is `NULL`, an uninitialized value is prepended.

`value_array` : | GValueArray to add an element to
`value` : | GValue to copy into GValueArray, or `NULL`. [allow-none]
Returns : | the GValueArray passed in as `value_array`. [transfer none]

### g_value_array_insert ()

    GValueArray *       g_value_array_insert                (GValueArray *value_array,
                                                             guint index_,
                                                             const GValue *value);

### Warning

`g_value_array_insert` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_insert_val()` instead.

Insert a copy of `value` at specified position into `value_array`. If `value` is `NULL`, an uninitialized value is inserted.

`value_array` : | GValueArray to add an element to
`index_` : | insertion position, must be <= value_array->n_values
`value` : | GValue to copy into GValueArray, or `NULL`. [allow-none]
Returns : | the GValueArray passed in as `value_array`. [transfer none]

### g_value_array_remove ()

    GValueArray *       g_value_array_remove                (GValueArray *value_array,
                                                             guint index_);

### Warning

`g_value_array_remove` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_remove_index()` instead.

Remove the value at position `index_` from `value_array`.

`value_array` : | GValueArray to remove an element from
`index_` : | position of value to remove, which must be less than `value_array->n_values`
Returns : | the GValueArray passed in as `value_array`. [transfer none]

### g_value_array_sort ()

    GValueArray *       g_value_array_sort                  (GValueArray *value_array,
                                                             GCompareFunc compare_func);

### Warning

`g_value_array_sort` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_sort()`.

Sort `value_array` using `compare_func` to compare the elements according to the semantics of GCompareFunc.

The current implementation uses the same sorting algorithm as standard C `qsort()` function.

`value_array` : | GValueArray to sort
`compare_func` : | function to compare elements. [scope call]
Returns : | the GValueArray passed in as `value_array`. [transfer none]

### g_value_array_sort_with_data ()

    GValueArray *       g_value_array_sort_with_data        (GValueArray *value_array,
                                                             GCompareDataFunc compare_func,
                                                             gpointer user_data);

### Warning

`g_value_array_sort_with_data` has been deprecated since version 2.32 and should not be used in newly-written code. Use GArray and `g_array_sort_with_data()`.

Sort `value_array` using `compare_func` to compare the elements according to the semantics of GCompareDataFunc.

The current implementation uses the same sorting algorithm as standard C `qsort()` function.

Rename to: g_value_array_sort

`value_array` : | GValueArray to sort
`compare_func` : | function to compare elements. [scope call]
`user_data` : | extra data argument provided for `compare_func`. [closure]
Returns : | the GValueArray passed in as `value_array`. [transfer none]

## See Also

GValue, GParamSpecValueArray, `g_param_spec_value_array()`