String Utility Functions

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

## Stability Level

Stable, unless otherwise indicated

## Synopsis

    #include <exo/exo.h>

    gchar *             exo_str_elide_underscores           (const gchar *text);
    gboolean            exo_str_is_equal                    (const gchar *a,
                                                             const gchar *b);
    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,
                                                             gint num);
    const gchar *       exo_intern_string                   (const gchar *string);
    const gchar *       exo_intern_static_string            (const gchar *string);
    #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_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.

`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`.

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,
                                                             gint num);

Creates a new string vector containing the first `n` elements of `strv`.

`strv` : | String vector to duplicate.
`num` : | Number of strings in `strv` to duplicate.
Returns : | The new string vector. Should be freed using `g_strfreev()` when no longer needed.

### exo_intern_string ()

    const gchar *       exo_intern_string                   (const gchar *string);

Returns a canonical representation for `string`. Interned strings can be compared for equality by comparing the pointers, instead of using `strcmp()` or `exo_str_is_equal()`. `exo_intern_string()` takes a copy of the `string` for its internal usage, so `string` does not need to be static.

`string` : | a string
Returns : | a canonical representation for the string

Since 0.3.1.1

### exo_intern_static_string ()

    const gchar *       exo_intern_static_string            (const gchar *string);

Returns a canonical representation for `string`. Interned strings can be compared for equality by comparing the pointers, instead of using `strcmp()` or `exo_str_is_equal()`. `exo_intern_static_string()` does not copy the string, therefore `string` must not be freed or modified.

`string` : | a static string
Returns : | a canonical representation for the string

Since 0.3.1.1

### I_()

    #define             I_(string)

Shortcut for `exo_intern_static_string()`.

`string` : | a static string.

Since 0.3.1.1