## Utilities Utilities — Non-Telepathy utility functions |

## Synopsis

    #include <telepathy-glib/util.h>

    void                tp_g_hash_table_update              (GHashTable *target,
                                                             GHashTable *source,
                                                             GBoxedCopyFunc key_dup,
                                                             GBoxedCopyFunc value_dup);
    gboolean            tp_g_ptr_array_contains             (GPtrArray *haystack,
                                                             gpointer needle);
    GValue*             tp_g_value_slice_new                (GType type);
    void                tp_g_value_slice_free               (GValue *value);
    GValue*             tp_g_value_slice_dup                (const GValue *value);
    gboolean            tp_strdiff                          (const gchar *left,
                                                             const gchar *right);
    gpointer            tp_mixin_offset_cast                (gpointer instance,
                                                             guint offset);
    guint               tp_mixin_class_get_offset           (gpointer klass,
                                                             GQuark quark);
    guint               tp_mixin_instance_get_offset        (gpointer instance,
                                                             GQuark quark);
    gchar*              tp_escape_as_identifier             (const gchar *name);
    gboolean            tp_strv_contains                    (const gchar * const *strv,
                                                             const gchar *str);

## Description

Some utility functions used in telepathy-glib which could have been in GLib, but aren't.

## Details

### tp_g_hash_table_update ()

    void                tp_g_hash_table_update              (GHashTable *target,
                                                             GHashTable *source,
                                                             GBoxedCopyFunc key_dup,
                                                             GBoxedCopyFunc value_dup);

Add each item in `source` to `target`, replacing any existing item with the same key. `key_dup` and `value_dup` are used to duplicate the items; in principle they could also be used to convert between types.

`target` : | The hash table to be updated
`source` : | The hash table to update it with (read-only)
`key_dup` : | function to duplicate a key from `source` so it can be be stored in `target`. If NULL, the key is not copied, but is used as-is
`value_dup` : | function to duplicate a value from `source` so it can be stored in `target`. If NULL, the value is not copied, but is used as-is

Since 0.7.0

### tp_g_ptr_array_contains ()

    gboolean            tp_g_ptr_array_contains             (GPtrArray *haystack,
                                                             gpointer needle);

`haystack` : | The pointer array to be searched
`needle` : | The pointer to look for
Returns : | `TRUE` if `needle` is one of the elements of `haystack`

### tp_g_value_slice_new ()

    GValue*             tp_g_value_slice_new                (GType type);

`type` : | The type desired for the new GValue
Returns : | a newly allocated, newly initialized GValue, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`.

Since 0.5.14

### tp_g_value_slice_free ()

    void                tp_g_value_slice_free               (GValue *value);

Unset and free a slice-allocated GValue.

`value` : | A GValue which was allocated with the g_slice API

### tp_g_value_slice_dup ()

    GValue*             tp_g_value_slice_dup                (const GValue *value);

`value` : | A GValue
Returns : | a newly allocated copy of `value`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`.

Since 0.5.14

### tp_strdiff ()

    gboolean            tp_strdiff                          (const gchar *left,
                                                             const gchar *right);

Return `TRUE` if the given strings are different. Unlike strcmp this function will handle null pointers, treating them as distinct from any string.

`left` : | The first string to compare (may be NULL)
`right` : | The second string to compare (may be NULL)
Returns : | `FALSE` if `left` and `right` are both `NULL`, or if neither is `NULL` and both have the same contents; `TRUE` otherwise

### tp_mixin_offset_cast ()

    gpointer            tp_mixin_offset_cast                (gpointer instance,
                                                             guint offset);

Extend a pointer by an offset, provided the offset is not 0. This is used to cast from an object instance to one of the telepathy-glib mixin classes.

`instance` : | A pointer to a structure
`offset` : | The offset of a structure member in bytes, which must not be 0
Returns : | a pointer `offset` bytes beyond `instance`

### tp_mixin_class_get_offset ()

    guint               tp_mixin_class_get_offset           (gpointer klass,
                                                             GQuark quark);

If the type of `klass`, or any of its ancestor types, has had an offset attached using qdata with the given `quark`, return that offset. If not, this indicates a programming error and results are undefined.

This is used to implement the telepathy-glib mixin classes.

`klass` : | A pointer to a GObjectClass-derived class structure
`quark` : | A quark that was used to store the offset with `g_type_set_qdata()`
Returns : | the offset of the mixin class

### tp_mixin_instance_get_offset ()

    guint               tp_mixin_instance_get_offset        (gpointer instance,
                                                             GQuark quark);

If the type of `instance`, or any of its ancestor types, has had an offset attached using qdata with the given `quark`, return that offset. If not, this indicates a programming error and results are undefined.

This is used to implement the telepathy-glib mixin classes.

`instance` : | A pointer to a GObject-derived instance structure
`quark` : | A quark that was used to store the offset with `g_type_set_qdata()`
Returns : | the offset of the mixin

### tp_escape_as_identifier ()

    gchar*              tp_escape_as_identifier             (const gchar *name);

Escape an arbitrary string so it follows the rules for a C identifier, and hence an object path component, interface element component, bus name component or member name in D-Bus.

Unlike g_strcanon this is a reversible encoding, so it preserves distinctness.

The escaping consists of replacing all non-alphanumerics, and the first character if it's a digit, with an underscore and two lower-case hex digits:

"0123abc_xyz\x01\xff" -> _30123abc_5fxyz_01_ff

i.e. similar to URI encoding, but with _ taking the role of %, and a smaller allowed set. As a special case, "" is escaped to "_" (just for completeness, really).

`name` : | The string to be escaped
Returns : | the escaped string, which must be freed by the caller with g_free

### tp_strv_contains ()

    gboolean            tp_strv_contains                    (const gchar * const *strv,
                                                             const gchar *str);

`strv` : | a NULL-terminated array of strings, or `NULL` (which is treated as an empty strv)
`str` : | a non-NULL string
Returns : | TRUE if `str` is an element of `strv`, according to `strcmp()`.

Since 0.7.15