wocky-utils

## wocky-utils wocky-utils |

## Synopsis

    gboolean            wocky_strdiff                       (const gchar *left,
                                                             const gchar *right);
    gchar *             wocky_normalise_jid                 (const gchar *jid);
    gboolean            wocky_decode_jid                    (const gchar *jid,
                                                             gchar **node,
                                                             gchar **domain,
                                                             gchar **resource);
    gchar *             wocky_compose_jid                   (const gchar *node,
                                                             const gchar *domain,
                                                             const gchar *resource);
    GValue *            wocky_g_value_slice_new             (GType type);
    GValue *            wocky_g_value_slice_new_boolean     (gboolean b);
    GValue *            wocky_g_value_slice_new_int         (gint n);
    GValue *            wocky_g_value_slice_new_int64       (gint64 n);
    GValue *            wocky_g_value_slice_new_uint        (guint n);
    GValue *            wocky_g_value_slice_new_uint64      (guint64 n);
    GValue *            wocky_g_value_slice_new_double      (double d);
    GValue *            wocky_g_value_slice_new_string      (const gchar *string);
    GValue *            wocky_g_value_slice_new_static_string
                                                            (const gchar *string);
    GValue *            wocky_g_value_slice_new_take_string (gchar *string);
    GValue *            wocky_g_value_slice_new_boxed       (GType type,
                                                             gconstpointer p);
    GValue *            wocky_g_value_slice_new_static_boxed
                                                            (GType type,
                                                             gconstpointer p);
    GValue *            wocky_g_value_slice_new_take_boxed  (GType type,
                                                             gpointer p);
    void                wocky_g_value_slice_free            (GValue *value);
    GValue *            wocky_g_value_slice_dup             (const GValue *value);
    gboolean            wocky_enum_from_nick                (GType enum_type,
                                                             const gchar *nick,
                                                             gint *value);
    const gchar *       wocky_enum_to_nick                  (GType enum_type,
                                                             gint value);
    gchar *             wocky_absolutize_path               (const gchar *path);
    GList *             wocky_list_deep_copy                (GBoxedCopyFunc copy,
                                                             GList *items);
    GString *           wocky_g_string_dup                  (const GString *str);
    void                wocky_g_string_free                 (GString *str);
    #define             wocky_implement_finish_void         (source,
                                                             tag)
    #define             wocky_implement_finish_copy_pointer (source,
                                                             tag,
                                                             copy_func,
                                                             out_param)
    #define             wocky_implement_finish_return_copy_pointer(source,
                                                             tag,
                                                             copy_func)
    #define             wocky_implement_finish_return_pointer(source,
                                                             tag)

## Description

## Details

### wocky_strdiff ()

    gboolean            wocky_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

### wocky_normalise_jid ()

    gchar *             wocky_normalise_jid                 (const gchar *jid);

`jid` : | a JID
Returns : | a normalised JID, using the same rules as `wocky_decode_jid()`, or `NULL` if the JID could not be sensibly decoded. This value should be freed when you are done with it.

### wocky_decode_jid ()

    gboolean            wocky_decode_jid                    (const gchar *jid,
                                                             gchar **node,
                                                             gchar **domain,
                                                             gchar **resource);

If `jid` is valid, returns `TRUE` and sets the caller's `node`, `domain` and `resource` pointers. `node` and `resource` will be set to `NULL` if the respective part is not present in `jid`. If `jid` is invalid, sets `node`, `domain` and `resource` to `NULL` and returns `FALSE`.

In theory, the returned parts will be normalised as specified in RFC 6122 (XMPP Address Format); in practice, Wocky does not fully implement the normalisation and validation algorithms. FIXME: Do nodeprep/resourceprep and length checking.

`jid` : | a JID
`node` : | address to store the normalised localpart of the JID. [allow-none]
`domain` : | address to store the normalised domainpart of the JID. [allow-none]
`resource` : | address to store the resourcepart of the JID
Returns : | `TRUE` if the JID is valid

### wocky_compose_jid ()

    gchar *             wocky_compose_jid                   (const gchar *node,
                                                             const gchar *domain,
                                                             const gchar *resource);

Composes a JID from its parts. If `node` is empty or `NULL`, the '@' separator is also omitted; if `resource` is empty or `NULL`, the '/' separator is also omitted. `node` and `domain` are assumed to have already been normalised.

`node` : | the node part of a JID, possibly empty or `NULL`. [allow-none]
`domain` : | the non-`NULL` domain part of a JID
`resource` : | the resource part of a JID, possibly empty or `NULL`. [allow-none]
Returns : | a JID constructed from `node`, `domain` and `resource`

### wocky_g_value_slice_new ()

    GValue *            wocky_g_value_slice_new             (GType type);

Slice-allocate an empty GValue. `wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`.

Since 0.5.14

### wocky_g_value_slice_new_boolean ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_int ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_int64 ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_uint ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_uint64 ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_double ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_string ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_static_string ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_take_string ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_boxed ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_static_boxed ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_new_take_boxed ()

    GValue *            wocky_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 `wocky_g_value_slice_free()` or `g_slice_free()`

Since 0.7.27

### wocky_g_value_slice_free ()

    void                wocky_g_value_slice_free            (GValue *value);

Unset and free a slice-allocated GValue.

`(GDestroyNotify) wocky_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

### wocky_g_value_slice_dup ()

    GValue *            wocky_g_value_slice_dup             (const GValue *value);

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

Since 0.5.14

### wocky_enum_from_nick ()

    gboolean            wocky_enum_from_nick                (GType enum_type,
                                                             const gchar *nick,
                                                             gint *value);

`enum_type` : | the GType of a subtype of GEnum
`nick` : | a non-`NULL` string purporting to be the nickname of a value of `enum_type`
`value` : | the address at which to store the value of `enum_type` corresponding to `nick` if this functions returns `TRUE`; if this function returns `FALSE`, this variable will be left untouched.
Returns : | `TRUE` if `nick` is a member of `enum_type`, or `FALSE` otherwise

### wocky_enum_to_nick ()

    const gchar *       wocky_enum_to_nick                  (GType enum_type,
                                                             gint value);

`enum_type` : | the GType of a subtype of GEnum
`value` : | a value of `enum_type`
Returns : | the nickname of `value`, or `NULL` if it is not, in fact, a value of `enum_type`

### wocky_absolutize_path ()

    gchar *             wocky_absolutize_path               (const gchar *path);

Return an absolute form of `path`. This cleans up duplicate slashes, "." or ".." path segments, etc., and prepends `g_get_current_dir()` if necessary, but does not necessarily resolve symlinks.

`path` : | an absolute or relative path
Returns : | an absolute path which must be freed with `g_free()`, or possibly `NULL` for invalid filenames

### wocky_list_deep_copy ()

    GList *             wocky_list_deep_copy                (GBoxedCopyFunc copy,
                                                             GList *items);

### wocky_g_string_dup ()

    GString *           wocky_g_string_dup                  (const GString *str);

### wocky_g_string_free ()

    void                wocky_g_string_free                 (GString *str);

### wocky_implement_finish_void()

    #define             wocky_implement_finish_void(source, tag)

### wocky_implement_finish_copy_pointer()

    #define             wocky_implement_finish_copy_pointer(source, tag, copy_func, \
                    out_param)

### wocky_implement_finish_return_copy_pointer()

    #define             wocky_implement_finish_return_copy_pointer(source, tag, \
                    copy_func)

### wocky_implement_finish_return_pointer()

    #define             wocky_implement_finish_return_pointer(source, tag)