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 Quick-Sort as sorting algorithm.

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 Quick-Sort as sorting algorithm.

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