GValue Support

## GValue Support GValue Support — GValue utilities |

## Synopsis

    #include <libsoup/soup.h>

    GHashTable *        soup_value_hash_new                 (void);
    GHashTable *        soup_value_hash_new_with_vals       (const char *first_key,
                                                             ...);
    void                soup_value_hash_insert_value        (GHashTable *hash,
                                                             const char *key,
                                                             GValue *value);
    void                soup_value_hash_insert              (GHashTable *hash,
                                                             const char *key,
                                                             GType type,
                                                             ...);
    void                soup_value_hash_insert_vals         (GHashTable *hash,
                                                             const char *first_key,
                                                             ...);
    gboolean            soup_value_hash_lookup              (GHashTable *hash,
                                                             const char *key,
                                                             GType type,
                                                             ...);
    gboolean            soup_value_hash_lookup_vals         (GHashTable *hash,
                                                             const char *first_key,
                                                             ...);

    GValueArray *       soup_value_array_from_args          (va_list args);
    gboolean            soup_value_array_to_args            (GValueArray *array,
                                                             va_list args);
    GValueArray *       soup_value_array_new                (void);
    GValueArray *       soup_value_array_new_with_vals      (GType first_type,
                                                             ...);
    void                soup_value_array_insert             (GValueArray *array,
                                                             guint index_,
                                                             GType type,
                                                             ...);
    void                soup_value_array_append             (GValueArray *array,
                                                             GType type,
                                                             ...);
    void                soup_value_array_append_vals        (GValueArray *array,
                                                             GType first_type,
                                                             ...);
    gboolean            soup_value_array_get_nth            (GValueArray *array,
                                                             guint index_,
                                                             GType type,
                                                             ...);

    #define             SOUP_VALUE_SETV                     (val,
                                                             type,
                                                             args)
    #define             SOUP_VALUE_GETV                     (val,
                                                             type,
                                                             args)

    #define             SOUP_TYPE_BYTE_ARRAY

## Description

These methods are useful for manipulating GValues, and in particular, arrays and hash tables of GValues, in a slightly nicer way than the standard GValue API.

They are written for use with soup-xmlrpc, but they also work with types not used by XML-RPC.

## Details

### soup_value_hash_new ()

    GHashTable *        soup_value_hash_new                 (void);

Creates a GHashTable whose keys are strings and whose values are GValue.

Returns : | a new empty GHashTable. [element-type utf8 GValue][transfer full]

### soup_value_hash_new_with_vals ()

    GHashTable *        soup_value_hash_new_with_vals       (const char *first_key,
                                                             ...);

Creates a GHashTable whose keys are strings and whose values are GValue, and initializes it with the provided data. As with `soup_value_hash_insert()`, the keys and values are copied rather than being inserted directly.

`first_key` : | the key for the first value
`...` : | the type of `first_key`, followed by the value, followed by additional key/type/value triplets, terminated by `NULL`
Returns : | a new GHashTable, initialized with the given values. [element-type utf8 GValue][transfer full]

### soup_value_hash_insert_value ()

    void                soup_value_hash_insert_value        (GHashTable *hash,
                                                             const char *key,
                                                             GValue *value);

Inserts `value` into `hash`. (Unlike with `g_hash_table_insert()`, both the key and the value are copied).

`hash` : | a value hash. [element-type utf8 GValue]
`key` : | the key
`value` : | a value

### soup_value_hash_insert ()

    void                soup_value_hash_insert              (GHashTable *hash,
                                                             const char *key,
                                                             GType type,
                                                             ...);

Inserts the provided value of type `type` into `hash`. (Unlike with `g_hash_table_insert()`, both the key and the value are copied).

`hash` : | a value hash. [element-type utf8 GValue]
`key` : | the key
`type` : | a GType
`...` : | a value of type `type`

### soup_value_hash_insert_vals ()

    void                soup_value_hash_insert_vals         (GHashTable *hash,
                                                             const char *first_key,
                                                             ...);

Inserts the given data into `hash`. As with `soup_value_hash_insert()`, the keys and values are copied rather than being inserted directly.

`hash` : | a value hash. [element-type utf8 GValue]
`first_key` : | the key for the first value
`...` : | the type of `first_key`, followed by the value, followed by additional key/type/value triplets, terminated by `NULL`

### soup_value_hash_lookup ()

    gboolean            soup_value_hash_lookup              (GHashTable *hash,
                                                             const char *key,
                                                             GType type,
                                                             ...);

Looks up `key` in `hash` and stores its value into the provided location.

`hash` : | a value hash. [element-type utf8 GValue]
`key` : | the key to look up
`type` : | a GType
`...` : | a value of type pointer-to-`type`
Returns : | `TRUE` if `hash` contained a value with key `key` and type `type`, `FALSE` if not.

### soup_value_hash_lookup_vals ()

    gboolean            soup_value_hash_lookup_vals         (GHashTable *hash,
                                                             const char *first_key,
                                                             ...);

Looks up a number of keys in `hash` and returns their values.

`hash` : | a value hash. [element-type utf8 GValue]
`first_key` : | the first key to look up
`...` : | the type of `first_key`, a pointer to that type, and then additional key/type/pointer triplets, terminated by `NULL`.
Returns : | `TRUE` if all of the keys were found, `FALSE` if any were missing; note that you will generally need to initialize each destination variable to a reasonable default value, since there is no way to tell which keys were found and which were not.

### soup_value_array_from_args ()

    GValueArray *       soup_value_array_from_args          (va_list args);

Creates a GValueArray from the provided arguments, which must consist of pairs of a GType and a value of that type, terminated by `G_TYPE_INVALID`. (The array will contain copies of the provided data rather than pointing to the passed-in data directly.)

`args` : | arguments to create a GValueArray from
Returns : | a new GValueArray, or `NULL` if an error occurred.

### soup_value_array_to_args ()

    gboolean            soup_value_array_to_args            (GValueArray *array,
                                                             va_list args);

Extracts a GValueArray into the provided arguments, which must consist of pairs of a GType and a value of pointer-to-that-type, terminated by `G_TYPE_INVALID`. The returned values will point to the same memory as the values in the array.

`array` : | a GValueArray
`args` : | arguments to extract `array` into
Returns : | success or failure

### soup_value_array_new ()

    GValueArray *       soup_value_array_new                (void);

Creates a new `GValueArray`. (This is just a wrapper around `g_value_array_new()`, for naming consistency purposes.)

Returns : | a new `GValueArray`

### soup_value_array_new_with_vals ()

    GValueArray *       soup_value_array_new_with_vals      (GType first_type,
                                                             ...);

Creates a new `GValueArray` and copies the provided values into it.

`first_type` : | the type of the first value to add
`...` : | the first value to add, followed by other type/value pairs, terminated by `G_TYPE_INVALID`
Returns : | a new `GValueArray`

### soup_value_array_insert ()

    void                soup_value_array_insert             (GValueArray *array,
                                                             guint index_,
                                                             GType type,
                                                             ...);

Inserts the provided value of type `type` into `array` as with `g_value_array_insert()`. (The provided data is copied rather than being inserted directly.)

`array` : | a GValueArray
`index_` : | the index to insert at
`type` : | a GType
`...` : | a value of type `type`

### soup_value_array_append ()

    void                soup_value_array_append             (GValueArray *array,
                                                             GType type,
                                                             ...);

Appends the provided value of type `type` to `array` as with `g_value_array_append()`. (The provided data is copied rather than being inserted directly.)

`array` : | a GValueArray
`type` : | a GType
`...` : | a value of type `type`

### soup_value_array_append_vals ()

    void                soup_value_array_append_vals        (GValueArray *array,
                                                             GType first_type,
                                                             ...);

Appends the provided values into `array` as with `g_value_array_append()`. (The provided data is copied rather than being inserted directly.)

`array` : | a GValueArray
`first_type` : | the type of the first value to add
`...` : | the first value to add, followed by other type/value pairs, terminated by `G_TYPE_INVALID`

### soup_value_array_get_nth ()

    gboolean            soup_value_array_get_nth            (GValueArray *array,
                                                             guint index_,
                                                             GType type,
                                                             ...);

Gets the `index_` element of `array` and stores its value into the provided location.

`array` : | a GValueArray
`index_` : | the index to look up
`type` : | a GType
`...` : | a value of type pointer-to-`type`
Returns : | `TRUE` if `array` contained a value with index `index_` and type `type`, `FALSE` if not.

### SOUP_VALUE_SETV()

    #define             SOUP_VALUE_SETV(val, type, args)

Copies an argument of type `type` from `args` into `val`. `val` will point directly to the value in `args` rather than copying it, so you must `g_value_copy()` it if you want it to remain valid.

`val` : | a GValue
`type` : | a GType
`args` : | va_list pointing to a value of type `type`

### SOUP_VALUE_GETV()

    #define             SOUP_VALUE_GETV(val, type, args)

Extracts a value of type `type` from `val` into `args`. The return value will point to the same data as `val` rather than being a copy of it.

`val` : | a GValue
`type` : | a GType
`args` : | va_list pointing to a value of type pointer-to-`type`

### SOUP_TYPE_BYTE_ARRAY

    #define SOUP_TYPE_BYTE_ARRAY (soup_byte_array_get_type ())

glib does not define a GType for GByteArray, so libsoup defines this one itself.