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