String Utility Functions
3
EXO Library

# 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