String Utility Functions various string-related functions. 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_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() 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. 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. Duplicates a string. If @str is %NULL it returns %NULL. The returned string should be freed when no longer needed. @str: the string to duplicate. @Returns: a newly-allocated copy of @str. 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. If @str is %NULL it returns %NULL. The returned value should be freed when no longer needed. @str: the string to duplicate part of. @n: the maximum number of characters to copy from @str. @Returns: a newly-allocated buffer containing the first @n characters of @str, nul-terminated. @str_array: @Returns: Creates a new string @length characters long filled with @fill_char. The returned string should be freed when no longer needed. @length: the length of the new string. @fill_char: the character to fill the string with. @Returns: a newly-allocated string filled the @fill_char. @dest: @src: @Returns: @haystack: @haystack_len: @needle: @Returns: @haystack: @needle: @Returns: @haystack: @haystack_len: @needle: @Returns: @str: @prefix: @Returns: @str: @suffix: @Returns: 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. @dest: destination buffer @src: source buffer @dest_size: length of @dest in bytes @Returns: length of @src 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. Caveat: this is supposedly a more secure alternative to strcat() or strncat(), but for real security g_strconcat() is harder to mess up. @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: length of @src plus initial length of string in @dest Similar to the standard C sprintf() function but safer, since it calculates the maximum space required and allocates memory to hold the result. The returned string should be freed when no longer needed. @format: a standard printf() format string, but notice string precision pitfalls. @Varargs: the parameters to insert into the format string. @Returns: a newly-allocated string holding the result. 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. @format: a standard printf() format string, but notice string precision pitfalls. @args: the list of parameters to insert into the format string. @Returns: a newly-allocated string holding the result. @format: @Varargs: @Returns: @format: @args: @Returns: @file: @format: @Varargs: @Returns: @file: @format: @args: @Returns: @string: @format: @Varargs: @Returns: @string: @format: @args: @Returns: @string: @n: @format: @Varargs: @Returns: @string: @n: @format: @args: @Returns: @string: @format: @args: @Returns: Calculates the maximum space needed to store the output of the sprintf() function. @format: the format string. See the printf() documentation. @args: the parameters to be inserted into the format string. @Returns: the maximum space needed to store the formatted string. 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. @c: any character @Returns: %TRUE if @c is an ASCII alphanumeric character 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. @c: any character @Returns: %TRUE if @c is an ASCII alphabetic character 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. @c: any character @Returns: %TRUE if @c is an ASCII control character. 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. @c: any character @Returns: %TRUE if @c is an ASCII digit. 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. @c: any character @Returns: %TRUE if @c is an ASCII printing character other than space. 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. @c: any character @Returns: %TRUE if @c is an ASCII lower case letter 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. @c: any character @Returns: %TRUE if @c is an ASCII printing character. 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. @c: any character @Returns: %TRUE if @c is an ASCII punctuation character. 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. @c: any character @Returns: %TRUE if @c is an ASCII white-space character 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. @c: any character @Returns: %TRUE if @c is an ASCII upper case letter 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. @c: any character @Returns: %TRUE if @c is an ASCII hexadecimal-digit character. @c: @Returns: @c: @Returns: @s1: @s2: @Returns: @s1: @s2: @n: @Returns: @str: @len: @Returns: @string: @str: @len: @Returns: @c: @Returns: @c: @Returns: @string: @Returns: @string: @Returns: @string: @Returns: @string: @Returns: @s1: @s2: @Returns: @s1: @s2: @n: @Returns: 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(). @string: the string to reverse. @Returns: the same pointer passed in as @string. @nptr: @endptr: @base: @Returns: 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)); @nptr: @endptr: @Returns: @buffer: @buf_len: @d: @Returns: @buffer: @buf_len: @format: @d: @Returns: @nptr: @endptr: @Returns: Removes leading whitespace from a string, by moving the rest of the characters forward. @string: a string to remove the leading whitespace from. @Returns: @string. Removes trailing whitespace from a string. @string: a string to remove the trailing whitespace from. @Returns: @string. Removes leading and trailing whitespace from a string. @string: a string to remove the leading and trailing whitespace from. 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", '?')). @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: @string. The standard delimiters, used in g_strdelimit(). 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. @source: a string to escape. @exceptions: a string of characters not to escape in @source. @Returns: a newly-allocated copy of @source with certain characters escaped. See above. Replaces all escaped characters with their one byte equivalent. It does the reverse conversion of g_strescape(). @source: a string to compress. @Returns: a newly-allocated copy of @source with all escaped character compressed. 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", '?')). @string: a nul-terminated array of bytes. @valid_chars: bytes permitted in @string. @substitutor: replacement character for disallowed bytes. @Returns: @string. @string: @delimiter: @max_tokens: @Returns: @string: @delimiters: @max_tokens: @Returns: @str_array: Concatenates all of the given strings into one long string. The returned string should be freed 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. @string1: The first string to add, which must not be %NULL. @Varargs: a %NULL-terminated list of strings to append to the string. @Returns: a newly-allocated string containing all the string arguments. Joins a number of strings together to form one long string, with the optional @separator inserted between each of them. @separator: a string to insert between each of the strings, or %NULL. @Varargs: a %NULL-terminated list of strings to join. @Returns: a newly-allocated string containing all of the strings joined together, with @separator between them. Joins a number of strings together to form one long string, with the optional @separator inserted between each of them. @separator: a string to insert between each of the strings, or %NULL. @str_array: a %NULL-terminated array of strings to join. @Returns: a newly-allocated string containing all of the strings joined together, with @separator between them. Returns a string corresponding to the given error code, e.g. "no such process". This function is included since not all platforms support the strerror() function. @errnum: the system error number. See the standard C %errno documentation. @Returns: a string describing the error code. If the error code is unknown, it returns "unknown error (<code>)". The string can only be used until the next call to g_strerror(). Returns a string describing the given signal, e.g. "Segmentation fault". This function is included since not all platforms support the strsignal() function. @signum: the signal number. See the signal documentation. @Returns: a string describing the signal. If the signal is unknown, it returns "unknown signal (<signum>)". The string can only be used until the next call to g_strsignal().