## GwyContainer

GwyContainer — A container with items identified by a GQuark

## Synopsis

    #include <libgwyddion/gwyddion.h>

    #define             GWY_CONTAINER_PATHSEP
    #define             GWY_CONTAINER_PATHSEP_STR
                        GwyContainer;
                        GwyContainerClass;
    #define             gwy_container_duplicate             (container)
    GwyContainer*       gwy_container_new                   (void);
    guint               gwy_container_get_n_items           (GwyContainer *container);
    GType               gwy_container_value_type            (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_contains              (GwyContainer *container,
                                                             GQuark key);
    GValue              gwy_container_get_value             (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_value             (GwyContainer *container,
                                                             GQuark key,
                                                             GValue *value);
    void                gwy_container_set_value             (GwyContainer *container,
                                                             ...);
    void                gwy_container_set_value_by_name     (GwyContainer *container,
                                                             ...);
    gboolean            gwy_container_remove                (GwyContainer *container,
                                                             GQuark key);
    guint               gwy_container_remove_by_prefix      (GwyContainer *container,
                                                             const gchar *prefix);
    GwyContainer*       gwy_container_duplicate_by_prefix   (GwyContainer *container,
                                                             ...);
    gint                gwy_container_transfer              (GwyContainer *source,
                                                             GwyContainer *dest,
                                                             const gchar *source_prefix,
                                                             const gchar *dest_prefix,
                                                             gboolean force);
    gboolean            gwy_container_rename                (GwyContainer *container,
                                                             GQuark key,
                                                             GQuark newkey,
                                                             gboolean force);
    guint               gwy_container_foreach               (GwyContainer *container,
                                                             const gchar *prefix,
                                                             GHFunc function,
                                                             gpointer user_data);
    GQuark*             gwy_container_keys                  (GwyContainer *container);
    const gchar**       gwy_container_keys_by_name          (GwyContainer *container);
    void                gwy_container_set_boolean           (GwyContainer *container,
                                                             GQuark key,
                                                             gboolean value);
    gboolean            gwy_container_get_boolean           (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_boolean           (GwyContainer *container,
                                                             GQuark key,
                                                             gboolean *value);
    void                gwy_container_set_uchar             (GwyContainer *container,
                                                             GQuark key,
                                                             guchar value);
    guchar              gwy_container_get_uchar             (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_uchar             (GwyContainer *container,
                                                             GQuark key,
                                                             guchar *value);
    void                gwy_container_set_int32             (GwyContainer *container,
                                                             GQuark key,
                                                             gint32 value);
    gint32              gwy_container_get_int32             (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_int32             (GwyContainer *container,
                                                             GQuark key,
                                                             gint32 *value);
    void                gwy_container_set_enum              (GwyContainer *container,
                                                             GQuark key,
                                                             guint value);
    guint               gwy_container_get_enum              (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_enum              (GwyContainer *container,
                                                             GQuark key,
                                                             guint *value);
    void                gwy_container_set_int64             (GwyContainer *container,
                                                             GQuark key,
                                                             gint64 value);
    gint64              gwy_container_get_int64             (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_int64             (GwyContainer *container,
                                                             GQuark key,
                                                             gint64 *value);
    void                gwy_container_set_double            (GwyContainer *container,
                                                             GQuark key,
                                                             gdouble value);
    gdouble             gwy_container_get_double            (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_double            (GwyContainer *container,
                                                             GQuark key,
                                                             gdouble *value);
    void                gwy_container_set_string            (GwyContainer *container,
                                                             GQuark key,
                                                             const guchar *value);
    const guchar*       gwy_container_get_string            (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_string            (GwyContainer *container,
                                                             GQuark key,
                                                             const guchar **value);
    void                gwy_container_set_object            (GwyContainer *container,
                                                             GQuark key,
                                                             gpointer value);
    gpointer            gwy_container_get_object            (GwyContainer *container,
                                                             GQuark key);
    gboolean            gwy_container_gis_object            (GwyContainer *container,
                                                             GQuark key,
                                                             gpointer value);
    GPtrArray*          gwy_container_serialize_to_text     (GwyContainer *container);
    GwyContainer*       gwy_container_deserialize_from_text (const gchar *text);
    #define             gwy_container_value_type_by_name    (c,n)
    #define             gwy_container_contains_by_name      (c,n)
    #define             gwy_container_get_value_by_name     (c,n)
    #define             gwy_container_gis_value_by_name     (c,n,v)
    #define             gwy_container_remove_by_name        (c,n)
    #define             gwy_container_rename_by_name        (c,n,nn,f)
    #define             gwy_container_set_boolean_by_name   (c,n,v)
    #define             gwy_container_get_boolean_by_name   (c,n)
    #define             gwy_container_gis_boolean_by_name   (c,n,v)
    #define             gwy_container_set_uchar_by_name     (c,n,v)
    #define             gwy_container_get_uchar_by_name     (c,n)
    #define             gwy_container_gis_uchar_by_name     (c,n,v)
    #define             gwy_container_set_int32_by_name     (c,n,v)
    #define             gwy_container_get_int32_by_name     (c,n)
    #define             gwy_container_gis_int32_by_name     (c,n,v)
    #define             gwy_container_set_enum_by_name      (c,n,v)
    #define             gwy_container_get_enum_by_name      (c,n)
    #define             gwy_container_gis_enum_by_name      (c,n,v)
    #define             gwy_container_set_int64_by_name     (c,n,v)
    #define             gwy_container_get_int64_by_name     (c,n)
    #define             gwy_container_gis_int64_by_name     (c,n,v)
    #define             gwy_container_set_double_by_name    (c,n,v)
    #define             gwy_container_get_double_by_name    (c,n)
    #define             gwy_container_gis_double_by_name    (c,n,v)
    #define             gwy_container_set_string_by_name    (c,n,v)
    #define             gwy_container_get_string_by_name    (c,n)
    #define             gwy_container_gis_string_by_name    (c,n,v)
    #define             gwy_container_set_object_by_name    (c,n,v)
    #define             gwy_container_get_object_by_name    (c,n)
    #define             gwy_container_gis_object_by_name    (c,n,v)

## Object Hierarchy

      GObject
       +----GwyContainer

## Implemented Interfaces

GwyContainer implements GwySerializable.

## Signals

      "item-changed"                                   : Run First / No Recursion / Has Details

## Description

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

## Details

### GWY_CONTAINER_PATHSEP

    #define GWY_CONTAINER_PATHSEP      '/'

Path separator to be used for hierarchical structures in the container.

### GWY_CONTAINER_PATHSEP_STR

    #define GWY_CONTAINER_PATHSEP_STR  "/"

Path separator to be used for hierarchical structures in the container, as a string.

### GwyContainer

    typedef struct _GwyContainer GwyContainer;

The GwyContainer struct contains private data only and should be accessed using the functions below.

### GwyContainerClass

    typedef struct {
        GObjectClass parent_class;

        void (*item_changed)(GwyContainer *container, const gchar *key);
        void (*reserved1)(void);
    } GwyContainerClass;

### gwy_container_duplicate()

    #define             gwy_container_duplicate(container)

Convenience macro doing `gwy_serializable_duplicate()` with all the necessary typecasting.

`container` : | A container to duplicate.

### gwy_container_new ()

    GwyContainer*       gwy_container_new                   (void);

Creates a new GwyContainer.

Returns : | The container, as a GObject.

### gwy_container_get_n_items ()

    guint               gwy_container_get_n_items           (GwyContainer *container);

Gets the number of items in a container.

`container` : | A container.
Returns : | The number of items.

### gwy_container_value_type ()

    GType               gwy_container_value_type            (GwyContainer *container,
                                                             GQuark key);

Returns the type of value in `container` identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The value type as GType; 0 if there is no such value.

### gwy_container_contains ()

    gboolean            gwy_container_contains              (GwyContainer *container,
                                                             GQuark key);

Returns `TRUE` if `container` contains a value identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | Whether `container` contains something identified by `key`.

### gwy_container_get_value ()

    GValue              gwy_container_get_value             (GwyContainer *container,
                                                             GQuark key);

Returns the value in `container` identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The value as a GValue.

### gwy_container_gis_value ()

    gboolean            gwy_container_gis_value             (GwyContainer *container,
                                                             GQuark key,
                                                             GValue *value);

Get-if-set a generic value from a container.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to a GValue to update. If item does not exist, it is left untouched.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such value in the container.

### gwy_container_set_value ()

    void                gwy_container_set_value             (GwyContainer *container,
                                                             ...);

Inserts or updates several values in `container`.

`container` : | A container.
`...` : | A zero-terminated list of GQuark keys and GValue values.

### gwy_container_set_value_by_name ()

    void                gwy_container_set_value_by_name     (GwyContainer *container,
                                                             ...);

Inserts or updates several values in `container`.

`container` : | A container.
`...` : | A `NULL`-terminated list of string keys and GValue values.

### gwy_container_remove ()

    gboolean            gwy_container_remove                (GwyContainer *container,
                                                             GQuark key);

Removes a value identified by `key` from a container.

`container` : | A container.
`key` : | A GQuark key.
Returns : | `TRUE` if there was such a value and was removed.

### gwy_container_remove_by_prefix ()

    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.

`container` : | A container.
`prefix` : | A nul-terminated id prefix.
Returns : | The number of values removed.

### gwy_container_duplicate_by_prefix ()

    GwyContainer*       gwy_container_duplicate_by_prefix   (GwyContainer *container,
                                                             ...);

Duplicates a container keeping only values under given prefixes.

Like `gwy_container_duplicate()`, this method creates a deep copy, that is contained object are physically duplicated too, not just referenced again.

`container` : | A container.
`...` : | A `NULL`-terminated list of string keys.
Returns : | A newly created container.

### gwy_container_transfer ()

    gint                gwy_container_transfer              (GwyContainer *source,
                                                             GwyContainer *dest,
                                                             const gchar *source_prefix,
                                                             const gchar *dest_prefix,
                                                             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`.

`source` : | Source container.
`dest` : | Destination container. It may be the same container as `source`, but `source_prefix` and `dest_prefix` may not overlap then.
`source_prefix` : | Prefix in `source` to take values from.
`dest_prefix` : | Prefix in `dest` to put values to.
`force` : | `TRUE` to replace existing values in `dest`.
Returns : | The number of actually transferred items.

### gwy_container_rename ()

    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.

`container` : | A container.
`key` : | The current key.
`newkey` : | A new key for the value.
`force` : | Whether to replace existing value at `newkey`.
Returns : | Whether the rename succeeded.

### gwy_container_foreach ()

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

`container` : | A container.
`prefix` : | A nul-terminated id prefix.
`function` : | The function called on the items.
`user_data` : | The user data passed to `function`.
Returns : | The number of items `function` was called on.

### gwy_container_keys ()

    GQuark*             gwy_container_keys                  (GwyContainer *container);

Gets all quark keys of a container.

`container` : | A container.
Returns : | A newly allocated array with quark keys of all `container` items, in no particular order. The number of items can be obtained with `gwy_container_get_n_items()`. If there are no items, `NULL` is returned.

Since 2.7

### gwy_container_keys_by_name ()

    const gchar**       gwy_container_keys_by_name          (GwyContainer *container);

Gets all string keys of a container.

`container` : | A container.
Returns : | 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()`. If there are no items, `NULL` is returned. Unlike the array the strings are owned by GLib and must not be freed.

Since 2.7

### gwy_container_set_boolean ()

    void                gwy_container_set_boolean           (GwyContainer *container,
                                                             GQuark key,
                                                             gboolean value);

Stores a boolean into `container`, identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
`value` : | A boolean.

### gwy_container_get_boolean ()

    gboolean            gwy_container_get_boolean           (GwyContainer *container,
                                                             GQuark key);

Returns the boolean in `container` identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The boolean as gboolean.

### gwy_container_gis_boolean ()

    gboolean            gwy_container_gis_boolean           (GwyContainer *container,
                                                             GQuark key,
                                                             gboolean *value);

Get-if-set a boolean from a container.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the boolean to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such boolean in the container.

### gwy_container_set_uchar ()

    void                gwy_container_set_uchar             (GwyContainer *container,
                                                             GQuark key,
                                                             guchar value);

Stores an unsigned character into `container`, identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
`value` : | An unsigned character.

### gwy_container_get_uchar ()

    guchar              gwy_container_get_uchar             (GwyContainer *container,
                                                             GQuark key);

Returns the unsigned character in `container` identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The character as guchar.

### gwy_container_gis_uchar ()

    gboolean            gwy_container_gis_uchar             (GwyContainer *container,
                                                             GQuark key,
                                                             guchar *value);

Get-if-set an unsigned char from a container.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the unsigned char to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such unsigned char in the container.

### gwy_container_set_int32 ()

    void                gwy_container_set_int32             (GwyContainer *container,
                                                             GQuark key,
                                                             gint32 value);

Stores a 32bit integer into `container`, identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
`value` : | A 32bit integer.

### gwy_container_get_int32 ()

    gint32              gwy_container_get_int32             (GwyContainer *container,
                                                             GQuark key);

Returns the 32bit integer in `container` identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The integer as guint32.

### gwy_container_gis_int32 ()

    gboolean            gwy_container_gis_int32             (GwyContainer *container,
                                                             GQuark key,
                                                             gint32 *value);

Get-if-set a 32bit integer from a container.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the 32bit integer to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such 32bit integer in the container.

### gwy_container_set_enum ()

    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.

`container` : | A container.
`key` : | A GQuark key.
`value` : | An enum integer.

### gwy_container_get_enum ()

    guint               gwy_container_get_enum              (GwyContainer *container,
                                                             GQuark key);

Returns the enum in `container` identified by `key`.

Note enums are treated as 32bit integers.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The enum as gint.

### gwy_container_gis_enum ()

    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.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the enum to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such enum in the container.

### gwy_container_set_int64 ()

    void                gwy_container_set_int64             (GwyContainer *container,
                                                             GQuark key,
                                                             gint64 value);

Stores a 64bit integer into `container`, identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
`value` : | A 64bit integer.

### gwy_container_get_int64 ()

    gint64              gwy_container_get_int64             (GwyContainer *container,
                                                             GQuark key);

Returns the 64bit integer in `container` identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The 64bit integer as guint64.

### gwy_container_gis_int64 ()

    gboolean            gwy_container_gis_int64             (GwyContainer *container,
                                                             GQuark key,
                                                             gint64 *value);

Get-if-set a 64bit integer from a container.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the 64bit integer to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such 64bit integer in the container.

### gwy_container_set_double ()

    void                gwy_container_set_double            (GwyContainer *container,
                                                             GQuark key,
                                                             gdouble value);

Stores a double into `container`, identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
`value` : | A double.

### gwy_container_get_double ()

    gdouble             gwy_container_get_double            (GwyContainer *container,
                                                             GQuark key);

Returns the double in `container` identified by `key`.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The double as gdouble.

### gwy_container_gis_double ()

    gboolean            gwy_container_gis_double            (GwyContainer *container,
                                                             GQuark key,
                                                             gdouble *value);

Get-if-set a double from a container.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the double to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such double in the container.

### gwy_container_set_string ()

    void                gwy_container_set_string            (GwyContainer *container,
                                                             GQuark key,
                                                             const guchar *value);

Stores a string into `container`, identified by `key`.

The container takes ownership of the string, so it can't be used on static strings, use `g_strdup()` to duplicate them first.

`container` : | A container.
`key` : | A GQuark key.
`value` : | A nul-terminated string.

### gwy_container_get_string ()

    const guchar*       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.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The string.

### gwy_container_gis_string ()

    gboolean            gwy_container_gis_string            (GwyContainer *container,
                                                             GQuark key,
                                                             const guchar **value);

Get-if-set a string from a container.

The string eventually stored in `value` must be treated as constant and never freed or modified.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the string pointer to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such string in the container.

### gwy_container_set_object ()

    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.

The object must implement GwySerializable interface to allow serialization of the container.

`container` : | A container.
`key` : | A GQuark key.
`value` : | An object to store into container.

### gwy_container_get_object ()

    gpointer            gwy_container_get_object            (GwyContainer *container,
                                                             GQuark key);

Returns the object in `container` identified by `key`.

The returned object doesn't have its reference count increased, use `g_object_ref()` if you want to access it even when `container` may cease to exist.

`container` : | A container.
`key` : | A GQuark key.
Returns : | The object as gpointer.

### gwy_container_gis_object ()

    gboolean            gwy_container_gis_object            (GwyContainer *container,
                                                             GQuark key,
                                                             gpointer value);

Get-if-set an object from a container.

The object eventually 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.

`container` : | A container.
`key` : | A GQuark key.
`value` : | Pointer to the object pointer to update.
Returns : | `TRUE` if `v` was actually updated, `FALSE` when there is no such object in the container.

### gwy_container_serialize_to_text ()

    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.

`container` : | A container.
Returns : | A pointer array, each item containing string with one container item representation (name, type, value). The array is sorted by name.

### gwy_container_deserialize_from_text ()

    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 `gwy_container_serialize_to_text()`.
Returns : | The restored container, or `NULL` on failure.

### gwy_container_value_type_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_contains_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_get_value_by_name()

    #define gwy_container_get_value_by_name(c,n)     gwy_container_get_value(c,g_quark_try_string(n))

Gets the value in container `c` identified by name `n`.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_value_by_name()

    #define gwy_container_gis_value_by_name(c,n,v)   gwy_container_gis_value(c,g_quark_from_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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to a GValue to update. If item does not exist, it is left untouched.

### gwy_container_remove_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_rename_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`nn` : | A nul-terminated name (id).
`f` : | Whether to delete existing value at `newkey`.

### gwy_container_set_boolean_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | A boolean.

### gwy_container_get_boolean_by_name()

    #define gwy_container_get_boolean_by_name(c,n)   gwy_container_get_boolean(c,g_quark_try_string(n))

Gets the boolean in container `c` identified by name `n`.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_boolean_by_name()

    #define gwy_container_gis_boolean_by_name(c,n,v) gwy_container_gis_boolean(c,g_quark_from_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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the boolean to update.

### gwy_container_set_uchar_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | An unsigned character.

### gwy_container_get_uchar_by_name()

    #define gwy_container_get_uchar_by_name(c,n)     gwy_container_get_uchar(c,g_quark_try_string(n))

Gets the unsigned character in container `c` identified by name `n`.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_uchar_by_name()

    #define gwy_container_gis_uchar_by_name(c,n,v)   gwy_container_gis_uchar(c,g_quark_from_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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the unsigned char to update.

### gwy_container_set_int32_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | A 32bit integer.

### gwy_container_get_int32_by_name()

    #define gwy_container_get_int32_by_name(c,n)     gwy_container_get_int32(c,g_quark_try_string(n))

Gets the 32bit integer in container `c` identified by name `n`.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_int32_by_name()

    #define gwy_container_gis_int32_by_name(c,n,v)   gwy_container_gis_int32(c,g_quark_from_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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the 32bit integer to update.

### gwy_container_set_enum_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | An enum.

### gwy_container_get_enum_by_name()

    #define gwy_container_get_enum_by_name(c,n)      gwy_container_get_enum(c,g_quark_try_string(n))

Gets the enum in container `c` identified by name `n`.

Note enums are treated as 32bit integers.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_enum_by_name()

    #define gwy_container_gis_enum_by_name(c,n,v)    gwy_container_gis_enum(c,g_quark_from_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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the enum to update.

### gwy_container_set_int64_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | A 64bit integer.

### gwy_container_get_int64_by_name()

    #define gwy_container_get_int64_by_name(c,n)     gwy_container_get_int64(c,g_quark_try_string(n))

Gets the 64bit integer in container `c` identified by name `n`.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_int64_by_name()

    #define gwy_container_gis_int64_by_name(c,n,v)   gwy_container_gis_int64(c,g_quark_from_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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the 64bit integer to update.

### gwy_container_set_double_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | A double integer.

### gwy_container_get_double_by_name()

    #define gwy_container_get_double_by_name(c,n)    gwy_container_get_double(c,g_quark_try_string(n))

Gets the double in container `c` identified by name `n`.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_double_by_name()

    #define gwy_container_gis_double_by_name(c,n,v)  gwy_container_gis_double(c,g_quark_from_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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the double to update.

### gwy_container_set_string_by_name()

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

The container takes ownership of the string, so it can't be used on static strings, use `g_strdup()` to duplicate them first.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | A nul-terminated string.

### gwy_container_get_string_by_name()

    #define gwy_container_get_string_by_name(c,n)    gwy_container_get_string(c,g_quark_try_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.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_string_by_name()

    #define gwy_container_gis_string_by_name(c,n,v)  gwy_container_gis_string(c,g_quark_from_string(n),v)

Get-if-set a string from a container.

The string eventually 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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the string pointer to update.

### gwy_container_set_object_by_name()

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

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | An object to store into container.

### gwy_container_get_object_by_name()

    #define gwy_container_get_object_by_name(c,n)    gwy_container_get_object(c,g_quark_try_string(n))

Gets the object in container `c` identified by name `n`.

The returned object doesn't have its reference count increased, use `g_object_ref()` if you want to access it even when `container` may cease to exist.

`c` : | A container.
`n` : | A nul-terminated name (id).

### gwy_container_gis_object_by_name()

    #define gwy_container_gis_object_by_name(c,n,v)  gwy_container_gis_object(c,g_quark_from_string(n),v)

Get-if-set an object from a container.

The object eventually 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.

`c` : | A container.
`n` : | A nul-terminated name (id).
`v` : | Pointer to the object pointer to update.

## Signal Details

### The `"item-changed"` signal

    void                user_function                      (GwyContainer *gwycontainer,
                                                            guint         arg1,
                                                            gpointer      user_data)         : Run First / No Recursion / Has Details

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.

## See Also

GwyInventory