## String Utility Functions

String Utility Functions — various string-related functions

## Functions

gchar * | g_strdup ()
gchar * | g_strndup ()
gchar ** | g_strdupv ()
gchar * | g_strnfill ()
gchar * | g_stpcpy ()
gchar * | g_strstr_len ()
gchar * | g_strrstr ()
gchar * | g_strrstr_len ()
gboolean | g_str_has_prefix ()
gboolean | g_str_has_suffix ()
int | g_strcmp0 ()
gchar * | g_str_to_ascii ()
gchar ** | g_str_tokenize_and_fold ()
gboolean | g_str_match_string ()
gsize | g_strlcpy ()
gsize | g_strlcat ()
gchar * | g_strdup_printf ()
gchar * | g_strdup_vprintf ()
gint | g_printf ()
gint | g_vprintf ()
gint | g_fprintf ()
gint | g_vfprintf ()
gint | g_sprintf ()
gint | g_vsprintf ()
gint | g_snprintf ()
gint | g_vsnprintf ()
gint | g_vasprintf ()
gsize | g_printf_string_upper_bound ()
gboolean | g_str_is_ascii ()
gboolean | g_ascii_isalnum ()
gboolean | g_ascii_isalpha ()
gboolean | g_ascii_iscntrl ()
gboolean | g_ascii_isdigit ()
gboolean | g_ascii_isgraph ()
gboolean | g_ascii_islower ()
gboolean | g_ascii_isprint ()
gboolean | g_ascii_ispunct ()
gboolean | g_ascii_isspace ()
gboolean | g_ascii_isupper ()
gboolean | g_ascii_isxdigit ()
gint | g_ascii_digit_value ()
gint | g_ascii_xdigit_value ()
gint | g_ascii_strcasecmp ()
gint | g_ascii_strncasecmp ()
gchar * | g_ascii_strup ()
gchar * | g_ascii_strdown ()
gchar | g_ascii_tolower ()
gchar | g_ascii_toupper ()
GString * | g_string_ascii_up ()
GString * | g_string_ascii_down ()
gchar * | g_strup ()
gchar * | g_strdown ()
gint | g_strcasecmp ()
gint | g_strncasecmp ()
gchar * | g_strreverse ()
gint64 | g_ascii_strtoll ()
guint64 | g_ascii_strtoull ()
gdouble | g_ascii_strtod ()
gchar * | g_ascii_dtostr ()
gchar * | g_ascii_formatd ()
gdouble | g_strtod ()
gboolean | g_ascii_string_to_signed ()
gboolean | g_ascii_string_to_unsigned ()
gchar * | g_strchug ()
gchar * | g_strchomp ()
#define | g_strstrip()
gchar * | g_strdelimit ()
gchar * | g_strescape ()
gchar * | g_strcompress ()
gchar * | g_strcanon ()
gchar ** | g_strsplit ()
gchar ** | g_strsplit_set ()
void | g_strfreev ()
gchar * | g_strconcat ()
gchar * | g_strjoin ()
gchar * | g_strjoinv ()
guint | g_strv_length ()
gboolean | g_strv_contains ()
gboolean | g_strv_equal ()
const gchar * | g_strerror ()
const gchar * | g_strsignal ()

## Types and Values

#define | G_ASCII_DTOSTR_BUF_SIZE
enum | GNumberParserError
#define | G_NUMBER_PARSER_ERROR
#define | G_STR_DELIMITERS
typedef | GStrv

## Includes

    #include <glib.h>
    #include <glib/gprintf.h>

## Description

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

Note that the functions `g_printf()`, `g_fprintf()`, `g_sprintf()`, `g_vprintf()`, `g_vfprintf()`, `g_vsprintf()` and `g_vasprintf()` are declared in the header `gprintf.h` which is not included in `glib.h` (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to explicitly include `<glib/gprintf.h>` in order to use the GLib `printf()` functions.

#### String precision pitfalls

While you may use the `printf()` functions to format UTF-8 strings, notice that the precision of a %Ns parameter is interpreted as the number of bytes, not characters to print. On top of that, the GNU libc implementation of the `printf()` functions has the "feature" that it checks that the string given for the %Ns parameter consists of a whole number of characters in the current encoding. So, unless you are sure you are always going to be in an UTF-8 locale or your know your text is restricted to ASCII, avoid using %Ns. If your intention is to format strings for a certain number of columns, then %Ns is not a correct solution anyway, since it fails to take wide characters (see `g_unichar_iswide()`) into account.

Note also that there are various `printf()` parameters which are platform dependent. GLib provides platform independent macros for these parameters which should be used instead. A common example is `G_GUINT64_FORMAT`, which should be used instead of `%llu` or similar parameters for formatting 64-bit integers. These macros are all named `G_*_FORMAT`; see Basic Types.

## Functions

### g_strdup ()

    gchar *
    g_strdup (const gchar *str);

Duplicates a string. If `str` is `NULL` it returns `NULL`. The returned string should be freed with `g_free()` when no longer needed.

#### Parameters

str | the string to duplicate. | [nullable]

#### Returns

a newly-allocated copy of `str`

### g_strndup ()

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

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

To copy a number of characters from a UTF-8 encoded string, use `g_utf8_strncpy()` instead.

#### Parameters

str | the string to duplicate |
n | the maximum number of bytes to copy from `str` |

#### Returns

a newly-allocated buffer containing the first `n` bytes of `str` , nul-terminated

### g_strdupv ()

    gchar **
    g_strdupv (gchar **str_array);

Copies `NULL`-terminated array of strings. The copy is a deep copy; the new array should be freed by first freeing each string, then the array itself. `g_strfreev()` does this for you. If called on a `NULL` value, `g_strdupv()` simply returns `NULL`.

#### Parameters

str_array | a `NULL`-terminated array of strings. | [nullable]

#### Returns

a new `NULL`-terminated array of strings.

[nullable]

### g_strnfill ()

    gchar *
    g_strnfill (gsize length,
                gchar fill_char);

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

#### Parameters

length | the length of the new string |
fill_char | the byte to fill the string with |

#### Returns

a newly-allocated string filled the `fill_char`

### g_stpcpy ()

    gchar *
    g_stpcpy (gchar *dest,
              const char *src);

Copies a nul-terminated string into the dest buffer, include the trailing nul, and return a pointer to the trailing nul byte. This is useful for concatenating multiple strings together without having to repeatedly scan for the end.

#### Parameters

dest | destination buffer. |
src | source string. |

#### Returns

a pointer to trailing nul byte.

### g_strstr_len ()

    gchar *
    g_strstr_len (const gchar *haystack,
                  gssize haystack_len,
                  const gchar *needle);

Searches the string `haystack` for the first occurrence of the string `needle` , limiting the length of the search to `haystack_len` .

#### Parameters

haystack | a string |
haystack_len | the maximum length of `haystack` . Note that -1 is a valid length, if `haystack` is nul-terminated, meaning it will search through the whole string. |
needle | the string to search for |

#### Returns

a pointer to the found occurrence, or `NULL` if not found.

### g_strrstr ()

    gchar *
    g_strrstr (const gchar *haystack,
               const gchar *needle);

Searches the string `haystack` for the last occurrence of the string `needle` .

#### Parameters

haystack | a nul-terminated string |
needle | the nul-terminated string to search for |

#### Returns

a pointer to the found occurrence, or `NULL` if not found.

### g_strrstr_len ()

    gchar *
    g_strrstr_len (const gchar *haystack,
                   gssize haystack_len,
                   const gchar *needle);

Searches the string `haystack` for the last occurrence of the string `needle` , limiting the length of the search to `haystack_len` .

#### Parameters

haystack | a nul-terminated string |
haystack_len | the maximum length of `haystack` |
needle | the nul-terminated string to search for |

#### Returns

a pointer to the found occurrence, or `NULL` if not found.

### g_str_has_prefix ()

    gboolean
    g_str_has_prefix (const gchar *str,
                      const gchar *prefix);

Looks whether the string `str` begins with `prefix` .

#### Parameters

str | a nul-terminated string |
prefix | the nul-terminated prefix to look for |

#### Returns

`TRUE` if `str` begins with `prefix` , `FALSE` otherwise.

Since: 2.2

### g_str_has_suffix ()

    gboolean
    g_str_has_suffix (const gchar *str,
                      const gchar *suffix);

Looks whether the string `str` ends with `suffix` .

#### Parameters

str | a nul-terminated string |
suffix | the nul-terminated suffix to look for |

#### Returns

`TRUE` if `str` end with `suffix` , `FALSE` otherwise.

Since: 2.2

### g_strcmp0 ()

    int
    g_strcmp0 (const char *str1,
               const char *str2);

Compares `str1` and `str2` like `strcmp()`. Handles `NULL` gracefully by sorting it before non-`NULL` strings. Comparing two `NULL` pointers returns 0.

#### Parameters

str1 | a C string or `NULL`. | [nullable]
str2 | another C string or `NULL`. | [nullable]

#### Returns

an integer less than, equal to, or greater than zero, if `str1` is <, == or > than `str2` .

Since: 2.16

### g_str_to_ascii ()

    gchar *
    g_str_to_ascii (const gchar *str,
                    const gchar *from_locale);

Transliterate `str` to plain ASCII.

For best results, `str` should be in composed normalised form.

This function performs a reasonably good set of character replacements. The particular set of replacements that is done may change by version or even by runtime environment.

If the source language of `str` is known, it can used to improve the accuracy of the translation by passing it as `from_locale` . It should be a valid POSIX locale string (of the form `language[_territory][.codeset][@modifier]`).

If `from_locale` is `NULL` then the current locale is used.

If you want to do translation for no specific locale, and you want it to be done independently of the currently locale, specify `"C"` for `from_locale` .

#### Parameters

str | a string, in UTF-8 |
from_locale | the source locale, if known. | [nullable]

#### Returns

a string in plain ASCII

Since: 2.40

### g_str_tokenize_and_fold ()

    gchar **
    g_str_tokenize_and_fold (const gchar *string,
                             const gchar *translit_locale,
                             gchar ***ascii_alternates);

Tokenises `string` and performs folding on each token.

A token is a non-empty sequence of alphanumeric characters in the source string, separated by non-alphanumeric characters. An "alphanumeric" character for this purpose is one that matches `g_unichar_isalnum()` or `g_unichar_ismark()`.

Each token is then (Unicode) normalised and case-folded. If `ascii_alternates` is non-`NULL` and some of the returned tokens contain non-ASCII characters, ASCII alternatives will be generated.

The number of ASCII alternatives that are generated and the method for doing so is unspecified, but `translit_locale` (if specified) may improve the transliteration if the language of the source string is known.

#### Parameters

string | a string |
translit_locale | the language code (like 'de' or 'en_GB') from which `string` originates. | [nullable]
ascii_alternates | a return location for ASCII alternates. | [out][transfer full][array zero-terminated=1]

#### Returns

the folded tokens.

[transfer full][array zero-terminated=1]

Since: 2.40

### g_str_match_string ()

    gboolean
    g_str_match_string (const gchar *search_term,
                        const gchar *potential_hit,
                        gboolean accept_alternates);

Checks if a search conducted for `search_term` should match `potential_hit` .

This function calls `g_str_tokenize_and_fold()` on both `search_term` and `potential_hit` . ASCII alternates are never taken for `search_term` but will be taken for `potential_hit` according to the value of `accept_alternates` .

A hit occurs when each folded token in `search_term` is a prefix of a folded token from `potential_hit` .

Depending on how you're performing the search, it will typically be faster to call `g_str_tokenize_and_fold()` on each string in your corpus and build an index on the returned folded tokens, then call `g_str_tokenize_and_fold()` on the search term and perform lookups into that index.

As some examples, searching for ‘fred’ would match the potential hit ‘Smith, Fred’ and also ‘Frédéric’. Searching for ‘Fréd’ would match ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of accent matching). Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).

#### Parameters

search_term | the search term from the user |
potential_hit | the text that may be a hit |
accept_alternates | `TRUE` to accept ASCII alternates |

#### Returns

`TRUE` if `potential_hit` is a hit

Since: 2.40

### g_strlcpy ()

    gsize
    g_strlcpy (gchar *dest,
               const gchar *src,
               gsize dest_size);

Portability wrapper that calls `strlcpy()` on systems which have it, and emulates `strlcpy()` otherwise. Copies `src` to `dest` ; `dest` is guaranteed to be nul-terminated; `src` must be nul-terminated; `dest_size` is the buffer size, not the number of bytes to copy.

At most `dest_size` - 1 characters will be copied. Always nul-terminates (unless `dest_size` is 0). This function does not allocate memory. Unlike `strncpy()`, this function doesn't pad `dest` (so it's often faster). It returns the size of the attempted result, strlen (src), so if `retval` >= `dest_size` , truncation occurred.

Caveat: `strlcpy()` is supposedly more secure than `strcpy()` or `strncpy()`, but if you really want to avoid screwups, `g_strdup()` is an even better idea.

#### Parameters

dest | destination buffer |
src | source buffer |
dest_size | length of `dest` in bytes |

#### Returns

length of `src`

### g_strlcat ()

    gsize
    g_strlcat (gchar *dest,
               const gchar *src,
               gsize dest_size);

Portability wrapper that calls `strlcat()` on systems which have it, and emulates it otherwise. Appends nul-terminated `src` string to `dest` , guaranteeing nul-termination for `dest` . The total size of `dest` won't exceed `dest_size` .

At most `dest_size` - 1 characters will be copied. Unlike `strncat()`, `dest_size` is the full size of dest, not the space left over. This function does not allocate memory. It always nul-terminates (unless `dest_size` == 0 or there were no nul characters in the `dest_size` characters of dest to start with).

Caveat: this is supposedly a more secure alternative to `strcat()` or `strncat()`, but for real security `g_strconcat()` is harder to mess up.

#### Parameters

dest | destination buffer, already containing one nul-terminated string |
src | source buffer |
dest_size | length of `dest` buffer in bytes (not length of existing string inside `dest` ) |

#### Returns

size of attempted result, which is MIN (dest_size, strlen (original dest)) + strlen (src), so if retval >= dest_size, truncation occurred.

### 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 with `g_free()` when no longer needed.

The returned string is guaranteed to be non-NULL, unless `format` contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character.

#### Parameters

format | a standard `printf()` format string, but notice string precision pitfalls. | [not nullable]
... | 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 with `g_free()` when no longer needed.

The returned string is guaranteed to be non-NULL, unless `format` contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character.

See also `g_vasprintf()`, which offers the same functionality, but additionally returns the length of the allocated string.

#### Parameters

format | a standard `printf()` format string, but notice string precision pitfalls. | [not nullable]
args | the list of parameters to insert into the format string |

#### Returns

a newly-allocated string holding the result

### g_printf ()

    gint
    g_printf (gchar const *format,
              ...);

An implementation of the standard `printf()` function which supports positional parameters, as specified in the Single Unix Specification.

As with the standard `printf()`, this does not automatically append a trailing new-line character to the message, so typically `format` should end with its own new-line character.

`glib/gprintf.h` must be explicitly included in order to use this function.

#### Parameters

format | a standard `printf()` format string, but notice string precision pitfalls |
... | the arguments to insert in the output. |

#### Returns

the number of bytes printed.

Since: 2.2

### g_vprintf ()

    gint
    g_vprintf (gchar const *format,
               va_list args);

An implementation of the standard `vprintf()` function which supports positional parameters, as specified in the Single Unix Specification.

`glib/gprintf.h` must be explicitly included in order to use this function.

#### Parameters

format | a standard `printf()` format string, but notice string precision pitfalls |
args | the list of arguments to insert in the output. |

#### Returns

the number of bytes printed.

Since: 2.2

### g_fprintf ()

    gint
    g_fprintf (FILE *file,
               gchar const *format,
               ...);

An implementation of the standard `fprintf()` function which supports positional parameters, as specified in the Single Unix Specification.

`glib/gprintf.h` must be explicitly included in order to use this function.

#### Parameters

file | the stream to write to. | [not nullable]
format | a standard `printf()` format string, but notice string precision pitfalls |
... | the arguments to insert in the output. |

#### Returns

the number of bytes printed.

Since: 2.2

### g_vfprintf ()

    gint
    g_vfprintf (FILE *file,
                gchar const *format,
                va_list args);

An implementation of the standard `fprintf()` function which supports positional parameters, as specified in the Single Unix Specification.

`glib/gprintf.h` must be explicitly included in order to use this function.

#### Parameters

file | the stream to write to. | [not nullable]
format | a standard `printf()` format string, but notice string precision pitfalls |
args | the list of arguments to insert in the output. |

#### Returns

the number of bytes printed.

Since: 2.2

### g_sprintf ()

    gint
    g_sprintf (gchar *string,
               gchar const *format,
               ...);

An implementation of the standard `sprintf()` function which supports positional parameters, as specified in the Single Unix Specification.

Note that it is usually better to use `g_snprintf()`, to avoid the risk of buffer overflow.

`glib/gprintf.h` must be explicitly included in order to use this function.

See also `g_strdup_printf()`.

#### Parameters

string | A pointer to a memory buffer to contain the resulting string. It is up to the caller to ensure that the allocated buffer is large enough to hold the formatted result |
format | a standard `printf()` format string, but notice string precision pitfalls |
... | the arguments to insert in the output. |

#### Returns

the number of bytes printed.

Since: 2.2

### g_vsprintf ()

    gint
    g_vsprintf (gchar *string,
                gchar const *format,
                va_list args);

An implementation of the standard `vsprintf()` function which supports positional parameters, as specified in the Single Unix Specification.

`glib/gprintf.h` must be explicitly included in order to use this function.

#### Parameters

string | the buffer to hold the output. |
format | a standard `printf()` format string, but notice string precision pitfalls |
args | the list of arguments to insert in the output. |

#### Returns

the number of bytes printed.

Since: 2.2

### 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 nul character), so it is easy to ensure that a buffer overflow cannot occur.

See also `g_strdup_printf()`.

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 nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string.

The return value of `g_snprintf()` conforms to the `snprintf()` function as standardized in ISO C99. Note that this is different from traditional `snprintf()`, which returns the length of the output string.

The format string may contain positional parameters, as specified in the Single Unix Specification.

#### Parameters

string | the buffer to hold the output. |
n | the maximum number of bytes to produce (including the terminating nul character). |
format | a standard `printf()` format string, but notice string precision pitfalls |
... | the arguments to insert in the output. |

#### Returns

the number of bytes which would be produced if the buffer was large enough.

### 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 nul character), so it is easy to ensure that a buffer overflow cannot occur.

See also `g_strdup_vprintf()`.

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 nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string.

The return value of `g_vsnprintf()` conforms to the `vsnprintf()` function as standardized in ISO C99. Note that this is different from traditional `vsnprintf()`, which returns the length of the output string.

The format string may contain positional parameters, as specified in the Single Unix Specification.

#### Parameters

string | the buffer to hold the output. |
n | the maximum number of bytes to produce (including the terminating nul character). |
format | a standard `printf()` format string, but notice string precision pitfalls][string-precision] |
args | the list of arguments to insert in the output. |

#### Returns

the number of bytes which would be produced if the buffer was large enough.

### g_vasprintf ()

    gint
    g_vasprintf (gchar **string,
                 gchar const *format,
                 va_list args);

An implementation of the GNU `vasprintf()` function which supports positional parameters, as specified in the Single Unix Specification. This function is similar to `g_vsprintf()`, except that it allocates a string to hold the output, instead of putting the output in a buffer you allocate in advance.

The returned value in `string` is guaranteed to be non-NULL, unless `format` contains `%lc` or `%ls` conversions, which can fail if no multibyte representation is available for the given character.

`glib/gprintf.h` must be explicitly included in order to use this function.

#### Parameters

string | the return location for the newly-allocated string. | [not optional][nullable]
format | a standard `printf()` format string, but notice string precision pitfalls. | [not nullable]
args | the list of arguments to insert in the output. |

#### Returns

the number of bytes printed.

Since: 2.4

### g_printf_string_upper_bound ()

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

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

#### Parameters

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_str_is_ascii ()

    gboolean
    g_str_is_ascii (const gchar *str);

Determines if a string is pure ASCII. A string is pure ASCII if it contains no bytes with the high bit set.

#### Parameters

str | a string |

#### Returns

`TRUE` if `str` is ASCII

Since: 2.40

### g_ascii_isalnum ()

    gboolean
    g_ascii_isalnum (gchar c);

Determines whether a character is alphanumeric.

Unlike the standard C library `isalnum()` function, this only recognizes standard ASCII letters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII alphanumeric character

### g_ascii_isalpha ()

    gboolean
    g_ascii_isalpha (gchar c);

Determines whether a character is alphabetic (i.e. a letter).

Unlike the standard C library `isalpha()` function, this only recognizes standard ASCII letters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII alphabetic character

### g_ascii_iscntrl ()

    gboolean
    g_ascii_iscntrl (gchar c);

Determines whether a character is a control character.

Unlike the standard C library `iscntrl()` function, this only recognizes standard ASCII control characters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII control character.

### g_ascii_isdigit ()

    gboolean
    g_ascii_isdigit (gchar c);

Determines whether a character is digit (0-9).

Unlike the standard C library `isdigit()` function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII digit.

### g_ascii_isgraph ()

    gboolean
    g_ascii_isgraph (gchar c);

Determines whether a character is a printing character and not a space.

Unlike the standard C library `isgraph()` function, this only recognizes standard ASCII characters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII printing character other than space.

### g_ascii_islower ()

    gboolean
    g_ascii_islower (gchar c);

Determines whether a character is an ASCII lower case letter.

Unlike the standard C library `islower()` function, this only recognizes standard ASCII letters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to worry about casting to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII lower case letter

### g_ascii_isprint ()

    gboolean
    g_ascii_isprint (gchar c);

Determines whether a character is a printing character.

Unlike the standard C library `isprint()` function, this only recognizes standard ASCII characters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII printing character.

### g_ascii_ispunct ()

    gboolean
    g_ascii_ispunct (gchar c);

Determines whether a character is a punctuation character.

Unlike the standard C library `ispunct()` function, this only recognizes standard ASCII letters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII punctuation character.

### g_ascii_isspace ()

    gboolean
    g_ascii_isspace (gchar c);

Determines whether a character is a white-space character.

Unlike the standard C library `isspace()` function, this only recognizes standard ASCII white-space and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII white-space character

### g_ascii_isupper ()

    gboolean
    g_ascii_isupper (gchar c);

Determines whether a character is an ASCII upper case letter.

Unlike the standard C library `isupper()` function, this only recognizes standard ASCII letters and ignores the locale, returning `FALSE` for all non-ASCII characters. Also, unlike the standard library function, this takes a char, not an int, so don't call it on `EOF`, but no need to worry about casting to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII upper case letter

### g_ascii_isxdigit ()

    gboolean
    g_ascii_isxdigit (gchar c);

Determines whether a character is a hexadecimal-digit character.

Unlike the standard C library `isxdigit()` function, this takes a char, not an int, so don't call it on `EOF`, but no need to cast to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

`TRUE` if `c` is an ASCII hexadecimal-digit character.

### g_ascii_digit_value ()

    gint
    g_ascii_digit_value (gchar c);

Determines the numeric value of a character as a decimal digit. Differs from `g_unichar_digit_value()` because it takes a char, so there's no worry about sign extension if characters are signed.

#### Parameters

c | an ASCII character |

#### Returns

If `c` is a decimal digit (according to `g_ascii_isdigit()`), its numeric value. Otherwise, -1.

### g_ascii_xdigit_value ()

    gint
    g_ascii_xdigit_value (gchar c);

Determines the numeric value of a character as a hexidecimal digit. Differs from `g_unichar_xdigit_value()` because it takes a char, so there's no worry about sign extension if characters are signed.

#### Parameters

c | an ASCII character. |

#### Returns

If `c` is a hex digit (according to `g_ascii_isxdigit()`), its numeric value. Otherwise, -1.

### g_ascii_strcasecmp ()

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

Compare two strings, ignoring the case of ASCII characters.

Unlike the BSD `strcasecmp()` function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII bytes as if they are not letters.

This function should be used only on strings that are known to be in encodings where the bytes corresponding to ASCII letters always represent themselves. This includes UTF-8 and the ISO-8859-* charsets, but not for instance double-byte encodings like the Windows Codepage 932, where the trailing bytes of double-byte characters include all ASCII letters. If you compare two CP932 strings using this function, you will get false matches.

Both `s1` and `s2` must be non-`NULL`.

#### Parameters

s1 | string to compare with `s2` |
s2 | 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_ascii_strncasecmp ()

    gint
    g_ascii_strncasecmp (const gchar *s1,
                         const gchar *s2,
                         gsize n);

Compare `s1` and `s2` , ignoring the case of ASCII characters and any characters after the first `n` in each string.

Unlike the BSD `strcasecmp()` function, this only recognizes standard ASCII letters and ignores the locale, treating all non-ASCII characters as if they are not letters.

The same warning as in `g_ascii_strcasecmp()` applies: Use this function only on strings known to be in encodings where bytes corresponding to ASCII letters always represent themselves.

#### Parameters

s1 | string to compare with `s2` |
s2 | string to compare with `s1` |
n | 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_ascii_strup ()

    gchar *
    g_ascii_strup (const gchar *str,
                   gssize len);

Converts all lower case ASCII letters to upper case ASCII letters.

#### Parameters

str | a string |
len | length of `str` in bytes, or -1 if `str` is nul-terminated |

#### Returns

a newly allocated string, with all the lower case characters in `str` converted to upper case, with semantics that exactly match `g_ascii_toupper()`. (Note that this is unlike the old `g_strup()`, which modified the string in place.)

### g_ascii_strdown ()

    gchar *
    g_ascii_strdown (const gchar *str,
                     gssize len);

Converts all upper case ASCII letters to lower case ASCII letters.

#### Parameters

str | a string |
len | length of `str` in bytes, or -1 if `str` is nul-terminated |

#### Returns

a newly-allocated string, with all the upper case characters in `str` converted to lower case, with semantics that exactly match `g_ascii_tolower()`. (Note that this is unlike the old `g_strdown()`, which modified the string in place.)

### g_ascii_tolower ()

    gchar
    g_ascii_tolower (gchar c);

Convert a character to ASCII lower case.

Unlike the standard C library `tolower()` function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are lower case letters in a particular character set. Also unlike the standard library function, this takes and returns a char, not an int, so don't call it on `EOF` but no need to worry about casting to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

the result of converting `c` to lower case. If `c` is not an ASCII upper case letter, `c` is returned unchanged.

### g_ascii_toupper ()

    gchar
    g_ascii_toupper (gchar c);

Convert a character to ASCII upper case.

Unlike the standard C library `toupper()` function, this only recognizes standard ASCII letters and ignores the locale, returning all non-ASCII characters unchanged, even if they are upper case letters in a particular character set. Also unlike the standard library function, this takes and returns a char, not an int, so don't call it on `EOF` but no need to worry about casting to guchar before passing a possibly non-ASCII character in.

#### Parameters

c | any character |

#### Returns

the result of converting `c` to upper case. If `c` is not an ASCII lower case letter, `c` is returned unchanged.

### g_string_ascii_up ()

    GString *
    g_string_ascii_up (GString *string);

Converts all lowercase ASCII letters to uppercase ASCII letters.

#### Parameters

string | a GString |

#### Returns

passed-in `string` pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match `g_ascii_toupper()`.

[transfer none]

### g_string_ascii_down ()

    GString *
    g_string_ascii_down (GString *string);

Converts all uppercase ASCII letters to lowercase ASCII letters.

#### Parameters

string | a GString |

#### Returns

passed-in `string` pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match `g_ascii_tolower()`.

[transfer none]

### g_strup ()

    gchar *
    g_strup (gchar *string);

`g_strup` has been deprecated since version 2.2 and should not be used in newly-written code.

This function is totally broken for the reasons discussed in the `g_strncasecmp()` docs - use `g_ascii_strup()` or `g_utf8_strup()` instead.

Converts a string to upper case.

#### Parameters

string | the string to convert |

#### Returns

the string

### g_strdown ()

    gchar *
    g_strdown (gchar *string);

`g_strdown` has been deprecated since version 2.2 and should not be used in newly-written code.

This function is totally broken for the reasons discussed in the `g_strncasecmp()` docs - use `g_ascii_strdown()` or `g_utf8_strdown()` instead.

Converts a string to lower case.

#### Parameters

string | the string to convert. |

#### Returns

the string

### g_strcasecmp ()

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

`g_strcasecmp` has been deprecated since version 2.2 and should not be used in newly-written code.

See `g_strncasecmp()` for a discussion of why this function is deprecated and how to replace it.

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

#### Parameters

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);

`g_strncasecmp` has been deprecated since version 2.2 and should not be used in newly-written code.

The problem with `g_strncasecmp()` is that it does the comparison by calling `toupper()`/`tolower()`. These functions are locale-specific and operate on single bytes. However, it is impossible to handle things correctly from an internationalization standpoint by operating on bytes, since characters may be multibyte. Thus `g_strncasecmp()` is broken if your string is guaranteed to be ASCII, since it is locale-sensitive, and it's broken if your string is localized, since it doesn't work on many encodings at all, including UTF-8, EUC-JP, etc.

There are therefore two replacement techniques: `g_ascii_strncasecmp()`, which only works on ASCII and is not locale-sensitive, and `g_utf8_casefold()` followed by `strcmp()` on the resulting strings, which is good for case-insensitive sorting of UTF-8.

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.

#### Parameters

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

    gchar *
    g_strreverse (gchar *string);

Reverses all of the bytes in a string. For example, `g_strreverse ("abcdef")` will result in "fedcba".

Note that `g_strreverse()` doesn't work on UTF-8 strings containing multibyte characters. For that purpose, use `g_utf8_strreverse()`.

#### Parameters

string | the string to reverse |

#### Returns

the same pointer passed in as `string`

### g_ascii_strtoll ()

    gint64
    g_ascii_strtoll (const gchar *nptr,
                     gchar **endptr,
                     guint base);

Converts a string to a gint64 value. This function behaves like the standard `strtoll()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe.

This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the locale-sensitive system `strtoll()` function.

If the correct value would cause overflow, `G_MAXINT64` or `G_MININT64` is returned, and `ERANGE` is stored in `errno`. If the base is outside the valid range, zero is returned, and `EINVAL` is stored in `errno`. If the string conversion fails, zero is returned, and `endptr` returns `nptr` (if `endptr` is non-`NULL`).

#### Parameters

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. | [out][transfer none][optional]
base | to be used for the conversion, 2..36 or 0 |

#### Returns

the gint64 value or zero on error.

Since: 2.12

### g_ascii_strtoull ()

    guint64
    g_ascii_strtoull (const gchar *nptr,
                      gchar **endptr,
                      guint base);

Converts a string to a guint64 value. This function behaves like the standard `strtoull()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe.

Note that input with a leading minus sign (`-`) is accepted, and will return the negation of the parsed number, unless that would overflow a guint64. Critically, this means you cannot assume that a short fixed length input will never result in a low return value, as the input could have a leading `-`.

This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the locale-sensitive system `strtoull()` function.

If the correct value would cause overflow, `G_MAXUINT64` is returned, and `ERANGE` is stored in `errno`. If the base is outside the valid range, zero is returned, and `EINVAL` is stored in `errno`. If the string conversion fails, zero is returned, and `endptr` returns `nptr` (if `endptr` is non-`NULL`).

#### Parameters

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. | [out][transfer none][optional]
base | to be used for the conversion, 2..36 or 0 |

#### Returns

the guint64 value or zero on error.

Since: 2.2

### g_ascii_strtod ()

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

Converts a string to a gdouble value.

This function behaves like the standard `strtod()` function does in the C locale. It does this without actually changing the current locale, since that would not be thread-safe. A limitation of the implementation is that this function will still accept localized versions of infinities and NANs.

This function is typically used when reading configuration files or other non-user input that should be locale independent. To handle input from the user you should normally use the locale-sensitive system `strtod()` function.

To convert from a gdouble to a string in a locale-insensitive way, use `g_ascii_dtostr()`.

If the correct value would cause overflow, plus or minus `HUGE_VAL` is returned (according to the sign of the value), and `ERANGE` is stored in `errno`. If the correct value would cause underflow, zero is returned and `ERANGE` is stored in `errno`.

This function resets `errno` before calling `strtod()` so that you can reliably detect overflow and underflow.

#### Parameters

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. | [out][transfer none][optional]

#### Returns

the gdouble value.

### g_ascii_dtostr ()

    gchar *
    g_ascii_dtostr (gchar *buffer,
                    gint buf_len,
                    gdouble d);

Converts a gdouble to a string, using the '.' as decimal point.

This function generates enough precision that converting the string back using `g_ascii_strtod()` gives the same machine-number (on machines with IEEE compatible 64bit doubles). It is guaranteed that the size of the resulting string will never be larger than `G_ASCII_DTOSTR_BUF_SIZE` bytes, including the terminating nul character, which is always added.

#### Parameters

buffer | A buffer to place the resulting string in |
buf_len | The length of the buffer. |
d | The gdouble to convert |

#### Returns

The pointer to the buffer with the converted string.

### g_ascii_formatd ()

    gchar *
    g_ascii_formatd (gchar *buffer,
                     gint buf_len,
                     const gchar *format,
                     gdouble d);

Converts a gdouble to a string, using the '.' as decimal point. To format the number you pass in a `printf()`-style format string. Allowed conversion specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.

The returned buffer is guaranteed to be nul-terminated.

If you just want to want to serialize the value into a string, use `g_ascii_dtostr()`.

#### Parameters

buffer | A buffer to place the resulting string in |
buf_len | The length of the buffer. |
format | The `printf()`-style format to use for the code to use for converting. |
d | The gdouble to convert |

#### Returns

The pointer to the buffer with the converted string.

### 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 with `g_ascii_strtod()`, and returns the best match.

This function should seldom be used. The normal situation when reading numbers not for human consumption is to use `g_ascii_strtod()`. Only when you know that you must expect both locale formatted and C formatted numbers should you use this. Make sure that you don't pass strings such as comma separated lists of values, since the commas may be interpreted as a decimal point in some locales, causing unexpected results.

#### Parameters

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. | [out][transfer none][optional]

#### Returns

the gdouble value.

### g_ascii_string_to_signed ()

    gboolean
    g_ascii_string_to_signed (const gchar *str,
                              guint base,
                              gint64 min,
                              gint64 max,
                              gint64 *out_num,
                              GError **error);

A convenience function for converting a string to a signed number.

This function assumes that `str` contains only a number of the given `base` that is within inclusive bounds limited by `min` and `max` . If this is true, then the converted number is stored in `out_num` . An empty string is not a valid input. A string with leading or trailing whitespace is also an invalid input.

`base` can be between 2 and 36 inclusive. Hexadecimal numbers must not be prefixed with "0x" or "0X". Such a problem does not exist for octal numbers, since they were usually prefixed with a zero which does not change the value of the parsed number.

Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` domain. If the input is invalid, the error code will be `G_NUMBER_PARSER_ERROR_INVALID`. If the parsed number is out of bounds - `G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS`.

See `g_ascii_strtoll()` if you have more complex needs such as parsing a string which starts with a number, but then has other characters.

#### Parameters

str | a string |
base | base of a parsed number |
min | a lower bound (inclusive) |
max | an upper bound (inclusive) |
out_num | a return location for a number. | [out][optional]
error | a return location for GError |

#### Returns

`TRUE` if `str` was a number, otherwise `FALSE`.

Since: 2.54

### g_ascii_string_to_unsigned ()

    gboolean
    g_ascii_string_to_unsigned (const gchar *str,
                                guint base,
                                guint64 min,
                                guint64 max,
                                guint64 *out_num,
                                GError **error);

A convenience function for converting a string to an unsigned number.

This function assumes that `str` contains only a number of the given `base` that is within inclusive bounds limited by `min` and `max` . If this is true, then the converted number is stored in `out_num` . An empty string is not a valid input. A string with leading or trailing whitespace is also an invalid input. A string with a leading sign (`-` or `+`) is not a valid input for the unsigned parser.

`base` can be between 2 and 36 inclusive. Hexadecimal numbers must not be prefixed with "0x" or "0X". Such a problem does not exist for octal numbers, since they were usually prefixed with a zero which does not change the value of the parsed number.

Parsing failures result in an error with the `G_NUMBER_PARSER_ERROR` domain. If the input is invalid, the error code will be `G_NUMBER_PARSER_ERROR_INVALID`. If the parsed number is out of bounds - `G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS`.

See `g_ascii_strtoull()` if you have more complex needs such as parsing a string which starts with a number, but then has other characters.

#### Parameters

str | a string |
base | base of a parsed number |
min | a lower bound (inclusive) |
max | an upper bound (inclusive) |
out_num | a return location for a number. | [out][optional]
error | a return location for GError |

#### Returns

`TRUE` if `str` was a number, otherwise `FALSE`.

Since: 2.54

### g_strchug ()

    gchar *
    g_strchug (gchar *string);

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

This function doesn't allocate or reallocate any memory; it modifies `string` in place. Therefore, it cannot be used on statically allocated strings.

The pointer to `string` is returned to allow the nesting of functions.

Also see `g_strchomp()` and `g_strstrip()`.

#### Parameters

string | a string to remove the leading whitespace from |

#### Returns

`string`

### g_strchomp ()

    gchar *
    g_strchomp (gchar *string);

Removes trailing whitespace from a string.

This function doesn't allocate or reallocate any memory; it modifies `string` in place. Therefore, it cannot be used on statically allocated strings.

The pointer to `string` is returned to allow the nesting of functions.

Also see `g_strchug()` and `g_strstrip()`.

#### Parameters

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. See `g_strchomp()` and `g_strchug()`.

#### Parameters

string | a string to remove the leading and trailing whitespace from |

#### Returns

`string`

### 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. Modifies `string` in place, and returns `string` itself, not a copy. The return value is to allow nesting such as

    1

    g_ascii_strup (g_strdelimit (str, "abc", '?'))

In order to modify a copy, you may use ``g_strdup()``:

    1
    2
    3

    reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
    ...
    g_free (reformatted);

#### Parameters

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

#### Returns

`string`

### g_strescape ()

    gchar *
    g_strescape (const gchar *source,
                 const gchar *exceptions);

Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' and '"' in the string `source` by inserting a '\' before them. Additionally all characters in the range 0x01-0x1F (everything below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are replaced with a '\' followed by their octal representation. Characters supplied in `exceptions` are not escaped.

g_strcompress() does the reverse conversion.

#### Parameters

source | a string to escape |
exceptions | a string of characters not to escape in `source` . | [nullable]

#### Returns

a newly-allocated copy of `source` with certain characters escaped. See above.

### g_strcompress ()

    gchar *
    g_strcompress (const gchar *source);

Replaces all escaped characters with their one byte equivalent.

This function does the reverse conversion of `g_strescape()`.

#### Parameters

source | a string to compress |

#### Returns

a newly-allocated copy of `source` with all escaped character compressed

### g_strcanon ()

    gchar *
    g_strcanon (gchar *string,
                const gchar *valid_chars,
                gchar substitutor);

For each character in `string` , if the character is not in `valid_chars` , replaces the character with `substitutor` . Modifies `string` in place, and return `string` itself, not a copy. The return value is to allow nesting such as

    1

    g_ascii_strup (g_strcanon (str, "abc", '?'))

In order to modify a copy, you may use ``g_strdup()``:

    1
    2
    3

    reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
    ...
    g_free (reformatted);

#### Parameters

string | a nul-terminated array of bytes |
valid_chars | bytes permitted in `string` |
substitutor | replacement character for disallowed bytes |

#### Returns

`string`

### 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 remainder of `string` is appended to the last token.

As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a `NULL`-terminated vector containing the six strings "", "a", "bc", "", "d" and "".

As a special case, the result of splitting the empty string "" is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling `g_strsplit()`.

#### Parameters

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 pieces to split `string` into. If this is less than 1, the string is split completely. |

#### Returns

a newly-allocated `NULL`-terminated array of strings. Use `g_strfreev()` to free it.

### g_strsplit_set ()

    gchar **
    g_strsplit_set (const gchar *string,
                    const gchar *delimiters,
                    gint max_tokens);

Splits `string` into a number of tokens not containing any of the characters in `delimiter` . A token is the (possibly empty) longest string that does not contain any of the characters in `delimiters` . If `max_tokens` is reached, the remainder is appended to the last token.

For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a `NULL`-terminated vector containing the three strings "abc", "def", and "ghi".

The result of g_strsplit_set (":def/ghi:", ":/", -1) is a `NULL`-terminated vector containing the four strings "", "def", "ghi", and "".

As a special case, the result of splitting the empty string "" is an empty vector, not a vector containing a single string. The reason for this special case is that being able to represent an empty vector is typically more useful than consistent handling of empty elements. If you do need to represent empty elements, you'll need to check for the empty string before calling `g_strsplit_set()`.

Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters.

#### Parameters

string | The string to be tokenized |
delimiters | A nul-terminated string containing bytes that are used to split the string. |
max_tokens | The maximum number of tokens to split `string` into. If this is less than 1, the string is split completely |

#### Returns

a newly-allocated `NULL`-terminated array of strings. Use `g_strfreev()` to free it.

Since: 2.4

### g_strfreev ()

    void
    g_strfreev (gchar **str_array);

Frees a `NULL`-terminated array of strings, as well as each string it contains.

If `str_array` is `NULL`, this function simply returns.

#### Parameters

str_array | a `NULL`-terminated array of strings to free. | [nullable]

### g_strconcat ()

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

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

The variable argument list must end with `NULL`. If you forget the `NULL`, `g_strconcat()` will start appending random memory junk to your string.

Note that this function is usually not the right function to use to assemble a translated message from pieces, since proper translation often requires the pieces to be reordered.

#### Parameters

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. The returned string should be freed with `g_free()`.

#### Parameters

separator | a string to insert between each of the strings, or `NULL`. | [nullable]
... | 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. The returned string should be freed with `g_free()`.

If `str_array` has no items, the return value will be an empty string. If `str_array` contains a single item, `separator` will not appear in the resulting string.

#### Parameters

separator | a string to insert between each of the strings, or `NULL`. | [nullable]
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_strv_length ()

    guint
    g_strv_length (gchar **str_array);

Returns the length of the given `NULL`-terminated string array `str_array` . `str_array` must not be `NULL`.

#### Parameters

str_array | a `NULL`-terminated array of strings |

#### Returns

length of `str_array` .

Since: 2.6

### g_strv_contains ()

    gboolean
    g_strv_contains (const gchar * const *strv,
                     const gchar *str);

Checks if `strv` contains `str` . `strv` must not be `NULL`.

#### Parameters

strv | a `NULL`-terminated array of strings |
str | a string |

#### Returns

`TRUE` if `str` is an element of `strv` , according to `g_str_equal()`.

Since: 2.44

### g_strv_equal ()

    gboolean
    g_strv_equal (const gchar * const *strv1,
                  const gchar * const *strv2);

Checks if `strv1` and `strv2` contain exactly the same elements in exactly the same order. Elements are compared using `g_str_equal()`. To match independently of order, sort the arrays first (using `g_qsort_with_data()` or similar).

Two empty arrays are considered equal. Neither `strv1` not `strv2` may be `NULL`.

#### Parameters

strv1 | a `NULL`-terminated array of strings |
strv2 | another `NULL`-terminated array of strings |

#### Returns

`TRUE` if `strv1` and `strv2` are equal

Since: 2.60

### g_strerror ()

    const gchar *
    g_strerror (gint errnum);

Returns a string corresponding to the given error code, e.g. "no such process". Unlike `strerror()`, this always returns a string in UTF-8 encoding, and the pointer is guaranteed to remain valid for the lifetime of the process.

Note that the string may be translated according to the current locale.

The value of `errno` will not be changed by this function. However, it may be changed by intermediate function calls, so you should save its value as soon as the call returns:

    1
    2
    3
    4
    5
    6

    int saved_errno;

    ret = read (blah);
    saved_errno = errno;

    g_strerror (saved_errno);

#### Parameters

errnum | the system error number. See the standard C `errno` documentation |

#### Returns

a UTF-8 string describing the error code. If the error code is unknown, it returns a string like "unknown error (<code>)".

### g_strsignal ()

    const gchar *
    g_strsignal (gint signum);

Returns a string describing the given signal, e.g. "Segmentation fault". You should use this function in preference to `strsignal()`, because it returns a string in UTF-8 encoding, and since not all platforms support the `strsignal()` function.

#### Parameters

signum | the signal number. See the `signal` documentation |

#### Returns

a UTF-8 string describing the signal. If the signal is unknown, it returns "unknown signal (<signum>)".

## Types and Values

### G_ASCII_DTOSTR_BUF_SIZE

    #define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)

A good size for a buffer to be passed into `g_ascii_dtostr()`. It is guaranteed to be enough for all output of that function on systems with 64bit IEEE-compatible doubles.

The typical usage would be something like:

    1
    2
    3

    char buf[G_ASCII_DTOSTR_BUF_SIZE];

    fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));

### enum GNumberParserError

Error codes returned by functions converting a string to a number.

#### Members

G_NUMBER_PARSER_ERROR_INVALID | String was not a valid number. |
G_NUMBER_PARSER_ERROR_OUT_OF_BOUNDS | String was a number, but out of bounds. |

Since: 2.54

### G_NUMBER_PARSER_ERROR

    #define G_NUMBER_PARSER_ERROR (g_number_parser_error_quark ())

Domain for errors returned by functions converting a string to a number.

Since: 2.54

### G_STR_DELIMITERS

    #define	 G_STR_DELIMITERS "_-|> <."

The standard delimiters, used in `g_strdelimit()`.

### GStrv

    typedef gchar** GStrv;

A typedef alias for gchar**. This is mostly useful when used together with `g_auto()`.