GLib Reference Manual | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
This section describes a number of utility functions for creating, duplicating, and manipulating strings.
gchar* g_strdup (const gchar *str); |
Duplicates a string. The returned string should be freed when no longer needed.
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 nul-terminated. If str is less than n characters long the buffer is padded with nuls. The returned value should be freed when no longer needed.
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.
Copies a NULL-terminated array of strings. The result consists of a NULL-terminated array, with one malloc block holding the array of strings, and each string itself allocated. The simplest way to free the result is with g_strfreev() which frees each string in a vector, then the vector itself.
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.
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.
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.
gchar* g_strrstr (const gchar *haystack, const gchar *needle); |
Searches the string haystack for the last occurrence of the string needle.
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.
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 chars to copy. 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.
gsize g_strlcat (gchar *dest, const gchar *src, gsize dest_size); |
Portability wrapper that calls strlcat() on systems which have it, and emulates strlcat() otherwise. Appends nul-terminated src string to dest, guaranteeing nul-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.
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.
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.
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().
Note: In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated.
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().
Note: In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated.
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.
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.
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.
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, returningFALSE 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
c : | an ASCII character. |
Returns : | If c is a decimal digit (according to g_ascii_isdigit()), its numeric value. Otherwise, -1. |
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.
c : | an ASCII character. |
Returns : | If c is a hex digit (according to g_ascii_isxdigit()), its numeric value. Otherwise, -1. |
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 characters as if they are not letters.
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.
gchar* g_ascii_strup (const gchar *str, gssize len); |
Converts all lower case ASCII letters to upper case ASCII letters.
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.) |
gchar* g_ascii_strdown (const gchar *str, gssize len); |
Converts all upper case ASCII letters to lower case ASCII letters.
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.) |
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.
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.
GString* g_string_ascii_up (GString *string); |
Converts all lower case ASCII letters to upper case ASCII letters.
GString* g_string_ascii_down (GString *string); |
Converts all upper case ASCII letters to lower case ASCII letters.
gchar* g_strup (gchar *string); |
Warning |
g_strup is deprecated and should not be used in newly-written code. |
Converts a string to upper case.
gchar* g_strdown (gchar *string); |
Warning |
g_strdown is deprecated and should not be used in newly-written code. |
Converts a string to lower case.
gint g_strcasecmp (const gchar *s1, const gchar *s2); |
Warning |
g_strcasecmp is deprecated and should not be used in newly-written code. |
A case-insensitive string comparison, corresponding to the standard strcasecmp() function on platforms which support it.
gint g_strncasecmp (const gchar *s1, const gchar *s2, guint n); |
Warning |
g_strncasecmp is deprecated and should not be used in newly-written code. |
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.
gchar* g_strreverse (gchar *string); |
Reverses all of the characters in a string. For example, g_strreverse ("abcdef") will result in "fedcba".
gdouble g_strtod (const gchar *nptr, gchar **endptr); |
Converts a string to a gdouble value. It calls the standard strtod() function to handle the conversion, but if the string is not completely converted it attempts the conversion again in the "C" locale, and returns the best match.
gchar* g_strchug (gchar *string); |
Removes leading whitespace from a string, by moving the rest of the characters forward.
gchar* g_strdelimit (gchar *string, const gchar *delimiters, gchar new_delimiter); |
Converts any delimiter characters in string to new_delimiter. Any characters in string which are found in delimiters are changed to the new_delimiter character.
string : | the string to convert. |
delimiters : | a string containing the current delimiters, or NULL to use the standard delimiters defined in G_STR_DELIMITERS. |
new_delimiter : | the new delimiter character. |
Returns : |
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 0x80-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.
gchar* g_strcompress (const gchar *source); |
Replaces all escaped characters with their one byte equivalent. It does the reverse conversion of g_strescape().
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_strup (g_strcanon (str)).
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 you do need to represent empty elements, you'll need to check for the empty string before calling g_strsplit().
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. |
void g_strfreev (gchar **str_array); |
Frees a NULL-terminated array of strings, and the array itself.
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 you forget the NULL, g_strconcat() will start appending random memory junk to your string.
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.
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_CONST_RETURN 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.