String Utility Functions

## String Utility Functions String Utility Functions — Various string-related functions |

## Synopsis

    #include <exo/exo.h>

    gchar *             exo_str_elide_underscores           (const gchar *text);
    gboolean            exo_str_is_equal                    (const gchar *a,
                                                             const gchar *b);
    #define             exo_str_is_empty                    (string)
    gboolean            exo_str_looks_like_an_uri           (const gchar *str);
    gchar *             exo_str_replace                     (const gchar *str,
                                                             const gchar *pattern,
                                                             const gchar *replacement);
    gchar *             exo_strdup_strftime                 (const gchar *format,
                                                             const struct tm *tm);
    gchar **            exo_strndupv                        (gchar **strv,
                                                             guint num);
    #define             I_                                  (string)

## Description

This section describes a number of utility functions for manipulating strings.

## Details

### exo_str_elide_underscores ()

    gchar *             exo_str_elide_underscores           (const gchar *text);

Returns a copy of `text` with all mnemonic underscores stripped off.

`text` : | A zero terminated string.
Returns : | A copy of `text` without underscores. The returned string must be freed when no longer required.

### exo_str_is_equal ()

    gboolean            exo_str_is_equal                    (const gchar *a,
                                                             const gchar *b);

`NULL`-safe string comparison. Returns `TRUE` if both `a` and `b` are `NULL` or if `a` and `b` refer to valid strings which are equal.

You should always prefer this function over `strcmp()`.

`a` : | A pointer to first string or `NULL`.
`b` : | A pointer to second string or `NULL`.
Returns : | `TRUE` if `a` equals `b`, else `FALSE`.

### exo_str_is_empty()

    #define             exo_str_is_empty(string)

Macro to check if a string is `NULL` or empty. You should prefer this function over strlen (str) == 0.

`string` : | a string
Returns : | `TRUE` if the string is not `NULL` and its length > 1, `FALSE` otherwise. Since : 0.5.0

### exo_str_looks_like_an_uri ()

    gboolean            exo_str_looks_like_an_uri           (const gchar *str);

Check if `str` looks like an uri. This function is no guarantee that the uri exists, or is supported by the system.

`str` : | an input string.
Returns : | `TRUE` if the `str` looks like an URI according to RFC 2396, `FALSE` otherwise.

Since 0.5.0

### exo_str_replace ()

    gchar *             exo_str_replace                     (const gchar *str,
                                                             const gchar *pattern,
                                                             const gchar *replacement);

Searches `str` for occurances of `pattern` and replaces each such occurance with `replacement`. Returns a newly allocated copy of `str` on which the given replacement were performed. The caller is responsible to free the returned string using `g_free()` when no longer needed.

Note that `pattern` and `replacement` don't need to be of the same size. If `replacement` is `NULL`, the pattern will be removed from the string.

`str` : | the input string.
`pattern` : | a search pattern in `str`.
`replacement` : | replacement string for `pattern`.
Returns : | a newly allocated copy of `str` where all occurances of `pattern` are replaced with `replacement`. Or `NULL` if `str` and/or `pattern` is `NULL`.

Since 0.3.1.1

### exo_strdup_strftime ()

    gchar *             exo_strdup_strftime                 (const gchar *format,
                                                             const struct tm *tm);

Cover for standard date-and-time-formatting routine strftime that returns a newly-allocated string of the correct size. The caller is responsible to free the returned string using `g_free()` when no longer needed.

Besides the buffer management, there are two differences between this and the library strftime:

The modifiers "-" and "_" between a "%" and a numeric directive are defined as for the GNU version of strftime. "-" means "do not pad the field" and "_" means "pad with spaces instead of zeroes".

Non-ANSI extensions to strftime are flagged at runtime with a warning, so it's easy to notice use of the extensions without testing with multiple versions of the library.

`format` : | format string to pass to strftime(3). See the strftime(3) documentation for details.
`tm` : | date/time, in struct tm format.
Returns : | a newly allocated string containing the formatted date/time.

Since 0.3.3

### exo_strndupv ()

    gchar **            exo_strndupv                        (gchar **strv,
                                                             guint num);

Creates a new string vector containing the first `n` elements of `strv`. If called on a `NULL` value or `num` is 0, `exo_strndupv()` simply returns `NULL`.

`strv` : | String vector to duplicate.
`num` : | Number of strings in `strv` to duplicate.
Returns : | A new NULL-terminated array of strings or `NULL`. Should be freed using `g_strfreev()` when no longer needed.

### I_()

    #define             I_(string)

Shortcut for `g_intern_static_string()` to return a canonical representation for `string`.

`string` : | A static string.
Returns : | a canonical representation for the string. Since : 0.3.1.1