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);
gchar*      tp_escape_as_identifier         (const gchar *name);

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_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