GLib Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# String Utility Functions

## Name

String Utility Functions -- various string-related functions.

## Synopsis

    #include <glib.h>

    gchar*      g_strdup                        (const gchar *str);
    gchar*      g_strndup                       (const gchar *str,
                                                 guint n);
    gchar*      g_strnfill                      (guint length,
                                                 gchar fill_char);

    gchar*      g_strdup_printf                 (const gchar *format,
                                                 ...);
    gchar*      g_strdup_vprintf                (const gchar *format,
                                                 va_list args);
    gint        g_snprintf                      (gchar *string,
                                                 gulong n,
                                                 gchar const *format,
                                                 ...);
    gint        g_vsnprintf                     (gchar *string,
                                                 gulong n,
                                                 gchar const *format,
                                                 va_list args);
    guint       g_printf_string_upper_bound     (const gchar *format,
                                                 va_list args);

    void        g_strup                         (gchar *string);
    void        g_strdown                       (gchar *string);

    gint        g_strcasecmp                    (const gchar *s1,
                                                 const gchar *s2);
    gint        g_strncasecmp                   (const gchar *s1,
                                                 const gchar *s2,
                                                 guint n);

    void        g_strreverse                    (gchar *string);
    gdouble     g_strtod                        (const gchar *nptr,
                                                 gchar **endptr);

    gchar*      g_strchug                       (gchar *string);
    gchar*      g_strchomp                      (gchar *string);
    #define     g_strstrip                      ( string )

    gchar*      g_strdelimit                    (gchar *string,
                                                 const gchar *delimiters,
                                                 gchar new_delimiter);
    #define     G_STR_DELIMITERS
    gchar*      g_strescape                     (gchar *string);
    gchar**     g_strsplit                      (const gchar *string,
                                                 const gchar *delimiter,
                                                 gint max_tokens);
    void        g_strfreev                      (gchar **str_array);
    gchar*      g_strconcat                     (const gchar *string1,
                                                 ...);
    gchar*      g_strjoin                       (const gchar *separator,
                                                 ...);
    gchar*      g_strjoinv                      (const gchar *separator,
                                                 gchar **str_array);

    gchar*      g_strerror                      (gint errnum);
    gchar*      g_strsignal                     (gint signum);

## Description

This section describes a number of utility functions for creating, duplicating, and manipulating strings.

## Details

### g_strdup ()

    gchar*      g_strdup                        (const gchar *str);

Duplicates a string. The returned string should be freed when no longer needed.

`str` : | the string to duplicate.
Returns : | a newly-allocated copy of `str`.

### g_strndup ()

    gchar*      g_strndup                       (const gchar *str,
                                                 guint n);

Duplicates the first `n` characters of a string, returning a newly-allocated buffer `n` + 1 characters long which will always be null-terminated. If `str` is less than `n` characters long the buffer is padded with nulls. The returned value should be freed when no longer needed.

`str` : | the string to duplicate part of.
`n` : | the maximum number of characters to copy from `str`.
Returns : | a newly-allocated buffer containing the first `n` characters of `str`, null-terminated.

### g_strnfill ()

    gchar*      g_strnfill                      (guint length,
                                                 gchar fill_char);

Creates a new string `length` characters long filled with `fill_char`. The returned string should be freed when no longer needed.

`length` : | the length of the new string.
`fill_char` : | the character to fill the string with.
Returns : | a newly-allocated string filled the `fill_char`.

### g_strdup_printf ()

    gchar*      g_strdup_printf                 (const gchar *format,
                                                 ...);

Similar to the standard C `sprintf()` function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed.

`format` : | the standard `sprintf()` format string.
`...` : | the parameters to insert into the format string.
Returns : | a newly-allocated string holding the result.

### g_strdup_vprintf ()

    gchar*      g_strdup_vprintf                (const gchar *format,
                                                 va_list args);

Similar to the standard C `vsprintf()` function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed.

`format` : | the standard `sprintf()` format string.
`args` : | the list of parameters to insert into the format string.
Returns : | a newly-allocated string holding the result.

### g_snprintf ()

    gint        g_snprintf                      (gchar *string,
                                                 gulong n,
                                                 gchar const *format,
                                                 ...);

A safer form of the standard `sprintf()` function. The output is guaranteed to not exceed `n` characters (including the terminating NULL character), so it is easy to ensure that a buffer overflow cannot occur.

See also g_strdup_printf().

> Note: In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be NULL-terminated.

`string` : | the buffer to hold the output.
`n` : | the maximum number of characters to produce (including the terminating null character).
`format` : | the format string. See the `sprintf()` documentation.
`...` : | the arguments to insert in the output.
Returns : | the length of the output string.

### g_vsnprintf ()

    gint        g_vsnprintf                     (gchar *string,
                                                 gulong n,
                                                 gchar const *format,
                                                 va_list args);

A safer form of the standard `vsprintf()` function. The output is guaranteed to not exceed `n` characters (including the terminating NULL character), so it is easy to ensure that a buffer overflow cannot occur.

See also g_strdup_vprintf().

> Note: In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be NULL-terminated.

`string` : | the buffer to hold the output.
`n` : | the maximum number of characters to produce (including the terminating null character).
`format` : | the format string. See the `sprintf()` documentation.
`args` : | the list of arguments to insert in the output.
Returns : | the length of the output string.

### g_printf_string_upper_bound ()

    guint       g_printf_string_upper_bound     (const gchar *format,
                                                 va_list args);

Calculates the maximum space needed to store the output of the `sprintf()` function.

`format` : | the format string. See the `printf()` documentation.
`args` : | the parameters to be inserted into the format string.
Returns : | the maximum space needed to store the formatted string.

### g_strup ()

    void        g_strup                         (gchar *string);

Converts a string to upper case.

`string` : | the string to convert.

### g_strdown ()

    void        g_strdown                       (gchar *string);

Converts a string to lower case.

`string` : | the string to convert.

### g_strcasecmp ()

    gint        g_strcasecmp                    (const gchar *s1,
                                                 const gchar *s2);

A case-insensitive string comparison, corresponding to the standard `strcasecmp()` function on platforms which support it.

`s1` : | a string.
`s2` : | a string to compare with `s1`.
Returns : | 0 if the strings match, a negative value if `s1` < `s2`, or a positive value if `s1` > `s2`.

### g_strncasecmp ()

    gint        g_strncasecmp                   (const gchar *s1,
                                                 const gchar *s2,
                                                 guint n);

A case-insensitive string comparison, corresponding to the standard `strncasecmp()` function on platforms which support it. It is similar to g_strcasecmp() except it only compares the first `n` characters of the strings.

`s1` : | a string.
`s2` : | a string to compare with `s1`.
`n` : | the maximum number of characters to compare.
Returns : | 0 if the strings match, a negative value if `s1` < `s2`, or a positive value if `s1` > `s2`.

### g_strreverse ()

    void        g_strreverse                    (gchar *string);

Reverses all of the characters in a string. For example, g_strreverse ("abcdef") would be "fedcba".

`string` : | the string to reverse.

### g_strtod ()

    gdouble     g_strtod                        (const gchar *nptr,
                                                 gchar **endptr);

Converts a string to a gdouble value. It calls the standard `strtod()` function to handle the conversion, but if the string is not completely converted it attempts the conversion again in the "C" locale, and returns the best match.

`nptr` : | the string to convert to a numeric value.
`endptr` : | if non-NULL, it returns the character after the last character used in the conversion.
Returns : | the gdouble value.

### g_strchug ()

    gchar*      g_strchug                       (gchar *string);

Removes leading whitespace from a string, by moving the rest of the characters forward.

`string` : | a string to remove the leading whitespace from.
Returns : | `string`.

### g_strchomp ()

    gchar*      g_strchomp                      (gchar *string);

Removes trailing whitespace from a string.

`string` : | a string to remove the trailing whitespace from.
Returns : | `string`.

### g_strstrip()

    #define     g_strstrip( string )

Removes leading and trailing whitespace from a string.

`string` : | a string to remove the leading and trailing whitespace from.

### g_strdelimit ()

    gchar*      g_strdelimit                    (gchar *string,
                                                 const gchar *delimiters,
                                                 gchar new_delimiter);

Converts any delimiter characters in `string` to `new_delimiter`. Any characters in `string` which are found in `delimiters` are changed to the `new_delimiter` character.

`string` : | the string to convert.
`delimiters` : | a string containing the current delimiters, or NULL to use the standard delimiters defined in G_STR_DELIMITERS.
`new_delimiter` : | the new delimiter character.
Returns : |

### G_STR_DELIMITERS

    #define	 G_STR_DELIMITERS	"_-|> <."

The standard delimiters, used in g_strdelimit.

### g_strescape ()

    gchar*      g_strescape                     (gchar *string);

Escapes all backslash characters, '\' in a string, by inserting a second '\'.

`string` : | a string to escape the backslashes in.
Returns : | a newly allocated copy of `string`, with all backslash characters escaped using a second backslash.

### g_strsplit ()

    gchar**     g_strsplit                      (const gchar *string,
                                                 const gchar *delimiter,
                                                 gint max_tokens);

Splits a string into a maximum of `max_tokens` pieces, using the given `delimiter`. If `max_tokens` is reached, the final string in the returned string array contains the remainder of `string`.

`string` : | a string to split.
`delimiter` : | a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless max_tokens is reached.
`max_tokens` : | the maximum number of strings to split `string` into. If this is less than 1, the string is split completely.
Returns : | a newly-allocated array of strings. Use g_strfreev() to free it.

### g_strfreev ()

    void        g_strfreev                      (gchar **str_array);

Frees a NULL-terminated array of strings, and the array itself.

`str_array` : | a NULL-terminated array of strings to free.

### g_strconcat ()

    gchar*      g_strconcat                     (const gchar *string1,
                                                 ...);

Concatenates all of the given strings into one long string. The returned string should be freed when no longer needed.

`string1` : | The first string to add, which must not be NULL.
`...` : | a NULL-terminated list of strings to append to the string.
Returns : | a newly-allocated string containing all the string arguments.

### g_strjoin ()

    gchar*      g_strjoin                       (const gchar *separator,
                                                 ...);

Joins a number of strings together to form one long string, with the optional `separator` inserted between each of them.

`separator` : | a string to insert between each of the strings, or NULL.
`...` : | a NULL-terminated list of strings to join.
Returns : | a newly-allocated string containing all of the strings joined together, with `separator` between them.

### g_strjoinv ()

    gchar*      g_strjoinv                      (const gchar *separator,
                                                 gchar **str_array);

Joins a number of strings together to form one long string, with the optional `separator` inserted between each of them.

`separator` : | a string to insert between each of the strings, or NULL.
`str_array` : | a NULL-terminated array of strings to join.
Returns : | a newly-allocated string containing all of the strings joined together, with `separator` between them.

### g_strerror ()

    gchar*      g_strerror                      (gint errnum);

Returns a string corresponding to the given error code, e.g. "no such process". This function is included since not all platforms support the `strerror()` function.

`errnum` : | the system error number. See the standard C `errno` documentation.
Returns : | a string describing the error code. If the error code is unknown, it returns "unknown error (<code>)". The string can only be used until the next call to g_strerror.

### g_strsignal ()

    gchar*      g_strsignal                     (gint signum);

Returns a string describing the given signal, e.g. "Segmentation fault". This function is included since not all platforms support the `strsignal()` function.

`signum` : | the signal number. See the `signal` documentation.
Returns : | a string describing the signal. If the signal is unknown, it returns "unknown signal (<signum>)". The string can only be used until the next call to g_strsignal.

<<< Previous Page | Home | Up | Next Page >>>
GLib Utilities | Date and Time Functions