GwyDict: Gwyddion Library Reference Manual

## GwyDict GwyDict — A dictionary with items identified by a GQuark or string |

## Functions

void | (*GwyDictForeachFunc) ()
GwyDict * | gwy_dict_new ()
GwyDict * | gwy_dict_new_in_construction ()
guint | gwy_dict_get_n_items ()
GType | gwy_dict_value_type ()
gboolean | gwy_dict_contains ()
GValue | gwy_dict_get_value ()
gboolean | gwy_dict_gis_value ()
void | gwy_dict_set_value ()
gboolean | gwy_dict_remove ()
guint | gwy_dict_remove_by_prefix ()
GwyDict * | gwy_dict_duplicate_by_prefix ()
GwyDict * | gwy_dict_duplicate_by_prefixv ()
void | gwy_dict_copy_value ()
gint | gwy_dict_transfer ()
gboolean | gwy_dict_rename ()
guint | gwy_dict_foreach ()
GQuark * | gwy_dict_keys ()
const gchar ** | gwy_dict_keys_by_name ()
GQuark * | gwy_dict_keys_with_prefix ()
const gchar ** | gwy_dict_keys_with_prefix_by_name ()
void | gwy_dict_set_boolean ()
gboolean | gwy_dict_get_boolean ()
gboolean | gwy_dict_gis_boolean ()
void | gwy_dict_set_uchar ()
guchar | gwy_dict_get_uchar ()
gboolean | gwy_dict_gis_uchar ()
void | gwy_dict_set_int32 ()
gint32 | gwy_dict_get_int32 ()
gboolean | gwy_dict_gis_int32 ()
void | gwy_dict_set_enum ()
guint | gwy_dict_get_enum ()
gboolean | gwy_dict_gis_enum ()
void | gwy_dict_set_int64 ()
gint64 | gwy_dict_get_int64 ()
gboolean | gwy_dict_gis_int64 ()
void | gwy_dict_set_double ()
gdouble | gwy_dict_get_double ()
gboolean | gwy_dict_gis_double ()
void | gwy_dict_pass_string ()
void | gwy_dict_set_string ()
const gchar * | gwy_dict_get_string ()
gboolean | gwy_dict_gis_string ()
void | gwy_dict_set_object ()
void | gwy_dict_pass_object ()
gpointer | gwy_dict_get_object ()
gboolean | gwy_dict_gis_object ()
void | gwy_dict_set_boxed ()
void | gwy_dict_pass_boxed ()
gpointer | gwy_dict_get_boxed ()
gboolean | gwy_dict_gis_boxed ()
void | gwy_dict_start_construction ()
void | gwy_dict_finish_construction ()
gboolean | gwy_dict_is_being_constructed ()
GwyDict * | gwy_dict_copy ()
void | gwy_dict_assign ()
GPtrArray * | gwy_dict_serialize_to_text ()
GwyDict * | gwy_dict_deserialize_from_text ()
#define | gwy_dict_value_type_by_name()
#define | gwy_dict_contains_by_name()
#define | gwy_dict_set_value_by_name()
#define | gwy_dict_get_value_by_name()
#define | gwy_dict_gis_value_by_name()
#define | gwy_dict_copy_value_by_name()
#define | gwy_dict_remove_by_name()
#define | gwy_dict_rename_by_name()
#define | gwy_dict_set_boolean_by_name()
#define | gwy_dict_get_boolean_by_name()
#define | gwy_dict_gis_boolean_by_name()
#define | gwy_dict_set_uchar_by_name()
#define | gwy_dict_get_uchar_by_name()
#define | gwy_dict_gis_uchar_by_name()
#define | gwy_dict_set_int32_by_name()
#define | gwy_dict_get_int32_by_name()
#define | gwy_dict_gis_int32_by_name()
#define | gwy_dict_set_enum_by_name()
#define | gwy_dict_get_enum_by_name()
#define | gwy_dict_gis_enum_by_name()
#define | gwy_dict_set_int64_by_name()
#define | gwy_dict_get_int64_by_name()
#define | gwy_dict_gis_int64_by_name()
#define | gwy_dict_set_double_by_name()
#define | gwy_dict_get_double_by_name()
#define | gwy_dict_gis_double_by_name()
#define | gwy_dict_pass_string_by_name()
#define | gwy_dict_set_string_by_name()
#define | gwy_dict_get_string_by_name()
#define | gwy_dict_gis_string_by_name()
#define | gwy_dict_set_object_by_name()
#define | gwy_dict_pass_object_by_name()
#define | gwy_dict_get_object_by_name()
#define | gwy_dict_gis_object_by_name()
#define | gwy_dict_set_boxed_by_name()
#define | gwy_dict_pass_boxed_by_name()
#define | gwy_dict_get_boxed_by_name()
#define | gwy_dict_gis_boxed_by_name()

## Signals

void | item-changed | Has Details

## Types and Values

#define | GWY_DICT_PATHSEP
#define | GWY_DICT_PATHSEP_STR
struct | GwyDict
struct | GwyDictClass

## Object Hierarchy

        GObject
        ╰── GwyDict

## Implemented Interfaces

GwyDict implements GwySerializable.

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

GwyDict is a general-purpose dictionary-like data container, it can hold atomic types, strings and objects. However, objects must implement the GwySerializable interface, because the dictionary itself is serializable.

A new dictionary can be created with `gwy_dict_new()`, items can be stored with function like `gwy_dict_set_double()`, read with `gwy_dict_get_double()`, and removed with `gwy_dict_remove()` or `gwy_dict_remove_by_prefix()`. A presence of a value can be tested with `gwy_dict_contains()`, convenience functions for reading (updating) a value only if it is present like `gwy_dict_gis_double()`, are available too.

GwyDict 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 dictionary will free them itself when they are removed or when the dictionary is finalized. For objects, this means it takes a reference on the object (released when the object is removed or the dictionary is finalized), so you usually want to `g_object_unref()` objects after storing them to a dictionary.

Items in a GwyDict can be identified by a GQuark or the corresponding string. While GQuark's are atomic values and allow faster access, they are less convenient for casual usage -- each GQuark key function like `gwy_dict_set_double()` thus has a string-key counterpart `gwy_dict_set_double_by_name()`.

## Functions

### GwyDictForeachFunc()

    void
    (*GwyDictForeachFunc) (GQuark key,
                           GValue *value,
                           gpointer user_data);

Type of callback function for container for-each operation.

#### Parameters

key | A GQuark key. |
value | Value at `key` . |
user_data | User data passed to the for-each function. |

### gwy_dict_new()

    GwyDict *
    gwy_dict_new (void);

Creates a new dictionary-like data container.

[constructor]

#### Returns

A new dictionary.

[transfer full]

### gwy_dict_new_in_construction()

    GwyDict *
    gwy_dict_new_in_construction (void);

Creates a new dictionary-like data container and marks it as being in construction.

This is a convenience function calling `gwy_dict_start_construction()` on the newly created dictionary.

[constructor]

#### Returns

A new container.

[transfer full]

### gwy_dict_get_n_items()

    guint
    gwy_dict_get_n_items (GwyDict *dict);

Gets the number of items in a dictionary.

#### Parameters

dict | A dictionary-like data container. |

#### Returns

The number of items.

### gwy_dict_value_type()

    GType
    gwy_dict_value_type (GwyDict *dict,
                         GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The value type as GType; 0 if there is no such value.

### gwy_dict_contains()

    gboolean
    gwy_dict_contains (GwyDict *dict,
                       GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

Whether `dict` contains something identified by `key` .

### gwy_dict_get_value()

    GValue
    gwy_dict_get_value (GwyDict *dict,
                        GQuark key);

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

The returned GValue should not be modified since such modification is not detectable and would not emit “item-changed”.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The value as a GValue.

### gwy_dict_gis_value()

    gboolean
    gwy_dict_gis_value (GwyDict *dict,
                        GQuark key,
                        GValue *value);

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

On success, `value` will contain a copy of the data in `dict` .

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to a GValue to update. If item does not exist, it is left untouched. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such value in the container.

### gwy_dict_set_value()

    void
    gwy_dict_set_value (GwyDict *dict,
                        GQuark key,
                        GValue *value);

Inserts or updates one value in a dictionary.

The value is copied and the caller remains responsible for unsetting `value` .

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to a GValue to set. |

### gwy_dict_remove()

    gboolean
    gwy_dict_remove (GwyDict *dict,
                     GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

`TRUE` if there was such a value and was removed.

### gwy_dict_remove_by_prefix()

    guint
    gwy_dict_remove_by_prefix (GwyDict *dict,
                               const gchar *prefix);

Removes a values whose key start with `prefix` from container `dict` .

`prefix` can be `NULL`, all values are then removed.

#### Parameters

dict | A dictionary-like data container. |
prefix | A nul-terminated id prefix. | [nullable]

#### Returns

The number of values removed.

### gwy_dict_duplicate_by_prefix()

    GwyDict *
    gwy_dict_duplicate_by_prefix (GwyDict *dict,
                                  ...);

Duplicates a dictionary keeping only values under given prefixes.

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

Signal ::item-changed is not emitted during the construction of the copy (in case you manage to get hold on the returned object before the copying is finished).

#### Parameters

dict | A dictionary-like data container. |
... | A `NULL`-terminated list of string keys. |

#### Returns

A newly created container.

[transfer full]

### gwy_dict_duplicate_by_prefixv()

    GwyDict *
    gwy_dict_duplicate_by_prefixv (GwyDict *dict,
                                   guint n,
                                   const gchar **prefixes);

Duplicates a dictionary keeping only values under given prefixes.

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

Signal ::item-changed is not emitted during the construction of the copy (in case you manage to get hold on the returned object before the copying is finished).

#### Parameters

dict | A dictionary-like data container. |
n | Length of `prefixes` array. |
prefixes | List of prefixes. | [array length=n]

#### Returns

A newly created container.

[transfer full]

### gwy_dict_copy_value()

    void
    gwy_dict_copy_value (GwyDict *source,
                         GwyDict *dest,
                         GQuark srckey,
                         GQuark destkey);

Copies one value from a dictionary to another one.

The source value must exist. If it is an object or boxed, it is copied by value, i.e. the functions always does a deep copy.

#### Parameters

source | Source container. |
dest | Destination container. It may be the same container as `source` . |
srckey | Quark key in `source` . |
destkey | Quark key in `dest` . |

### gwy_dict_transfer()

    gint
    gwy_dict_transfer (GwyDict *source,
                       GwyDict *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.

#### Parameters

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. |
deep | `TRUE` to perform a deep copy, `FALSE` to perform a shallow copy. This option pertains only to contained objects, strings are always duplicated. |
force | `TRUE` to replace existing values in `dest` . |

#### Returns

The number of actually transferred items, excluding unchanged items (even when `force` is `TRUE`).

### gwy_dict_rename()

    gboolean
    gwy_dict_rename (GwyDict *dict,
                     GQuark key,
                     GQuark newkey,
                     gboolean force);

Makes a value in `dict` identified by `key` to be identified by `newkey` .

When `force` is `TRUE` existing value at `newkey` is removed from `dict` . When it's `FALSE`, an existing value `newkey` inhibits the rename and `FALSE` is returned.

#### Parameters

dict | A dictionary-like data 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_dict_foreach()

    guint
    gwy_dict_foreach (GwyDict *dict,
                      const gchar *prefix,
                      GwyDictForeachFunc function,
                      gpointer user_data);

Calls a function on each item in a dictionary, possibly limited to a prefix.

The function must not modify the container contents (see `g_hash_table_foreach()`). Modifying individual items by changing the contents of a GValue is strongly discouraged because it is not detectable and no GwyDict::item-changed signal is emitted.

#### Parameters

dict | A dictionary-like data container. |
prefix | A string container key prefix. | [nullable]
function | The function called on the items. | [scope call]
user_data | The user data passed to `function` . |

#### Returns

The number of items `function` was called on.

### gwy_dict_keys()

    GQuark *
    gwy_dict_keys (GwyDict *dict);

Gets all quark keys of a dictionary.

#### Parameters

dict | A dictionary-like data container. |

#### Returns

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

[array zero-terminated=1]

### gwy_dict_keys_by_name()

    const gchar **
    gwy_dict_keys_by_name (GwyDict *dict);

Gets all string keys of a dictionary.

#### Parameters

dict | A dictionary-like data container. |

#### Returns

A newly allocated array with string keys of all `dict` items, in no particular order. The number of items can be obtained with `gwy_dict_get_n_items()`. Unlike the array the strings are owned by GLib and must not be freed.

[transfer container][array zero-terminated=1]

### gwy_dict_keys_with_prefix()

    GQuark *
    gwy_dict_keys_with_prefix (GwyDict *dict,
                               const gchar *prefix,
                               guint *n);

Gets quark keys of a dictionary that start with given prefix.

#### Parameters

dict | A dictionary-like data container. |
prefix | A nul-terminated id prefix. |
n | Location to store the number of keys to. Can be `NULL`. | [out]

#### Returns

A newly allocated array with quark keys, in no particular order. The array is zero-terminated.

[array zero-terminated=1]

### gwy_dict_keys_with_prefix_by_name()

    const gchar **
    gwy_dict_keys_with_prefix_by_name (GwyDict *dict,
                                       const gchar *prefix,
                                       guint *n);

Gets string keys of a dictionary that start with given prefix.

#### Parameters

dict | A dictionary-like data container. |
prefix | A nul-terminated id prefix. |
n | Location to store the number of keys to. Can be `NULL`. | [out]

#### Returns

A newly allocated array with string keys, in no particular order. Unlike the array the strings are owned by GLib and must not be freed. The array is `NULL`-terminated.

[transfer none][array zero-terminated=1]

### gwy_dict_set_boolean()

    void
    gwy_dict_set_boolean (GwyDict *dict,
                          GQuark key,
                          gboolean value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | A boolean. |

### gwy_dict_get_boolean()

    gboolean
    gwy_dict_get_boolean (GwyDict *dict,
                          GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The boolean as gboolean.

### gwy_dict_gis_boolean()

    gboolean
    gwy_dict_gis_boolean (GwyDict *dict,
                          GQuark key,
                          gboolean *value);

Get-if-set a boolean from a dictionary.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the boolean to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such boolean in the container.

### gwy_dict_set_uchar()

    void
    gwy_dict_set_uchar (GwyDict *dict,
                        GQuark key,
                        guchar value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | An unsigned character. |

### gwy_dict_get_uchar()

    guchar
    gwy_dict_get_uchar (GwyDict *dict,
                        GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The character as guchar.

### gwy_dict_gis_uchar()

    gboolean
    gwy_dict_gis_uchar (GwyDict *dict,
                        GQuark key,
                        guchar *value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the unsigned char to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such unsigned char in the container.

### gwy_dict_set_int32()

    void
    gwy_dict_set_int32 (GwyDict *dict,
                        GQuark key,
                        gint32 value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | A 32bit integer. |

### gwy_dict_get_int32()

    gint32
    gwy_dict_get_int32 (GwyDict *dict,
                        GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The integer as guint32.

### gwy_dict_gis_int32()

    gboolean
    gwy_dict_gis_int32 (GwyDict *dict,
                        GQuark key,
                        gint32 *value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the 32bit integer to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such 32bit integer in the container.

### gwy_dict_set_enum()

    void
    gwy_dict_set_enum (GwyDict *dict,
                       GQuark key,
                       guint value);

Stores an enum into `dict` , identified by `key` .

Note enums are treated as 32bit integers.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | An enum integer. |

### gwy_dict_get_enum()

    guint
    gwy_dict_get_enum (GwyDict *dict,
                       GQuark key);

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

Note enums are treated as 32bit integers.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The enum as gint.

### gwy_dict_gis_enum()

    gboolean
    gwy_dict_gis_enum (GwyDict *dict,
                       GQuark key,
                       guint *value);

Get-if-set an enum from a dictionary.

Note enums are treated as 32bit integers.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the enum to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such enum in the container.

### gwy_dict_set_int64()

    void
    gwy_dict_set_int64 (GwyDict *dict,
                        GQuark key,
                        gint64 value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | A 64bit integer. |

### gwy_dict_get_int64()

    gint64
    gwy_dict_get_int64 (GwyDict *dict,
                        GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The 64bit integer as guint64.

### gwy_dict_gis_int64()

    gboolean
    gwy_dict_gis_int64 (GwyDict *dict,
                        GQuark key,
                        gint64 *value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the 64bit integer to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such 64bit integer in the container.

### gwy_dict_set_double()

    void
    gwy_dict_set_double (GwyDict *dict,
                         GQuark key,
                         gdouble value);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | A double. |

### gwy_dict_get_double()

    gdouble
    gwy_dict_get_double (GwyDict *dict,
                         GQuark key);

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The double as gdouble.

### gwy_dict_gis_double()

    gboolean
    gwy_dict_gis_double (GwyDict *dict,
                         GQuark key,
                         gdouble *value);

Get-if-set a double from a dictionary.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the double to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such double in the container.

### gwy_dict_pass_string()

    void
    gwy_dict_pass_string (GwyDict *dict,
                          GQuark key,
                          gchar *value);

Stores a string into `dict` , 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` .

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | A nul-terminated string. |

### gwy_dict_set_string()

    void
    gwy_dict_set_string (GwyDict *dict,
                         GQuark key,
                         const gchar *value);

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

The container makes a copy of the string, so it can be used on static strings and strings owned by other entities.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | A nul-terminated string. |

### gwy_dict_get_string()

    const gchar *
    gwy_dict_get_string (GwyDict *dict,
                         GQuark key);

Returns the string in `dict` identified by `key` .

The returned string must be treated as constant and never freed or modified.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The string.

### gwy_dict_gis_string()

    gboolean
    gwy_dict_gis_string (GwyDict *dict,
                         GQuark key,
                         const gchar **value);

Get-if-set a string from a dictionary.

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the string pointer to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such string in the container.

### gwy_dict_set_object()

    void
    gwy_dict_set_object (GwyDict *dict,
                         GQuark key,
                         gpointer value);

Stores an object into `dict` , identified by `key` .

The container claims ownership on the object, i.e. its reference count is incremented. Use `gwy_dict_pass_object()` to pass your reference to `dict` .

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | An object to store into container. |

### gwy_dict_pass_object()

    void
    gwy_dict_pass_object (GwyDict *dict,
                          GQuark key,
                          gpointer value);

Stores an object into `dict` , identified by `key` , passing reference to the container.

The reference on the object you hold is passed to `dict` . This is often useful when importing data as you do not have to (in fact must not) release your reference afterwards. Use `gwy_dict_set_object()` if you want to keep your reference.

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

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | An object to store into container. |

### gwy_dict_get_object()

    gpointer
    gwy_dict_get_object (GwyDict *dict,
                         GQuark key);

Returns the object in `dict` 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 `dict` may cease to exist.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |

#### Returns

The object as gpointer.

### gwy_dict_gis_object()

    gboolean
    gwy_dict_gis_object (GwyDict *dict,
                         GQuark key,
                         gpointer value);

Get-if-set an object from a dictionary.

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 `dict` may cease to exist.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
value | Pointer to the object pointer to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such object in the container.

### gwy_dict_set_boxed()

    void
    gwy_dict_set_boxed (GwyDict *dict,
                        GType type,
                        GQuark key,
                        gpointer value);

Stores a boxed pointer into `dict` , identified by `key` .

The container makes a copy of the boxed pointer using `g_boxed_copy()`. The caller remains responsible for freeing `value` with `g_boxed_free()`.

The boxed type must be serializable to allow serialization of the container.

#### Parameters

dict | A dictionary-like data container. |
type | The type of `value` . |
key | A GQuark key. |
value | An boxed pointer to store into container. |

### gwy_dict_pass_boxed()

    void
    gwy_dict_pass_boxed (GwyDict *dict,
                         GType type,
                         GQuark key,
                         gpointer value);

Stores a boxed pointer into `dict` , 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 `dict` and forget about it, it is safer to use `gwy_dict_set_boxed()`.

The boxed type must be serializable to allow serialization of the container.

#### Parameters

dict | A dictionary-like data container. |
type | The type of `value` . |
key | A GQuark key. |
value | An boxed pointer to store into container. |

### gwy_dict_get_boxed()

    gpointer
    gwy_dict_get_boxed (GwyDict *dict,
                        GType type,
                        GQuark key);

Returns the boxed pointer in `dict` identified by `key` .

It is an error to request a boxed pointer of different type than is actually stored.

#### Parameters

dict | A dictionary-like data container. |
key | A GQuark key. |
type | The boxed type. |

#### Returns

The boxed pointer as gpointer.

### gwy_dict_gis_boxed()

    gboolean
    gwy_dict_gis_boxed (GwyDict *dict,
                        GType type,
                        GQuark key,
                        gpointer value);

Get-if-set a boxed pointer from a dictionary.

It is an error to request a boxed pointer of different type than is actually stored.

The boxed pointer is copied to `value` by value, which is always possbile as only serialisable boxed types can be stored in a GwyDict. The `value` pointer thus does not have the extra level of indirection objects and strings have:

    1
    2
    GwyXYZ xyz;
    gwy_dict_gis_boxed(dict, GWY_TYPE_XYZ, quark, &xyz);

#### Parameters

dict | A dictionary-like data container. |
type | The boxed type. |
key | A GQuark key. |
value | The boxed value to update. | [out]

#### Returns

`TRUE` if `value` was actually updated, `FALSE` when there is no such boxed in the container.

### gwy_dict_start_construction()

    void
    gwy_dict_start_construction (GwyDict *dict);

Marks a dictionary as being initially constructed.

It is an error to call the function on `dict` which is not empty. It is an error to call it when `dict` is already marked as being constructed. It is undefined behaviour to start and finish the construction multiple times, even if `dict` remains empty.

When a dictionary is constructed by internal means, for instance during deserialisation or `gwy_dict_copy()`, it does not emit any signals, in particular ::item-changed. However, data containers are also frequently constructed for instance to represent files in file import modules, where emitting signals is pointless and can slow down the import (more substantially for subclasses like GwyFile which respond to changed items). You can use this function to prevent signal emission in such case.

Remember to call `gwy_dict_finish_construction()` when you are done. A GwyDict marked as still being in construction can be considered an invalid object.

#### Parameters

dict | A dictionary-like data container. |

### gwy_dict_finish_construction()

    void
    gwy_dict_finish_construction (GwyDict *dict);

Marks the construction of a dictionary as finished.

The data container must be marked as being constructed with `gwy_dict_start_construction()`. The call may result in a subclass or other user scanning the contents. See `gwy_dict_start_construction()` for more discussion.

#### Parameters

dict | A dictionary-like data container. |

### gwy_dict_is_being_constructed()

    gboolean
    gwy_dict_is_being_constructed (GwyDict *dict);

Queries if a dictionary is being initially constructed.

#### Parameters

dict | A dictionary-like data container. |

#### Returns

`TRUE` if `dict` was marked with `gwy_dict_start_construction()`.

### gwy_dict_copy()

    GwyDict *
    gwy_dict_copy (GwyDict *dict);

Create a new container as a copy of an existing one.

This function is a convenience `gwy_serializable_copy()` wrapper.

Signal ::item-changed is not emitted during the construction of the copy (in case you manage to get hold on the returned object before the copying is finished). The new object is not marked as being in construction, regardless of the state of `dict` .

#### Parameters

dict | A dictionary-like data container to duplicate. |

#### Returns

A copy of the container.

[transfer full]

### gwy_dict_assign()

    void
    gwy_dict_assign (GwyDict *destination,
                     GwyDict *source);

Makes one container equal to another.

This function is a convenience `gwy_serializable_assign()` wrapper.

Signal ::item-changed is emitted as usual, making the operation possibly relatively expensive. The in-construction state of either object is unchanged.

#### Parameters

destination | Target container. |
source | Source container. |

### gwy_dict_serialize_to_text()

    GPtrArray *
    gwy_dict_serialize_to_text (GwyDict *dict);

Creates a text representation of `dict` contents.

Note that only simple data types are supported as serialization of compound objects is not controllable.

The strings in the returned array are owned by the array by means of element destroy function which is set to `g_free()` (which you need to take into account if you intend to add more strings yourself). Usually, you can free the array including all the strings with `g_ptr_array_free()`. If you want to take the ownership of the strings, use `g_ptr_array_steal()`.

#### Parameters

dict | A dictionary-like data container. |

#### Returns

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

### gwy_dict_deserialize_from_text()

    GwyDict *
    gwy_dict_deserialize_from_text (const gchar *text);

Restores a dictionary from is text representation.

Signal ::item-changed is not emitted during the construction (in case you manage to get hold on the returned object before the deserialisation is finished).

#### Parameters

text | Text containing serialized container contents as dumped by `gwy_dict_serialize_to_text()`. |

#### Returns

The restored container, or `NULL` on failure.

[transfer full]

### gwy_dict_value_type_by_name()

    #define gwy_dict_value_type_by_name(dict,name)               gwy_dict_value_type(dict,g_quark_try_string(name))

Gets the type of value in container `dict` identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_contains_by_name()

    #define gwy_dict_contains_by_name(dict,name)                 gwy_dict_contains(dict,g_quark_try_string(name))

Expands to `TRUE` if container `dict` contains a value identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_set_value_by_name()

    #define gwy_dict_set_value_by_name(dict,name,value)          gwy_dict_set_value(dict,g_quark_from_string(name),value)

Inserts or updates one value in a dictionary.

The value is copied and the caller remains responsible for unsetting `value` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to a GValue to set. |

### gwy_dict_get_value_by_name()

    #define gwy_dict_get_value_by_name(dict,name)                gwy_dict_get_value(dict,g_quark_from_string(name))

Gets the value in container `dict` identified by name `name` .

The returned GValue should not be modified since such modification is not detectable and would not emit “item-changed”.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_value_by_name()

    #define gwy_dict_gis_value_by_name(dict,name,value)          gwy_dict_gis_value(dict,g_quark_try_string(name),value)

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

On success, `value` will contain a copy of the data in `dict` .

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such value in the container.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to a GValue to update. If item does not exist, it is left untouched. |

### gwy_dict_copy_value_by_name()

    #define gwy_dict_copy_value_by_name(dict1,dict2,name1,name2) gwy_dict_copy_value(dict1,dict2,g_quark_try_string(name1),g_quark_try_string(name2))

Copies one value identified by a string key from one container to another one.

The source value must exist. If it is an object or boxed, it is copied by value, i.e. the functions always does a deep copy.

#### Parameters

dict1 | Source dictionary. |
dict2 | Destination dictionary. It may be the same container as `source` . |
name1 | String key in `source` . |
name2 | String key in `dest` . |

### gwy_dict_remove_by_name()

    #define gwy_dict_remove_by_name(dict,name)                   gwy_dict_remove(dict,g_quark_try_string(name))

Removes a value identified by name `name` from container `dict` .

Expands to `TRUE` if there was such a value and was removed.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_rename_by_name()

    #define gwy_dict_rename_by_name(dict,name,nn,f)              gwy_dict_rename(dict,g_quark_try_string(name),g_quark_from_string(nn),f)

Makes a value in container `dict` identified by name `name` to be identified by new name `nn` .

See `gwy_dict_rename()` for details.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
nn | A nul-terminated name. |
f | Whether to delete existing value at `newkey` . |

### gwy_dict_set_boolean_by_name()

    #define gwy_dict_set_boolean_by_name(dict,name,value)        gwy_dict_set_boolean(dict,g_quark_from_string(name),value)

Stores a boolean into container `dict` , identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | A boolean. |

### gwy_dict_get_boolean_by_name()

    #define gwy_dict_get_boolean_by_name(dict,name)              gwy_dict_get_boolean(dict,g_quark_from_string(name))

Gets the boolean in container `dict` identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_boolean_by_name()

    #define gwy_dict_gis_boolean_by_name(dict,name,value)        gwy_dict_gis_boolean(dict,g_quark_try_string(name),value)

Get-if-set a boolean from a dictionary.

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such boolean in the container.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the boolean to update. |

### gwy_dict_set_uchar_by_name()

    #define gwy_dict_set_uchar_by_name(dict,name,value)          gwy_dict_set_uchar(dict,g_quark_from_string(name),value)

Stores an unsigned character into container `dict` , identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | An unsigned character. |

### gwy_dict_get_uchar_by_name()

    #define gwy_dict_get_uchar_by_name(dict,name)                gwy_dict_get_uchar(dict,g_quark_from_string(name))

Gets the unsigned character in container `dict` identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_uchar_by_name()

    #define gwy_dict_gis_uchar_by_name(dict,name,value)          gwy_dict_gis_uchar(dict,g_quark_try_string(name),value)

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

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such unsigned char in the container.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the unsigned char to update. |

### gwy_dict_set_int32_by_name()

    #define gwy_dict_set_int32_by_name(dict,name,value)          gwy_dict_set_int32(dict,g_quark_from_string(name),value)

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

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | A 32bit integer. |

### gwy_dict_get_int32_by_name()

    #define gwy_dict_get_int32_by_name(dict,name)                gwy_dict_get_int32(dict,g_quark_from_string(name))

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

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_int32_by_name()

    #define gwy_dict_gis_int32_by_name(dict,name,value)          gwy_dict_gis_int32(dict,g_quark_try_string(name),value)

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

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such 32bit integer in the container.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the 32bit integer to update. |

### gwy_dict_set_enum_by_name()

    #define gwy_dict_set_enum_by_name(dict,name,value)           gwy_dict_set_enum(dict,g_quark_from_string(name),value)

Stores an enum into container `dict` , identified by name `name` .

Note enums are treated as 32bit integers.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | An enum. |

### gwy_dict_get_enum_by_name()

    #define gwy_dict_get_enum_by_name(dict,name)                 gwy_dict_get_enum(dict,g_quark_from_string(name))

Gets the enum in container `dict` identified by name `name` .

Note enums are treated as 32bit integers.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_enum_by_name()

    #define gwy_dict_gis_enum_by_name(dict,name,value)           gwy_dict_gis_enum(dict,g_quark_try_string(name),value)

Get-if-set an enum from a dictionary.

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.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the enum to update. |

### gwy_dict_set_int64_by_name()

    #define gwy_dict_set_int64_by_name(dict,name,value)          gwy_dict_set_int64(dict,g_quark_from_string(name),value)

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

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | A 64bit integer. |

### gwy_dict_get_int64_by_name()

    #define gwy_dict_get_int64_by_name(dict,name)                gwy_dict_get_int64(dict,g_quark_from_string(name))

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

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_int64_by_name()

    #define gwy_dict_gis_int64_by_name(dict,name,value)          gwy_dict_gis_int64(dict,g_quark_try_string(name),value)

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

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such 64bit integer in the container.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the 64bit integer to update. |

### gwy_dict_set_double_by_name()

    #define gwy_dict_set_double_by_name(dict,name,value)         gwy_dict_set_double(dict,g_quark_from_string(name),value)

Stores a double into container `dict` , identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | A double integer. |

### gwy_dict_get_double_by_name()

    #define gwy_dict_get_double_by_name(dict,name)               gwy_dict_get_double(dict,g_quark_from_string(name))

Gets the double in container `dict` identified by name `name` .

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_double_by_name()

    #define gwy_dict_gis_double_by_name(dict,name,value)         gwy_dict_gis_double(dict,g_quark_try_string(name),value)

Get-if-set a double from a dictionary.

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such double in the container.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the double to update. |

### gwy_dict_pass_string_by_name()

    #define gwy_dict_pass_string_by_name(dict,name,value)        gwy_dict_pass_string(dict,g_quark_from_string(name),value)

Stores a string into container `dict` , identified by name `name` .

See `gwy_dict_pass_string()` for details.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | A nul-terminated string. |

### gwy_dict_set_string_by_name()

    #define gwy_dict_set_string_by_name(dict,name,value)         gwy_dict_set_string(dict,g_quark_from_string(name),value)

Stores a string into container `dict` , identified by name `name` .

The container makes a copy of the string, so it can be used on static strings and strings owned by other entities.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | A nul-terminated string. |

### gwy_dict_get_string_by_name()

    #define gwy_dict_get_string_by_name(dict,name)               gwy_dict_get_string(dict,g_quark_from_string(name))

Gets the string in container `dict` identified by name `name` .

The returned string must be treated as constant and never freed or modified.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_string_by_name()

    #define gwy_dict_gis_string_by_name(dict,name,value)         gwy_dict_gis_string(dict,g_quark_try_string(name),value)

Get-if-set a string from a dictionary.

The string possibly stored in `value` 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.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the string pointer to update. |

### gwy_dict_set_object_by_name()

    #define gwy_dict_set_object_by_name(dict,name,value)         gwy_dict_set_object(dict,g_quark_from_string(name),value)

Stores an object into container `dict` , identified by name `name` .

See `gwy_dict_set_object()` for details.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | An object to store into container. |

### gwy_dict_pass_object_by_name()

    #define gwy_dict_pass_object_by_name(dict,name,value)        gwy_dict_pass_object(dict,g_quark_from_string(name),value)

Stores an object into container `dict` , identified by name `name` , passing reference to the container.

See `gwy_dict_pass_object()` for details.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | An object to store into container. |

### gwy_dict_get_object_by_name()

    #define gwy_dict_get_object_by_name(dict,name)               gwy_dict_get_object(dict,g_quark_from_string(name))

Gets the object in container `dict` identified by name `name` .

The returned object does not have its reference count increased, use `g_object_ref()` if you want to access it even when `dict` may cease to exist.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |

### gwy_dict_gis_object_by_name()

    #define gwy_dict_gis_object_by_name(dict,name,value)         gwy_dict_gis_object(dict,g_quark_try_string(name),value)

Get-if-set an object from a dictionary.

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 `dict` may cease to exist.

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such object in the container.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
value | Pointer to the object pointer to update. |

### gwy_dict_set_boxed_by_name()

    #define gwy_dict_set_boxed_by_name(dict,type,name,value)     gwy_dict_set_boxed(dict,type,g_quark_from_string(name),value)

Stores a boxed pointer into container `dict` , identified by name `name` .

See `gwy_dict_set_boxed()` for details.

#### Parameters

dict | A dictionary-like data container. |
type | The boxed type. |
name | A nul-terminated name. |
value | An boxed to store into container. |

### gwy_dict_pass_boxed_by_name()

    #define gwy_dict_pass_boxed_by_name(dict,type,name,value)    gwy_dict_pass_boxed(dict,type,g_quark_from_string(name),value)

Stores an boxed pointer into container `dict` , identified by name `name` , passing ownership to the container.

See `gwy_dict_pass_boxed()` for details.

#### Parameters

dict | A dictionary-like data container. |
type | The boxed type. |
name | A nul-terminated name. |
value | An boxed to store into container. |

### gwy_dict_get_boxed_by_name()

    #define gwy_dict_get_boxed_by_name(dict,type,name)           gwy_dict_get_boxed(dict,type,g_quark_from_string(name))

Gets the boxed pointer in container `dict` identified by name `name` .

See `gwy_dict_get_boxed()`.

#### Parameters

dict | A dictionary-like data container. |
name | A nul-terminated name. |
type | The boxed type. |

### gwy_dict_gis_boxed_by_name()

    #define gwy_dict_gis_boxed_by_name(dict,type,name,value)     gwy_dict_gis_boxed(dict,type,g_quark_try_string(name),value)

Get-if-set a boxed pointer from a dictionary.

It is an error to request a boxed pointer of different type than is actually stored.

The boxed pointer is copied to `value` by value, which is always possbile as only serialisable boxed types can be stored in a GwyDict. The `value` pointer thus does not have the extra level of indirection objects and strings have:

    1
    2
    GwyXYZ xyz;
    gwy_dict_gis_boxed_by_name(dict, GWY_TYPE_XYZ, "/some/name", &xyz);

Expands to `TRUE` if `value` was actually updated, `FALSE` when there is no such boxed in the container.

#### Parameters

dict | A dictionary-like data container. |
type | The boxed type. |
name | A nul-terminated name. |
value | The boxed pointer to update. |

## Types and Values

### GWY_DICT_PATHSEP

    #define GWY_DICT_PATHSEP      '/'

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

### GWY_DICT_PATHSEP_STR

    #define GWY_DICT_PATHSEP_STR  "/"

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

### struct GwyDict

    struct GwyDict;

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

### struct GwyDictClass

    struct GwyDictClass {
        GObjectClass parent_class;

        void (*item_changed)(GwyDict *dict, GQuark key);
        void (*construction_finished)(GwyDict *dict);
    };

## Signal Details

### The `“item-changed”` signal

    void
    user_function (GwyDict *gwydict,
                   guint    arg1,
                   gpointer user_data)

The ::item-changed signal is emitted whenever a dictionary item is changed. The detail is the string key identifier.

#### Parameters

gwydict | The GwyDict 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

## See Also

GwyInventory