## String Utility Functions

String Utility Functions — Various string-related functions

## Functions

gchar * | exo_str_elide_underscores ()
gboolean | exo_str_is_equal ()
#define | exo_str_is_empty()
gboolean | exo_str_is_flag ()
gboolean | exo_str_looks_like_an_uri ()
gchar * | exo_str_replace ()
gchar * | exo_strdup_strftime ()
gchar ** | exo_strndupv ()
#define | I_()

## Includes

    #include <exo/exo.h>

## Description

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

## Functions

### exo_str_elide_underscores ()

    gchar *
    exo_str_elide_underscores (const gchar *text);

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

#### Parameters

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

#### Parameters

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) ((string) == NULL || *(string) == '\0')

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

#### Parameters

string | a string |

#### Returns

`TRUE` if the string is not `NULL` and its length > 1, `FALSE` otherwise.

Since : 0.5.0

### exo_str_is_flag ()

    gboolean
    exo_str_is_flag (const gchar *str);

Check if `str` looks like a commandline flag. This function simply checks if the string begins with a single dash.

#### Parameters

str | an input string. |

#### Returns

`TRUE` if the `str` looks like a flag, `FALSE` otherwise.

Since: 0.11.5

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

#### Parameters

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.

#### Parameters

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.

Do NOT pass in the value returned by localtime(3) as the parameter `tm` , as this is a pointer to a shared static struct which can be changed by subsequent function calls, including any calls to `g_warning()` made by `exo_strdup_strftime()` itself. Use e.g. localtime_r(3) or make a copy of the struct to pass in instead.

#### Parameters

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

#### Parameters

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) (g_intern_static_string ((string)))

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

#### Parameters

string | A static string. |

#### Returns

a canonical representation for the string.

Since : 0.3.1.1