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