| Top | |
|
|
|
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.
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.
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.
GType
egg_dbus_array_seq_get_element_type (EggDBusArraySeq *array_seq);
Gets the type of the elements stored in array_seq
.
GEqualFunc
egg_dbus_array_seq_get_equal_func (EggDBusArraySeq *array_seq);
Gets the GEqualFunc used for comparing equality of elements.
gboolean
egg_dbus_array_seq_have_copy_func (EggDBusArraySeq *array_seq);
Checks if array_seq
have a copy function.
guint
egg_dbus_array_seq_get_size (EggDBusArraySeq *array_seq);
Gets the size of array_seq
.
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
.
void
egg_dbus_array_seq_clear (EggDBusArraySeq *array_seq);
Removes all elements from array_seq
.
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.
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).
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.
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
.
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.
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.
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
.
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).
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).
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).
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 |
||
other_array_seq |
Another EggDBusArraySeq with elements of the same type as |
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 |
||
other_array_seq |
Another EggDBusArraySeq with elements of the same type as |
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.
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.
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.
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.
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.
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.
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.
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.
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.