## EggDBusArraySeq EggDBusArraySeq — Arrays |

## Synopsis

                        EggDBusArraySeq;
    EggDBusArraySeq *   egg_dbus_array_seq_new              (GType element_type,
                                                             GDestroyNotify free_func,
                                                             GBoxedCopyFunc copy_func,
                                                             GEqualFunc equal_func);
    gsize               egg_dbus_array_seq_get_element_size (EggDBusArraySeq *array_seq);
    GType               egg_dbus_array_seq_get_element_type (EggDBusArraySeq *array_seq);
    GEqualFunc          egg_dbus_array_seq_get_equal_func   (EggDBusArraySeq *array_seq);
    gboolean            egg_dbus_array_seq_have_copy_func   (EggDBusArraySeq *array_seq);
    guint               egg_dbus_array_seq_get_size         (EggDBusArraySeq *array_seq);
    void                egg_dbus_array_seq_set_size         (EggDBusArraySeq *array_seq,
                                                             guint size);
    void                egg_dbus_array_seq_clear            (EggDBusArraySeq *array_seq);
    gpointer            egg_dbus_array_seq_get              (EggDBusArraySeq *array_seq,
                                                             gint index);
    gpointer            egg_dbus_array_seq_get_copy         (EggDBusArraySeq *array_seq,
                                                             gint index);
    void                egg_dbus_array_seq_set              (EggDBusArraySeq *array_seq,
                                                             gint index,
                                                             gconstpointer value);
    void                egg_dbus_array_seq_insert           (EggDBusArraySeq *array_seq,
                                                             gint index,
                                                             gconstpointer value);
    gboolean            egg_dbus_array_seq_add              (EggDBusArraySeq *array_seq,
                                                             gconstpointer value);
    void                egg_dbus_array_seq_remove_at        (EggDBusArraySeq *array_seq,
                                                             gint index);
    void                egg_dbus_array_seq_remove_range_at  (EggDBusArraySeq *array_seq,
                                                             gint index,
                                                             guint size);
    gint                egg_dbus_array_seq_index_of         (EggDBusArraySeq *array_seq,
                                                             gconstpointer value);
    gboolean            egg_dbus_array_seq_contains         (EggDBusArraySeq *array_seq,
                                                             gconstpointer value);
    gboolean            egg_dbus_array_seq_remove           (EggDBusArraySeq *array_seq,
                                                             gconstpointer value);
    gboolean            egg_dbus_array_seq_add_all          (EggDBusArraySeq *array_seq,
                                                             EggDBusArraySeq *other_array_seq);
    gboolean            egg_dbus_array_seq_steal_all        (EggDBusArraySeq *array_seq,
                                                             EggDBusArraySeq *other_array_seq);
    gboolean            egg_dbus_array_seq_add_fixed        (EggDBusArraySeq *array_seq,
                                                             guint64 value);
    gboolean            egg_dbus_array_seq_add_float        (EggDBusArraySeq *array_seq,
                                                             gdouble value);
    void                egg_dbus_array_seq_set_fixed        (EggDBusArraySeq *array_seq,
                                                             gint index,
                                                             guint64 value);
    void                egg_dbus_array_seq_set_float        (EggDBusArraySeq *array_seq,
                                                             gint index,
                                                             gdouble value);
    void                egg_dbus_array_seq_insert_fixed     (EggDBusArraySeq *array_seq,
                                                             gint index,
                                                             guint64 value);
    void                egg_dbus_array_seq_insert_float     (EggDBusArraySeq *array_seq,
                                                             gint index,
                                                             gdouble value);
    guint64             egg_dbus_array_seq_get_fixed        (EggDBusArraySeq *array_seq,
                                                             gint index);
    gdouble             egg_dbus_array_seq_get_float        (EggDBusArraySeq *array_seq,
                                                             gint index);

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

## Details

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

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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

`array_seq` : | A EggDBusArraySeq.
`index` : | Zero-based index of element.
Returns : | The requested element.