Name

g_strdup ()

gchar*      g_strdup           (const gchar *str);

Duplicates a string. If str is NULL it returns NULL. The returned string should be freed when no longer needed.

g_strndup ()

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

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

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. If called on a NULL value, g_strdupv() simply returns NULL.

g_strnfill ()

gchar*      g_strnfill        (gsize length, gchar fill_char);

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

g_stpcpy ()

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

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

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.

g_strrstr ()

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

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

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.

g_str_has_prefix ()

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

Looks whether the string str begins with prefix.

g_str_has_suffix ()

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

Looks whether the string str ends with suffix.

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 null-terminated; src must be null-terminated; dest_size is the buffer size, not the number of chars to copy. Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(), but using, g_strdup() is an even better idea.

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 null-terminated src string to dest, guaranteeing null-termination for dest. The total size of dest won't exceed dest_size. Caveat: this is supposedly a more secure alternative to strcat() or strncat(), but for real security g_strconcat() is harder to mess up.

g_strdup_printf ()

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

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

g_strdup_vprintf ()

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

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

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

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.

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.

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.

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.

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.

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.

g_snprintf ()

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

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

See also g_strdup_printf().

In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be null-terminated. 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.

g_vsnprintf ()

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

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

See also g_strdup_vprintf().

In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be null-terminated. 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.

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 allocate in advance.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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-* char sets, 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 two CP932 strings are compared using this function, false matches are obtained.

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.

g_ascii_strup ()

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

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

g_ascii_strdown ()

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

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

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.

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.

g_string_ascii_up ()

GString*    g_string_ascii_up         (GString *string);

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

g_string_ascii_down ()

GString*    g_string_ascii_down             (GString *string);

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

g_strup ()

gchar*      g_strup                         (gchar *string);

Converts a string to upper case.

Warning: 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.

g_strdown ()

gchar*      g_strdown                       (gchar *string);

Converts a string to lower case.

Warning: 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.

g_strcasecmp ()

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

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

Warning: 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.

g_strncasecmp ()

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

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

Warning: 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 I18N standpoint by operating on bytes, since characters may be multi byte. Thus g_strncasecmp() is broken if the string is guaranteed to be ASCII, since it's locale-sensitive, and it's broken if the string is localized, since it does not work on many encodings at all, including UTF-8, EUC-JP, etc. There are therefore two replacement functions: g_ascii_strncasecmp(), which only works on ASCII and is not locale-sensitive, and g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8.

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() does not work on UTF-8 strings containing multi byte characters. For that purpose, use g_utf8_strreverse().

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.

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, the locale-sensitive system strtoull() function is used.

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

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:

  char buf[G_ASCII_DTOSTR_BUF_SIZE];

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

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.

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, the locale-sensitive system strtod() function is used.

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 overflow and underflow can be detected reliably.

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 functions 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.

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 passed in a printf()-style format string. Allowed conversion specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.

To serialize the value into a string, use g_ascii_dtostr().

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 seldomly be used. The normal situation when reading numbers not for human consumption is to use g_ascii_strtod().This function must be used only when the expected locale formatted and C formatted numbers are known. Make sure that not to 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.

g_strchug ()

gchar*      g_strchug         (gchar *string);

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

This function does not allocate or reallocate any memory; it modifies string in place. The pointer to string is returned to allow the nesting of functions.

Also see g_strchomp() and g_strstrip().

g_strchomp ()

gchar*      g_strchomp         (gchar *string);

Removes trailing white space from a string.

This function does not allocate or reallocate any memory; it modifies string in place. The pointer to string is returned to allow the nesting of functions.

Also see g_strchug() and g_strstrip().

g_strstrip()

#define     g_strstrip( string )

Removes leading and trailing white space from a string. See g_strchomp() and g_strchug().

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", '?')).

G_STR_DELIMITERS

#define	 G_STR_DELIMITERS	"_-|> <."

The standard delimiters, used in g_strdelimit().

g_strescape ()

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

Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' 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.

g_strcompress ()

gchar*      g_strcompress        (const gchar *source);

Replaces all escaped characters with their one byte equivalent. It does the reverse conversion of g_strescape().

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", '?')).

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 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 a empty vector is typically more useful than consistent handling of empty elements. If there is no need to represent empty elements, check for the empty string before calling g_strsplit().

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 if 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 a empty vector is typically more useful than consistent handling of empty elements. If there is no need to represent empty elements, check for the empty string before calling g_strsplit_set().

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

g_strfreev ()

void        g_strfreev       (gchar **str_array);

Frees a NULL-terminated array of strings, and the array itself. If called on a NULL value, g_strfreev() simply returns.

g_strconcat ()

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

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

Warning: The variable argument list must end with NULL. If  NULL is forgotten, g_strconcat() will start appending random memory junk to the string.

 

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.

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.

g_strv_length ()

guint       g_strv_length          (gchar **str_array); 

Returns the length of the given NULL-terminated string array str_array.

g_strerror ()

const gchar* g_strerror        (gint errnum);

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

g_strsignal ()

const gchar* g_strsignal       (gint signum);

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