libsoup Reference Manual: GValue Support

## GValue Support GValue Support — GValue utilities |

## Functions

GHashTable * | soup_value_hash_new ()
GHashTable * | soup_value_hash_new_with_vals ()
void | soup_value_hash_insert_value ()
void | soup_value_hash_insert ()
void | soup_value_hash_insert_vals ()
gboolean | soup_value_hash_lookup ()
gboolean | soup_value_hash_lookup_vals ()
GValueArray * | soup_value_array_from_args ()
gboolean | soup_value_array_to_args ()
GValueArray * | soup_value_array_new ()
GValueArray * | soup_value_array_new_with_vals ()
void | soup_value_array_insert ()
void | soup_value_array_append ()
void | soup_value_array_append_vals ()
gboolean | soup_value_array_get_nth ()
#define | SOUP_VALUE_SETV()
#define | SOUP_VALUE_GETV()
#define | SOUP_TYPE_BYTE_ARRAY

## Includes

    #include <libsoup/soup.h>

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

## Functions

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

args | arguments to create a GValueArray from |

#### Returns

a new GValueArray, or `NULL` if an error occurred.

[nullable]

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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 did not used to define a GType for GByteArray, so libsoup defines this one itself.

## Types and Values