Value arrays: GObject Reference Manual

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

## Functions

GValue * | g_value_array_get_nth ()
GValueArray * | g_value_array_new ()
GValueArray * | g_value_array_copy ()
void | g_value_array_free ()
GValueArray * | g_value_array_append ()
GValueArray * | g_value_array_prepend ()
GValueArray * | g_value_array_insert ()
GValueArray * | g_value_array_remove ()
GValueArray * | g_value_array_sort ()
GValueArray * | g_value_array_sort_with_data ()

## Types and Values

struct | GValueArray

## Object Hierarchy

        GBoxed
        ╰── GValueArray

## Includes

    #include <glib-object.h>

## 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);

## Functions

### g_value_array_get_nth ()

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

`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` .

#### Parameters

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);

`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` .

#### Parameters

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);

`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.

#### Parameters

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);

`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.

[skip]

#### Parameters

value_array | GValueArray to free |

### g_value_array_append ()

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

`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.

#### Parameters

value_array | GValueArray to add an element to |
value | GValue to copy into GValueArray, or `NULL`. | [nullable]

#### 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);

`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.

#### Parameters

value_array | GValueArray to add an element to |
value | GValue to copy into GValueArray, or `NULL`. | [nullable]

#### 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);

`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.

#### Parameters

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`. | [nullable]

#### Returns

the GValueArray passed in as `value_array` .

[transfer none]

### g_value_array_remove ()

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

`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` .

#### Parameters

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);

`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.

#### Parameters

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);

`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]

#### Parameters

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]

## Types and Values

### struct GValueArray

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

A GValueArray contains an array of GValue elements.

#### Members

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

## See Also

GValue, GParamSpecValueArray, `g_param_spec_value_array()`