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 ()
GStrvBuilder *    g_strv_builder_new ()
GStrvBuilder *    g_strv_builder_ref ()
void    g_strv_builder_unref ()
void    g_strv_builder_add ()
GStrv    g_strv_builder_end ()
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
     GStrvBuilder

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 nul-terminated string

haystack_len

the maximum length of haystack in bytes. A length of -1 can be used to mean “search the entire string”, like strstr().

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 in bytes. A length of -1 can be used to mean “search the entire string”, like g_strrstr().

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.

译:
此函数类似于标准的C语言中的 sprintf()函数，但是比它更安全，因为此函数计算了请求的最大字符空间并分配对应的内存，以便于处理返回的结果。返回的字符串再不使用的时候，会自动调用 g_free() 释放内存。

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.

译:
除非指定的格式转换字符为 %lc 或 %ls 转换，否则返回的字符串均为 非NULL ，如果给定的字符没有多余的内存空间可用，转换可能会失败。

Parameters

• format
  a standard printf() format string, but notice string precision pitfalls.

  译:
  该参数为标准的 printf（）格式字符串，但要注意字符串的精度陷阱。

• …
  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

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 hexadecimal 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

g_ascii_strup (g_strdelimit (str, “abc”, ‘?’))
In order to modify a copy, you may use g_strdup():

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

g_ascii_strup (g_strcanon (str, “abc”, ‘?’))
In order to modify a copy, you may use g_strdup():

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 (it can accept an empty string, which will result in no string splitting).

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_strv_builder_new ()
GStrvBuilder *
g_strv_builder_new (void);
Creates a new GStrvBuilder with a reference count of 1. Use g_strv_builder_unref() on the returned value when no longer needed.

Returns
the new GStrvBuilder.

[transfer full]

Since: 2.68

g_strv_builder_ref ()
GStrvBuilder *
g_strv_builder_ref (GStrvBuilder *builder);
Atomically increments the reference count of builder by one. This function is thread-safe and may be called from any thread.

Parameters
builder

a GStrvBuilder.

[transfer none]
Returns
The passed in GStrvBuilder.

[transfer full]

Since: 2.68

g_strv_builder_unref ()
void
g_strv_builder_unref (GStrvBuilder *builder);
Decreases the reference count on builder .

In the event that there are no more references, releases all memory associated with the GStrvBuilder.

Parameters
builder

a GStrvBuilder allocated by g_strv_builder_new().

[transfer full]
Since: 2.68

g_strv_builder_add ()
void
g_strv_builder_add (GStrvBuilder *builder,
const char *value);
Add a string to the end of the array.

Since 2.68

Parameters
builder

a GStrvBuilder

value

a string.

g_strv_builder_end ()
GStrv
g_strv_builder_end (GStrvBuilder *builder);
Ends the builder process and returns the constructed NULL-terminated string array. The returned value should be freed with g_strfreev() when no longer needed.

Parameters
builder

a GStrvBuilder

Returns
the constructed string array.

Since 2.68.

[transfer full]

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:

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