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.

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.

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.

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.

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.

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.

egg_dbus_array_seq_get_size ()

guint               egg_dbus_array_seq_get_size         (EggDBusArraySeq *array_seq);

Gets the size of 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.

egg_dbus_array_seq_clear ()

void                egg_dbus_array_seq_clear            (EggDBusArraySeq *array_seq);

Removes all elements from array_seq.

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.

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

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.

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.

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.

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.

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.

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.