Top | ![]() |
![]() |
![]() |
![]() |
#define | GWY_CONTAINER_PATHSEP |
#define | GWY_CONTAINER_PATHSEP_STR |
struct | GwyContainer |
struct | GwyContainerClass |
GwyContainer is a general-purpose container, it can hold atomic types, strings and objects. However, objects must implement the GwySerializable interface, because the container itself is serializable.
A new container can be created with gwy_container_new()
, items can be stored with function like
gwy_container_set_double()
, read with gwy_container_get_double()
, and removed with gwy_container_remove()
or
gwy_container_remove_by_prefix()
. A presence of a value can be tested with gwy_container_contains()
, convenience
functions for reading (updating) a value only if it is present like gwy_container_gis_double()
, are available too.
GwyContainer takes ownership of stored non-atomic items. For strings, this means you cannot store static strings
(use g_strdup()
to duplicate them), and must not free stored dynamic strings, as the container will free them
itself when they are removed or when the container is finalized. For objects, this means it takes a reference on
the object (released when the object is removed or the container is finalized), so you usually want to
g_object_unref()
objects after storing them to a container.
Items in a GwyContainer can be identified by a GQuark or the corresponding string. While GQuark's are atomic
values and allow faster acces, they are less convenient for casual usage -- each GQuark key function like
gwy_container_set_double()
thus has a string-key counterpart gwy_container_set_double_by_name()
.
guint
gwy_container_get_n_items (GwyContainer *container
);
Gets the number of items in a container.
GType gwy_container_value_type (GwyContainer *container
,GQuark key
);
Returns the type of value in container
identified by key
.
gboolean gwy_container_contains (GwyContainer *container
,GQuark key
);
Returns TRUE
if container
contains a value identified by key
.
GValue gwy_container_get_value (GwyContainer *container
,GQuark key
);
Returns the value in container
identified by key
.
gboolean gwy_container_gis_value (GwyContainer *container
,GQuark key
,GValue *value
);
Get-if-set a generic value from a container.
void gwy_container_set_value (GwyContainer *container
,GQuark key
,GValue *value
);
Inserts or updates one value in a container.
The value is copied and the caller remains responsible for unsetting value
.
gboolean gwy_container_remove (GwyContainer *container
,GQuark key
);
Removes a value identified by key
from a container.
guint gwy_container_remove_by_prefix (GwyContainer *container
,const gchar *prefix
);
Removes a values whose key start with prefix
from container container
.
prefix
can be NULL
, all values are then removed.
GwyContainer * gwy_container_duplicate_by_prefix (GwyContainer *container
,...
);
Duplicates a container keeping only values under given prefixes.
Like gwy_container_copy()
, this method creates a deep copy, that is contained object are physically duplicated
too, not just referenced again.
GwyContainer * gwy_container_duplicate_by_prefixv (GwyContainer *container
,guint n
,const gchar **prefixes
);
Duplicates a container keeping only values under given prefixes.
Like gwy_container_copy()
, this method creates a deep copy, that is contained object are physically duplicated
too, not just referenced again.
gint gwy_container_transfer (GwyContainer *source
,GwyContainer *dest
,const gchar *source_prefix
,const gchar *dest_prefix
,gboolean deep
,gboolean force
);
Copies a items from one place in container to another place.
The copies are shallow, objects are not physically duplicated, only referenced in dest
, unless deep
is TRUE
.
The order in which items are transferred is not defined. Signals for all changed items are emitted after the transfer is finished (not during transfer).
Source items within source_prefix
are not allowed to change during the transfer. This is mostly relevant when
force
is TRUE
and existing destination objects are finalised or deep
is TRUE
and new objects are created,
either of which could have cascading effects.
source |
Source container. |
|
dest |
Destination container. It may be the same container as |
|
source_prefix |
Prefix in |
|
dest_prefix |
Prefix in |
|
deep |
|
|
force |
|
gboolean gwy_container_rename (GwyContainer *container
,GQuark key
,GQuark newkey
,gboolean force
);
Makes a value in container
identified by key
to be identified by newkey
.
When force
is TRUE
existing value at newkey
is removed from container
. When it's FALSE
, an existing value
newkey
inhibits the rename and FALSE
is returned.
guint gwy_container_foreach (GwyContainer *container
,const gchar *prefix
,GHFunc function
,gpointer user_data
);
Calls function
on each container
item whose identifier starts with prefix
.
The function is called function
(GQuark key, GValue *value, user_data).
GQuark *
gwy_container_keys (GwyContainer *container
);
Gets all quark keys of a container.
A newly allocated 0-terminated array with quark keys of all dict
items, in no particular order. The
number of items can be obtained with gwy_container_get_n_items()
.
[array zero-terminated=1]
const gchar **
gwy_container_keys_by_name (GwyContainer *container
);
Gets all string keys of a container.
A newly allocated array with string keys of all container
items, in no particular order. The number of
items can be obtained with gwy_container_get_n_items()
. Unlike the array the strings are owned by GLib
and must not be freed.
[transfer container][array zero-terminated=1]
GQuark * gwy_container_keys_with_prefix (GwyContainer *container
,const gchar *prefix
,guint *n
);
Gets quark keys of a container that start with given prefix.
const gchar ** gwy_container_keys_with_prefix_by_name (GwyContainer *container
,const gchar *prefix
,guint *n
);
Gets string keys of a container that start with given prefix.
void gwy_container_set_boolean (GwyContainer *container
,GQuark key
,gboolean value
);
Stores a boolean into container
, identified by key
.
gboolean gwy_container_get_boolean (GwyContainer *container
,GQuark key
);
Returns the boolean in container
identified by key
.
gboolean gwy_container_gis_boolean (GwyContainer *container
,GQuark key
,gboolean *value
);
Get-if-set a boolean from a container.
void gwy_container_set_uchar (GwyContainer *container
,GQuark key
,guchar value
);
Stores an unsigned character into container
, identified by key
.
guchar gwy_container_get_uchar (GwyContainer *container
,GQuark key
);
Returns the unsigned character in container
identified by key
.
gboolean gwy_container_gis_uchar (GwyContainer *container
,GQuark key
,guchar *value
);
Get-if-set an unsigned char from a container.
void gwy_container_set_int32 (GwyContainer *container
,GQuark key
,gint32 value
);
Stores a 32bit integer into container
, identified by key
.
gint32 gwy_container_get_int32 (GwyContainer *container
,GQuark key
);
Returns the 32bit integer in container
identified by key
.
gboolean gwy_container_gis_int32 (GwyContainer *container
,GQuark key
,gint32 *value
);
Get-if-set a 32bit integer from a container.
void gwy_container_set_enum (GwyContainer *container
,GQuark key
,guint value
);
Stores an enum into container
, identified by key
.
Note enums are treated as 32bit integers.
guint gwy_container_get_enum (GwyContainer *container
,GQuark key
);
Returns the enum in container
identified by key
.
Note enums are treated as 32bit integers.
gboolean gwy_container_gis_enum (GwyContainer *container
,GQuark key
,guint *value
);
Get-if-set an enum from a container.
Note enums are treated as 32bit integers.
void gwy_container_set_int64 (GwyContainer *container
,GQuark key
,gint64 value
);
Stores a 64bit integer into container
, identified by key
.
gint64 gwy_container_get_int64 (GwyContainer *container
,GQuark key
);
Returns the 64bit integer in container
identified by key
.
gboolean gwy_container_gis_int64 (GwyContainer *container
,GQuark key
,gint64 *value
);
Get-if-set a 64bit integer from a container.
void gwy_container_set_double (GwyContainer *container
,GQuark key
,gdouble value
);
Stores a double into container
, identified by key
.
gdouble gwy_container_get_double (GwyContainer *container
,GQuark key
);
Returns the double in container
identified by key
.
gboolean gwy_container_gis_double (GwyContainer *container
,GQuark key
,gdouble *value
);
Get-if-set a double from a container.
void gwy_container_set_string (GwyContainer *container
,GQuark key
,gchar *value
);
Stores a string into container
, identified by key
.
Since the ownership is passed to the container, you must not access the string data afterwards. The container is
allowed to immediately free value
, for example, when it already holds an identical string at key
.
void gwy_container_set_const_string (GwyContainer *container
,GQuark key
,const gchar *value
);
Stores a string into container
, identified by key
.
The container makes a copy of the string, so it can be used on static strings.
const gchar * gwy_container_get_string (GwyContainer *container
,GQuark key
);
Returns the string in container
identified by key
.
The returned string must be treated as constant and never freed or modified.
gboolean gwy_container_gis_string (GwyContainer *container
,GQuark key
,const gchar **value
);
Get-if-set a string from a container.
The string possibly stored in value
must be treated as constant and never freed or modified.
void gwy_container_set_object (GwyContainer *container
,GQuark key
,gpointer value
);
Stores an object into container
, identified by key
.
The container claims ownership on the object, i.e. its reference count is incremented. Use
gwy_container_pass_object()
to pass your reference to container
.
The object must implement GwySerializable interface to allow serialization of the container.
void gwy_container_pass_object (GwyContainer *container
,GQuark key
,gpointer value
);
Stores an object into container
, identified by key
, passing reference to the container.
The reference on the object you hold is passed to container
. This is often useful when importing data as you do
not have to (in fact must not) release your reference afterwards. Use gwy_container_set_object()
if you want to
keep your reference.
The object must implement GwySerializable interface to allow serialization of the container.
gpointer gwy_container_get_object (GwyContainer *container
,GQuark key
);
Returns the object in container
identified by key
.
The returned object does not have its reference count increased, use g_object_ref()
if you want to access it even
when container
may cease to exist.
gboolean gwy_container_gis_object (GwyContainer *container
,GQuark key
,gpointer value
);
Get-if-set an object from a container.
The object possibly stored in value
doesn't have its reference count increased, use g_object_ref()
if you want
to access it even when container
may cease to exist.
void gwy_container_set_boxed (GwyContainer *container
,GQuark key
,GType type
,gpointer value
);
Stores a boxed pointer into container
, identified by key
.
The container makes a copy of the boxed pointer using g_boxed_copy()
. The caller remains responsible for freeing
it with g_boxed_free()
.
The boxed type must be serializable to allow serialization of the container.
void gwy_container_pass_boxed (GwyContainer *container
,GQuark key
,GType type
,gpointer value
);
Stores a boxed pointer into container
, identified by key
, passing ownership to the container.
Since the ownership is passed to the container, you must not access the boxed data afterwards. The container is
allowed to immediately free value
using g_boxed_free()
, for example, when it already holds an identical value at
key
. In general, since boxed pointers are not reference counted, passing the ownership is prone to subtle errors.
Unless you created the boxed pointer in order to just pass it to container
and forget about it, it is safer to use
gwy_container_set_boxed()
.
The boxed type must be serializable to allow serialization of the container.
gpointer gwy_container_get_boxed (GwyContainer *container
,GQuark key
,GType type
);
Returns the boxed pointer in container
identified by key
.
It is an error to request a boxed pointer of different type than is actually stored.
gboolean gwy_container_gis_boxed (GwyContainer *container
,GQuark key
,GType type
,gpointer value
);
Get-if-set a boxed pointer from a container.
It is an error to request a boxed pointer of different type than is actually stored.
The boxed possibly stored in value
is not a copy, remains owned by container
and may become invalid when its
contents changes. Use g_boxed_copy()
if you need a boxed pointer with controlled lifetime.
GwyContainer *
gwy_container_copy (GwyContainer *container
);
Create a new container as a copy of an existing one.
This function is a convenience gwy_serializable_copy()
wrapper.
void gwy_container_assign (GwyContainer *destination
,GwyContainer *source
);
Makes one container equal to another.
This function is a convenience gwy_serializable_assign()
wrapper.
GPtrArray *
gwy_container_serialize_to_text (GwyContainer *container
);
Creates a text representation of container
contents.
Note only simple data types are supported as serialization of compound objects is not controllable.
GwyContainer *
gwy_container_deserialize_from_text (const gchar *text
);
Restores a container from is text representation.
text |
Text containing serialized container contents as dumped by |
#define gwy_container_value_type_by_name(c,n) gwy_container_value_type(c,g_quark_try_string(n))
Gets the type of value in container c
identified by name n
.
#define gwy_container_contains_by_name(c,n) gwy_container_contains(c,g_quark_try_string(n))
Expands to TRUE
if container c
contains a value identified by name n
.
#define gwy_container_set_value_by_name(c,n,v) gwy_container_set_value(c,g_quark_from_string(n),v)
#define gwy_container_get_value_by_name(c,n) gwy_container_get_value(c,g_quark_from_string(n))
Gets the value in container c
identified by name n
.
#define gwy_container_gis_value_by_name(c,n,v) gwy_container_gis_value(c,g_quark_try_string(n),v)
Get-if-set a generic value from a container.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such value in the container.
#define gwy_container_remove_by_name(c,n) gwy_container_remove(c,g_quark_try_string(n))
Removes a value identified by name n
from container c
.
Expands to TRUE
if there was such a value and was removed.
#define gwy_container_rename_by_name(c,n,nn,f) gwy_container_rename(c,g_quark_try_string(n),g_quark_from_string(nn),f)
Makes a value in container c
identified by name n
to be identified by new name nn
.
See gwy_container_rename()
for details.
#define gwy_container_set_boolean_by_name(c,n,v) gwy_container_set_boolean(c,g_quark_from_string(n),v)
Stores a boolean into container c
, identified by name n
.
#define gwy_container_get_boolean_by_name(c,n) gwy_container_get_boolean(c,g_quark_from_string(n))
Gets the boolean in container c
identified by name n
.
#define gwy_container_gis_boolean_by_name(c,n,v) gwy_container_gis_boolean(c,g_quark_try_string(n),v)
Get-if-set a boolean from a container.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such boolean in the container.
#define gwy_container_set_uchar_by_name(c,n,v) gwy_container_set_uchar(c,g_quark_from_string(n),v)
Stores an unsigned character into container c
, identified by name n
.
#define gwy_container_get_uchar_by_name(c,n) gwy_container_get_uchar(c,g_quark_from_string(n))
Gets the unsigned character in container c
identified by name n
.
#define gwy_container_gis_uchar_by_name(c,n,v) gwy_container_gis_uchar(c,g_quark_try_string(n),v)
Get-if-set an unsigned char from a container.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such unsigned char in the container.
#define gwy_container_set_int32_by_name(c,n,v) gwy_container_set_int32(c,g_quark_from_string(n),v)
Stores a 32bit integer into container c
, identified by name n
.
#define gwy_container_get_int32_by_name(c,n) gwy_container_get_int32(c,g_quark_from_string(n))
Gets the 32bit integer in container c
identified by name n
.
#define gwy_container_gis_int32_by_name(c,n,v) gwy_container_gis_int32(c,g_quark_try_string(n),v)
Get-if-set a 32bit integer from a container.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such 32bit integer in the container.
#define gwy_container_set_enum_by_name(c,n,v) gwy_container_set_enum(c,g_quark_from_string(n),v)
Stores an enum into container c
, identified by name n
.
Note enums are treated as 32bit integers.
#define gwy_container_get_enum_by_name(c,n) gwy_container_get_enum(c,g_quark_from_string(n))
Gets the enum in container c
identified by name n
.
Note enums are treated as 32bit integers.
#define gwy_container_gis_enum_by_name(c,n,v) gwy_container_gis_enum(c,g_quark_try_string(n),v)
Get-if-set an enum from a container.
Note enums are treated as 32bit integers.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such enum in the container.
#define gwy_container_set_int64_by_name(c,n,v) gwy_container_set_int64(c,g_quark_from_string(n),v)
Stores a 64bit integer into container c
, identified by name n
.
#define gwy_container_get_int64_by_name(c,n) gwy_container_get_int64(c,g_quark_from_string(n))
Gets the 64bit integer in container c
identified by name n
.
#define gwy_container_gis_int64_by_name(c,n,v) gwy_container_gis_int64(c,g_quark_try_string(n),v)
Get-if-set a 64bit integer from a container.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such 64bit integer in the container.
#define gwy_container_set_double_by_name(c,n,v) gwy_container_set_double(c,g_quark_from_string(n),v)
Stores a double into container c
, identified by name n
.
#define gwy_container_get_double_by_name(c,n) gwy_container_get_double(c,g_quark_from_string(n))
Gets the double in container c
identified by name n
.
#define gwy_container_gis_double_by_name(c,n,v) gwy_container_gis_double(c,g_quark_try_string(n),v)
Get-if-set a double from a container.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such double in the container.
#define gwy_container_set_string_by_name(c,n,v) gwy_container_set_string(c,g_quark_from_string(n),v)
Stores a string into container c
, identified by name n
.
See gwy_container_set_string()
for details.
#define gwy_container_set_const_string_by_name(c,n,v) gwy_container_set_const_string(c,g_quark_from_string(n),v)
Stores a string into container c
, identified by name n
.
The container makes a copy of the string, so it can be used on static strings.
#define gwy_container_get_string_by_name(c,n) gwy_container_get_string(c,g_quark_from_string(n))
Gets the string in container c
identified by name n
.
The returned string must be treated as constant and never freed or modified.
#define gwy_container_gis_string_by_name(c,n,v) gwy_container_gis_string(c,g_quark_try_string(n),v)
Get-if-set a string from a container.
The string possibly stored in v
must be treated as constant and never freed or modified.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such string in the container.
#define gwy_container_set_object_by_name(c,n,v) gwy_container_set_object(c,g_quark_from_string(n),v)
Stores an object into container c
, identified by name n
.
See gwy_container_set_object()
for details.
#define gwy_container_pass_object_by_name(c,n,v) gwy_container_pass_object(c,g_quark_from_string(n),v)
Stores an object into container c
, identified by name n
, passing reference to the container.
See gwy_container_pass_object()
for details.
#define gwy_container_get_object_by_name(c,n) gwy_container_get_object(c,g_quark_from_string(n))
Gets the object in container c
identified by name n
.
The returned object does not have its reference count increased, use g_object_ref()
if you want to access it even
when container
may cease to exist.
#define gwy_container_gis_object_by_name(c,n,v) gwy_container_gis_object(c,g_quark_try_string(n),v)
Get-if-set an object from a container.
The object possibly stored in value
doesn't have its reference count increased, use g_object_ref()
if you want
to access it even when container
may cease to exist.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such object in the container.
#define gwy_container_set_boxed_by_name(c,n,t,v) gwy_container_set_boxed(c,g_quark_from_string(n),t,v)
Stores a boxed pointer into container c
, identified by name n
.
See gwy_container_set_boxed()
for details.
#define gwy_container_pass_boxed_by_name(c,n,t,v) gwy_container_pass_boxed(c,g_quark_from_string(n),t,v)
Stores an boxed pointer into container c
, identified by name n
, passing ownership to the container.
See gwy_container_pass_boxed()
for details.
#define gwy_container_get_boxed_by_name(c,n,t) gwy_container_get_boxed(c,g_quark_from_string(n),t)
Gets the boxed pointer in container c
identified by name n
.
#define gwy_container_gis_boxed_by_name(c,n,t,v) gwy_container_gis_boxed(c,g_quark_try_string(n),t,v)
Get-if-set a boxed pointer from a container.
It is an error to request a boxed pointer of different type than is actually stored.
The boxed possibly stored in value
is not a copy, remains owned by container
and may become invalid when its
contents changes. Use g_boxed_copy()
if you need a boxed pointer with controlled lifetime.
Expands to TRUE
if value
was actually updated, FALSE
when there is no such boxed in the container.
#define GWY_CONTAINER_PATHSEP '/'
Path separator to be used for hierarchical structures in the container.
#define GWY_CONTAINER_PATHSEP_STR "/"
Path separator to be used for hierarchical structures in the container, as a string.
struct GwyContainer;
The GwyContainer struct contains private data only and should be accessed using the functions below.
“item-changed”
signalvoid user_function (GwyContainer *gwycontainer, guint arg1, gpointer user_data)
The ::item-changed signal is emitted whenever a container item is changed. The detail is the string key identifier.
gwycontainer |
The GwyContainer which received the signal. |
|
arg1 |
The quark key identifying the changed item. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Has Details