EggDBusArraySeq

EggDBusArraySeq — Arrays

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── EggDBusArraySeq

Description

An array type that can store elements of a given GType. See egg_dbus_array_seq_new() for details.

The array will automatically grow when elements are added and all accessor functions dealing with index-based access checks if the index is within bounds. If an index is not within the bounds of the array a warning is issued using g_error() (causing program termination).

When possible (when the elements are derived from GObject) type checking will be performed to ensure an inserted element is compatible with the element type of the array. If the check fails, a warning is issued using g_error() (causing program termination).

For implementing operations that involve comparing elements (such as egg_dbus_array_seq_contains()), a GEqualFunc is needed. For most types (such as G_TYPE_STRING and G_TYPE_INT), the natural GEqualFunc is used but for e.g. G_TYPE_OBJECT derived types one will need to be provided. Note that said operations are optional in the sense that if a GEqualFunc is not provided other operations will still work; the operations needing the equal function will just fail and call g_error() (causing program termination).

By default, the array takes ownership when inserting elements meaning that the programmer gives up his reference. Elements extracted from the array are owned by the array. There is also convenience API to get a copy of the item, see egg_dbus_array_seq_get_copy().

Note that this class exposes a number of implementation details directly in the class instance structure for efficient and convenient access when used from the C programming language. Use with caution. For the same reasons, this class also provides a number of convenience functions for dealing with fixed-size integral and floating point numbers.

Functions

egg_dbus_array_seq_new ()

EggDBusArraySeq *
egg_dbus_array_seq_new (GType element_type,
                        GDestroyNotify free_func,
                        GBoxedCopyFunc copy_func,
                        GEqualFunc equal_func);

Creates a new array that holds elements of element_type and uses free_func to free elements when they are no longer in use (e.g. when removed from the array either directly by calling e.g. egg_dbus_array_seq_remove_at() or if replaced by another element through egg_dbus_array_seq_set()). If free_func is NULL, then it is the responsibility of the owner of the array to free the elements when they are no longer used.

If copy_func is NULL, the default copy function is used if one exists for element_type (for example there is no default copy function if element_type is G_TYPE_POINTER). Note that optional methods such as egg_dbus_array_seq_get_copy() won't work if there is no copy function.

If equal_func is NULL, the default equality function is used if one exists for element_type (for example there is no default equality function if element_type is a subtype of G_TYPE_OBJECT, G_TYPE_INTERFACE or G_TYPE_BOXED). Note that optional methods such as egg_dbus_array_seq_contains() won't work if there is no equality function.

If the type of elements is not a fixed-size type (such as GObject derived types), the array will store pointers and all value pointers to and from this class are to the actual elements (the array is simply an array of pointers). For example, to implement equal_func when element_type is G_TYPE_FILE, one would do the following:

static gboolean
my_file_equal_func (gconstpointer _a, gconstpointer _b)
{
  GVolume *a = G_FILE (_a);
  GVolume *b = G_FILE (_b)
  gboolean is_equal;

  /* compute is_equal by comparing a and b */

  return is_equal;
}

or, in this specific case, just pass g_file_equal() as equal_func .

If the type of the elements is a fixed-size type (such as G_TYPE_INT, G_TYPE_DOUBLE or a G_TYPE_ENUM derived type), all value pointers used throughout this class is for the address of where the fixed-size value is stored inside the array. This is because the raw value are stored in the array; as such no pointers to elements are ever used (in addition, this means that free_func and copy_func are never used on such arrays). For example, for G_TYPE_DOUBLE, you'd define equal_func like this:

static gboolean
my_double_equal_func (gconstpointer _a, gconstpointer _b)
{
  gdouble a = *((gdouble *) _a);
  gdouble b = *((gdouble *) _b);
  gboolean is_equal;

  /* compute is_equal by comparing a and b */

  return is_equal;
}

Note that the default equality functions for integral and floating point types should be good enough for all but exotic corner cases.

Parameters

element_type

The type of the elements in the array.

 

free_func

Function to be used to free elements or NULL.

 

copy_func

Function to be used to copy elements or NULL to use the default copy function.

 

equal_func

Function to be used for comparing equality or NULL to use the default equality function.

 

Returns

A new EggDBusArraySeq. Free with g_object_unref().


egg_dbus_array_seq_get_element_size ()

gsize
egg_dbus_array_seq_get_element_size (EggDBusArraySeq *array_seq);

Gets the size of each element.

If array_seq contains elements on non-fixed size, sizeof gpointer is returned.

Parameters

array_seq

A EggDBusArraySeq.

 

Returns

The size, in bytes, of each element.


egg_dbus_array_seq_get_element_type ()

GType
egg_dbus_array_seq_get_element_type (EggDBusArraySeq *array_seq);

Gets the type of the elements stored in array_seq .

Parameters

array_seq

A EggDBusArraySeq.

 

Returns

The GType of for the elements in array_seq .


egg_dbus_array_seq_get_equal_func ()

GEqualFunc
egg_dbus_array_seq_get_equal_func (EggDBusArraySeq *array_seq);

Gets the GEqualFunc used for comparing equality of elements.

Parameters

array_seq

A EggDBusArraySeq.

 

Returns

A GEqualFunc.


egg_dbus_array_seq_have_copy_func ()

gboolean
egg_dbus_array_seq_have_copy_func (EggDBusArraySeq *array_seq);

Checks if array_seq have a copy function.

Parameters

array_seq

A EggDBusArraySeq.

 

Returns

TRUE only if there is a copy function for array_seq .


egg_dbus_array_seq_get_size ()

guint
egg_dbus_array_seq_get_size (EggDBusArraySeq *array_seq);

Gets the size of array_seq .

Parameters

array_seq

A EggDBusArraySeq.

 

Returns

The number of elements in array_seq .


egg_dbus_array_seq_set_size ()

void
egg_dbus_array_seq_set_size (EggDBusArraySeq *array_seq,
                             guint size);

Sets the size of array_seq to size .

If size is less than the current size, then elements with indices greater or equal than size will be freed.

If size is greater than the current size, the newly added elements will be set to either NULL or 0 depending on the GType of the elements of array_seq .

Parameters

array_seq

A EggDBusArraySeq.

 

size

New size of the array.

 

egg_dbus_array_seq_clear ()

void
egg_dbus_array_seq_clear (EggDBusArraySeq *array_seq);

Removes all elements from array_seq .

Parameters

array_seq

A EggDBusArraySeq.

 

egg_dbus_array_seq_get ()

gpointer
egg_dbus_array_seq_get (EggDBusArraySeq *array_seq,
                        gint index);

Gets the element at index from array_seq .

Note that the returned element is owned by array_seq and may be invalid if later removed from the array. If you want a copy, use egg_dbus_array_seq_get_copy() instead.

This is a constant-time operation.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

Returns

The requested element which is owned by array_seq .


egg_dbus_array_seq_get_copy ()

gpointer
egg_dbus_array_seq_get_copy (EggDBusArraySeq *array_seq,
                             gint index);

Gets a copy of the element at index from array_seq . If you don't want your own copy use egg_dbus_array_seq_get() instead.

This method is optional as some element types (for example G_TYPE_POINTER and derived types) have no natural copy function and one might not have been set when array_seq was constructed. It is a programming error to call this method on array_seq if there is no copy function on array_seq (a warning will be printed using g_error() causing program termination).

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

Returns

A copy of the requested element. Free with the appropriate function depending on the element type of array_seq .


egg_dbus_array_seq_set ()

void
egg_dbus_array_seq_set (EggDBusArraySeq *array_seq,
                        gint index,
                        gconstpointer value);

Replaces the element at index in array_seq with value .

Note that this function steals your reference to value .

This is a constant-time operation.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

value

The value to insert.

 

egg_dbus_array_seq_insert ()

void
egg_dbus_array_seq_insert (EggDBusArraySeq *array_seq,
                           gint index,
                           gconstpointer value);

Inserts value at index of array_seq . All elements currently at or after index will be shifted up by one and the size of array_seq will grow by one.

Note that this function steals your reference to value .

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

value

The value to append.

 

egg_dbus_array_seq_add ()

gboolean
egg_dbus_array_seq_add (EggDBusArraySeq *array_seq,
                        gconstpointer value);

Appends value to the end of array_seq . The size of array_seq will grow by one.

Note that this function steals your reference to value .

This is a constant time operation.

Parameters

array_seq

A EggDBusArraySeq.

 

value

The value to append.

 

Returns

Always TRUE.


egg_dbus_array_seq_remove_at ()

void
egg_dbus_array_seq_remove_at (EggDBusArraySeq *array_seq,
                              gint index);

Removes the element at index from array_seq . All elements following index will be shifted down by one and the size of array_seq will shrink by one.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

egg_dbus_array_seq_remove_range_at ()

void
egg_dbus_array_seq_remove_range_at (EggDBusArraySeq *array_seq,
                                    gint index,
                                    guint size);

Like egg_dbus_array_seq_remove_at() but removes size consecutive elements starting from index .

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

size

The number of elements to remove starting from index .

 

egg_dbus_array_seq_index_of ()

gint
egg_dbus_array_seq_index_of (EggDBusArraySeq *array_seq,
                             gconstpointer value);

Find the first occurence of an element equal to value in array_seq .

This method is optional. It is a programing error to call this method on array_seq if there is no GEqualFunc set for array_seq (a warning will be printed using g_error() causing program termination).

Parameters

array_seq

A EggDBusArraySeq.

 

value

The value to check for.

 

Returns

The index of the first occurence of an element equal to value in array_seq or -1 if no such elements exist.


egg_dbus_array_seq_contains ()

gboolean
egg_dbus_array_seq_contains (EggDBusArraySeq *array_seq,
                             gconstpointer value);

Check if array_seq contains an element equal to value .

This method is optional. It is a programing error to call this method on array_seq if there is no GEqualFunc set for array_seq (a warning will be printed using g_error() causing program termination).

Parameters

array_seq

A EggDBusArraySeq.

 

value

The value to check for.

 

Returns

TRUE if array_seq contains one or more elements equal to value .


egg_dbus_array_seq_remove ()

gboolean
egg_dbus_array_seq_remove (EggDBusArraySeq *array_seq,
                           gconstpointer value);

Remove the first occurence of elements equal to value from array_seq .

This method is optional. It is a programing error to call this method on array_seq if there is no GEqualFunc set for array_seq (a warning will be printed using g_error() causing program termination).

Parameters

array_seq

A EggDBusArraySeq.

 

value

The value to remove.

 

Returns

TRUE if an element was removed.


egg_dbus_array_seq_add_all ()

gboolean
egg_dbus_array_seq_add_all (EggDBusArraySeq *array_seq,
                            EggDBusArraySeq *other_array_seq);

Appends a copy of all elements from other_array_seq to array_seq . If you don't want to copy the elements, use egg_dbus_array_seq_steal_all() instead.

If array_seq and other_array_seq does not contain elements of the same type, a warning will be printed using g_error() (causing program termination).

This method is optional as some element types (for example G_TYPE_POINTER and derived types) have no natural copy function and one might not have been set when array_seq was constructed. It is a programming error to call this method on array_seq if there is no copy function on array_seq (a warning will be printed using g_error() causing program termination).

It is valid to call this method with array_seq and other_array_seq being the same array.

Parameters

array_seq

A EggDBusArraySeq.

 

other_array_seq

Another EggDBusArraySeq with elements of the same type as array_seq or NULL.

 

Returns

Always TRUE.


egg_dbus_array_seq_steal_all ()

gboolean
egg_dbus_array_seq_steal_all (EggDBusArraySeq *array_seq,
                              EggDBusArraySeq *other_array_seq);

Steals all elements from other_array_seq and appends them to array_seq . When this method returns there will be no more elements in other_array_seq . If you only want to copy the elements, use egg_dbus_array_seq_add_all() instead.

If array_seq and other_array_seq does not contain elements of the same type, a warning will be printed using g_error() (causing program termination).

It is an error to call this method if array_seq and other_array_seq is equal.

Parameters

array_seq

A EggDBusArraySeq.

 

other_array_seq

Another EggDBusArraySeq with elements of the same type as array_seq or NULL.

 

Returns

Always TRUE.


egg_dbus_array_seq_add_fixed ()

gboolean
egg_dbus_array_seq_add_fixed (EggDBusArraySeq *array_seq,
                              guint64 value);

Appends value to the end of array_seq . The size of array_seq will grow by one.

This is a C convenience function for fixed-size integral types such as G_TYPE_UCHAR, G_TYPE_INT and so on.

Parameters

array_seq

A EggDBusArraySeq.

 

value

The value to append.

 

Returns

Always TRUE.


egg_dbus_array_seq_add_float ()

gboolean
egg_dbus_array_seq_add_float (EggDBusArraySeq *array_seq,
                              gdouble value);

Appends value to the end of array_seq . The size of array_seq will grow by one.

This is a C convenience function for the floating point types G_TYPE_FLOAT and G_TYPE_DOUBLE.

Parameters

array_seq

A EggDBusArraySeq.

 

value

The value to append.

 

Returns

Always TRUE.


egg_dbus_array_seq_set_fixed ()

void
egg_dbus_array_seq_set_fixed (EggDBusArraySeq *array_seq,
                              gint index,
                              guint64 value);

Replaces the element at index in array_seq with value .

This is a C convenience function for fixed-size integral types such as G_TYPE_UCHAR, G_TYPE_INT and so on.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

value

The value to insert.

 

egg_dbus_array_seq_set_float ()

void
egg_dbus_array_seq_set_float (EggDBusArraySeq *array_seq,
                              gint index,
                              gdouble value);

Replaces the element at index in array_seq with value .

This is a C convenience function for the floating point types G_TYPE_FLOAT and G_TYPE_DOUBLE.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

value

The value to insert.

 

egg_dbus_array_seq_insert_fixed ()

void
egg_dbus_array_seq_insert_fixed (EggDBusArraySeq *array_seq,
                                 gint index,
                                 guint64 value);

Inserts value at index of array_seq . All elements currently at or after index will be shifted up by one and the size of array_seq will grow by one.

This is a C convenience function for fixed-size integral types such as G_TYPE_UCHAR, G_TYPE_INT and so on.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

value

The value to append.

 

egg_dbus_array_seq_insert_float ()

void
egg_dbus_array_seq_insert_float (EggDBusArraySeq *array_seq,
                                 gint index,
                                 gdouble value);

Inserts value at index of array_seq . All elements currently at or after index will be shifted up by one and the size of array_seq will grow by one.

This is a C convenience function for the floating point types G_TYPE_FLOAT and G_TYPE_DOUBLE.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

value

The value to append.

 

egg_dbus_array_seq_get_fixed ()

guint64
egg_dbus_array_seq_get_fixed (EggDBusArraySeq *array_seq,
                              gint index);

Gets the element at index from array_seq .

This is a C convenience function for fixed-size integral types such as G_TYPE_UCHAR, G_TYPE_INT and so on.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

Returns

The requested element.


egg_dbus_array_seq_get_float ()

gdouble
egg_dbus_array_seq_get_float (EggDBusArraySeq *array_seq,
                              gint index);

Gets the element at index from array_seq .

This is a C convenience function for the floating point types G_TYPE_FLOAT and G_TYPE_DOUBLE.

Parameters

array_seq

A EggDBusArraySeq.

 

index

Zero-based index of element.

 

Returns

The requested element.

Types and Values

EggDBusArraySeq

typedef struct {
  guint                 size;
  GType                 element_type;
  gsize                 element_size;
  union
  {
    gpointer            data;
    gpointer           *v_ptr;
    guchar             *v_byte;
    gint16             *v_int16;
    guint16            *v_uint16;
    gint               *v_int;
    guint              *v_uint;
    gint64             *v_int64;
    guint64            *v_uint64;
    glong              *v_long;
    gulong             *v_ulong;
    gboolean           *v_boolean;
    gfloat             *v_float;
    gdouble            *v_double;
    gchar             **v_str;
    gchar            ***v_strv;
  } data;
} EggDBusArraySeq;

The EggDBusArraySeq instance structure should normally not be accessed directly, use accessor functions instead. Certain instance members are provided only for efficient and convenient access when using the C programming language. Use with caution.

Members

guint size;

Number of elements in the array.

 

GType element_type;

The GType of the elements in the array.

 

gsize element_size;

The size, in bytes, of each element.