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,
                                                             const 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 the JID is valid, returns TRUE and sets the caller's node/domain/resource pointers if they are not NULL. The node and resource pointers will be set to NULL if the respective part is not present in the JID. The node and domain are lower-cased because the Jabber protocol treats them case-insensitively.

XXX: Do nodeprep/resourceprep and length checking.

See RFC 3920 §3.

`jid` : | a JID
`node` : | address to which return the username/room part of the JID
`domain` : | address to which return the server/service part of the JID
`resource` : | address to which return the resource/nick part 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` : | the node part of a JID, possibly empty or `NULL`
`domain` : | the non-`NULL` domain part of a JID
`resource` : | the resource part of a JID, possibly empty or `NULL`
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,
                                                             const GList *items);

`copy` : |
`items` : |
Returns : |

### wocky_g_string_dup ()

    GString *           wocky_g_string_dup                  (const GString *str);

`str` : |
Returns : |

### wocky_g_string_free ()

    void                wocky_g_string_free                 (GString *str);

`str` : |

### wocky_implement_finish_void()

    #define             wocky_implement_finish_void(source, tag)

`source` : |
`tag` : |

### wocky_implement_finish_copy_pointer()

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

`source` : |
`tag` : |
`copy_func` : |
`out_param` : |

### wocky_implement_finish_return_copy_pointer()

    #define             wocky_implement_finish_return_copy_pointer(source, tag, \
                    copy_func)

`source` : |
`tag` : |
`copy_func` : |

### wocky_implement_finish_return_pointer()

    #define             wocky_implement_finish_return_pointer(source, tag)

`source` : |
`tag` : |