manpagez: man pages & more
html files: eggdbus
Home | html | info | man

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.
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.