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

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

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

Generated by GTK-Doc V1.10