Utilities

## Utilities Utilities — Non-Telepathy utility functions |

## Synopsis

    #include <telepathy-glib/util.h>

    #define             tp_verify                           (R)
    #define             tp_verify_true                      (R)
    #define             tp_verify_statement                 (R)
    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);
    GValue *            tp_g_value_slice_new_boolean        (gboolean b);
    GValue *            tp_g_value_slice_new_boxed          (GType type,
                                                             gconstpointer p);
    GValue *            tp_g_value_slice_new_static_boxed   (GType type,
                                                             gconstpointer p);
    GValue *            tp_g_value_slice_new_take_boxed     (GType type,
                                                             gpointer p);
    GValue *            tp_g_value_slice_new_double         (double d);
    GValue *            tp_g_value_slice_new_int            (gint n);
    GValue *            tp_g_value_slice_new_int64          (gint64 n);
    GValue *            tp_g_value_slice_new_string         (const gchar *string);
    GValue *            tp_g_value_slice_new_static_string  (const gchar *string);
    GValue *            tp_g_value_slice_new_take_string    (gchar *string);
    GValue *            tp_g_value_slice_new_uint           (guint n);
    GValue *            tp_g_value_slice_new_uint64         (guint64 n);
    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);
    gint64              tp_g_key_file_get_int64             (GKeyFile *key_file,
                                                             const gchar *group_name,
                                                             const gchar *key,
                                                             GError **error);
    guint64             tp_g_key_file_get_uint64            (GKeyFile *key_file,
                                                             const gchar *group_name,
                                                             const gchar *key,
                                                             GError **error);
    gulong              tp_g_signal_connect_object          (gpointer instance,
                                                             const gchar *detailed_signal,
                                                             GCallback c_handler,
                                                             gpointer gobject,
                                                             GConnectFlags connect_flags);
    GValueArray *       tp_value_array_build                (gsize length,
                                                             GType type,
                                                             ...);

## Description

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

## Details

### tp_verify()

    # define tp_verify(R) extern int (* tp_verify_function__ (void)) [tp_verify_true (R)]

Make an assertion at compile time, like C++0x's proposed static_assert keyword. If `R` is determined to be true, there is no overhead at runtime; if `R` is determined to be false, compilation will fail.

This macro can be used at file scope (it expands to a dummy extern declaration).

(This is gnulib's verify macro, written by Paul Eggert, Bruno Haible and Jim Meyering.)

`R` : | a requirement (constant expression) to be checked at compile-time

Since 0.7.34

### tp_verify_true()

    #define             tp_verify_true(R)

Make an assertion at compile time, like C++0x's proposed static_assert keyword. If `R` is determined to be true, there is no overhead at runtime, and the macro evaluates to 1 as an integer constant expression; if `R` is determined to be false, compilation will fail.

This macro can be used anywhere that an integer constant expression would be allowed.

(This is gnulib's verify_true macro, written by Paul Eggert, Bruno Haible and Jim Meyering.)

`R` : | a requirement (constant expression) to be checked at compile-time
Returns : | 1

Since 0.7.34

### tp_verify_statement()

    #define tp_verify_statement(R) ((void) tp_verify_true (R))

Make an assertion at compile time, like C++0x's proposed static_assert keyword. If `R` is determined to be true, there is no overhead at runtime; if `R` is determined to be false, compilation will fail.

This macro can be used anywhere that a statement would be allowed; it is equivalent to ((void) tp_verify_true (R)).

`R` : | a requirement (constant expression) to be checked at compile-time

Since 0.7.34

### 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);

Slice-allocate an empty GValue. `tp_g_value_slice_new_boolean()` and similar functions are likely to be more convenient to use for the types supported.

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

    GValue *            tp_g_value_slice_new_boolean        (gboolean b);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`b` : | a boolean value
Returns : | a GValue of type `G_TYPE_BOOLEAN` with value `b`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_boxed ()

    GValue *            tp_g_value_slice_new_boxed          (GType type,
                                                             gconstpointer p);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`type` : | a boxed type
`p` : | a pointer of type `type`, which will be copied
Returns : | a GValue of type `type` whose value is a copy of `p`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_static_boxed ()

    GValue *            tp_g_value_slice_new_static_boxed   (GType type,
                                                             gconstpointer p);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`type` : | a boxed type
`p` : | a pointer of type `type`, which must remain valid forever
Returns : | a GValue of type `type` whose value is `p`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_take_boxed ()

    GValue *            tp_g_value_slice_new_take_boxed     (GType type,
                                                             gpointer p);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`type` : | a boxed type
`p` : | a pointer of type `type` which will be freed with `g_boxed_free()` by the returned GValue (the caller must own it before calling this function, but no longer owns it after this function returns)
Returns : | a GValue of type `type` whose value is `p`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_double ()

    GValue *            tp_g_value_slice_new_double         (double d);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`d` : | a number
Returns : | a GValue of type `G_TYPE_DOUBLE` with value `n`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_int ()

    GValue *            tp_g_value_slice_new_int            (gint n);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`n` : | an integer
Returns : | a GValue of type `G_TYPE_INT` with value `n`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_int64 ()

    GValue *            tp_g_value_slice_new_int64          (gint64 n);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`n` : | a 64-bit integer
Returns : | a GValue of type `G_TYPE_INT64` with value `n`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_string ()

    GValue *            tp_g_value_slice_new_string         (const gchar *string);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`string` : | a string to be copied into the value
Returns : | a GValue of type `G_TYPE_STRING` whose value is a copy of `string`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_static_string ()

    GValue *            tp_g_value_slice_new_static_string  (const gchar *string);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`string` : | a static string which must remain valid forever, to be pointed to by the value
Returns : | a GValue of type `G_TYPE_STRING` whose value is `string`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_take_string ()

    GValue *            tp_g_value_slice_new_take_string    (gchar *string);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`string` : | a string which will be freed with `g_free()` by the returned GValue (the caller must own it before calling this function, but no longer owns it after this function returns)
Returns : | a GValue of type `G_TYPE_STRING` whose value is `string`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_uint ()

    GValue *            tp_g_value_slice_new_uint           (guint n);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`n` : | an unsigned integer
Returns : | a GValue of type `G_TYPE_UINT` with value `n`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_new_uint64 ()

    GValue *            tp_g_value_slice_new_uint64         (guint64 n);

Slice-allocate and initialize a GValue. This function is convenient to use when constructing hash tables from string to GValue, for example.

`n` : | a 64-bit unsigned integer
Returns : | a GValue of type `G_TYPE_UINT64` with value `n`, to be freed with `tp_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### tp_g_value_slice_free ()

    void                tp_g_value_slice_free               (GValue *value);

Unset and free a slice-allocated GValue.

`(GDestroyNotify) tp_g_value_slice_free` can be used as a destructor for values in a GHashTable, for example.

`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

### tp_g_key_file_get_int64 ()

    gint64              tp_g_key_file_get_int64             (GKeyFile *key_file,
                                                             const gchar *group_name,
                                                             const gchar *key,
                                                             GError **error);

Returns the value associated with `key` under `group_name` as a signed 64-bit integer. This is similar to `g_key_file_get_integer()` but can return 64-bit results without truncation.

`key_file` : | a non-`NULL` GKeyFile
`group_name` : | a non-`NULL` group name
`key` : | a non-`NULL` key
`error` : | return location for a GError
Returns : | the value associated with the key as a signed 64-bit integer, or 0 if the key was not found or could not be parsed.

Since 0.7.31

### tp_g_key_file_get_uint64 ()

    guint64             tp_g_key_file_get_uint64            (GKeyFile *key_file,
                                                             const gchar *group_name,
                                                             const gchar *key,
                                                             GError **error);

Returns the value associated with `key` under `group_name` as an unsigned 64-bit integer. This is similar to `g_key_file_get_integer()` but can return large positive results without truncation.

`key_file` : | a non-`NULL` GKeyFile
`group_name` : | a non-`NULL` group name
`key` : | a non-`NULL` key
`error` : | return location for a GError
Returns : | the value associated with the key as an unsigned 64-bit integer, or 0 if the key was not found or could not be parsed.

Since 0.7.31

### tp_g_signal_connect_object ()

    gulong              tp_g_signal_connect_object          (gpointer instance,
                                                             const gchar *detailed_signal,
                                                             GCallback c_handler,
                                                             gpointer gobject,
                                                             GConnectFlags connect_flags);

Connects a GCallback function to a signal for a particular object, as if with `g_signal_connect()`. Additionally, arranges for the signal handler to be disconnected if `gobject` is destroyed.

This is similar to `g_signal_connect_data()`, but uses a closure which ensures that the `gobject` stays alive during the call to `c_handler` by temporarily adding a reference count to `gobject`.

This is similar to `g_signal_connect_object()`, but doesn't have the documented bug that everyone is too scared to fix. Also, it does not allow you to pass in NULL as `gobject`

This is intended to be a convenient way for objects to use themselves as user_data for callbacks without having to explicitly disconnect all the handlers in their finalizers.

Changed in 0.10.4 and 0.11.3: `G_CONNECT_AFTER` is now respected.

`instance` : | the instance to connect to.
`detailed_signal` : | a string of the form "signal-name::detail".
`c_handler` : | the GCallback to connect.
`gobject` : | the object to pass as data to `c_handler`.
`connect_flags` : | a combination of GConnectFlags. Only `G_CONNECT_AFTER` and `G_CONNECT_SWAPPED` are supported by this function.
Returns : | the handler id

Since 0.9.2

### tp_value_array_build ()

    GValueArray *       tp_value_array_build                (gsize length,
                                                             GType type,
                                                             ...);

Creates a new GValueArray for use with structs, containing the values passed in as parameters. The values are copied or reffed as appropriate for their type.

Example 2. using tp_value_array_build

    1
    2
    3
    4
    GValueArray *array = tp_value_array_build (2,
       G_TYPE_STRING, host,
       G_TYPE_UINT, port,
       G_TYPE_INVALID);

`length` : | The number of elements that should be in the array
`type` : | The type of the first argument.
`...` : | The value of the first item in the struct followed by a list of type, value pairs terminated by G_TYPE_INVALID.
Returns : | a newly created GValueArray, free with g_value_array_free.

Since 0.9.2