<!-- ##### SECTION Title ##### --> String Utility Functions <!-- ##### SECTION Short_Description ##### --> various string-related functions. <!-- ##### SECTION Long_Description ##### --> <para> This section describes a number of utility functions for creating, duplicating, and manipulating strings. </para> <para> 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 <filename>gprintf.h</filename> which is <emphasis>not</emphasis> included in <filename>glib.h</filename> (otherwise using <filename>glib.h</filename> would drag in <filename>stdio.h</filename>), so you'll have to explicitly include <literal><glib/gprintf.h></literal> in order to use the GLib printf() functions. </para> <para id="string-precision"> While you may use the printf() functions to format UTF-8 strings, notice that the precision of a <literal>%Ns</literal> parameter is interpreted as the number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> 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 <literal>%Ns</literal> 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 <literal>%Ns</literal>. If your intention is to format strings for a certain number of columns, then <literal>%Ns</literal> is not a correct solution anyway, since it fails to take wide characters (see g_unichar_iswide()) into account. </para> <!-- ##### SECTION See_Also ##### --> <para> </para> <!-- ##### FUNCTION g_strdup ##### --> <para> Duplicates a string. If @str is %NULL it returns %NULL. The returned string should be freed when no longer needed. </para> @str: the string to duplicate. @Returns: a newly-allocated copy of @str. <!-- ##### FUNCTION g_strndup ##### --> <para> 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. </para> @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. <!-- ##### FUNCTION g_strdupv ##### --> <para> </para> @str_array: @Returns: <!-- ##### FUNCTION g_strnfill ##### --> <para> Creates a new string @length characters long filled with @fill_char. The returned string should be freed when no longer needed. </para> @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. <!-- ##### FUNCTION g_stpcpy ##### --> <para> </para> @dest: @src: @Returns: <!-- ##### FUNCTION g_strstr_len ##### --> <para> </para> @haystack: @haystack_len: @needle: @Returns: <!-- ##### FUNCTION g_strrstr ##### --> <para> </para> @haystack: @needle: @Returns: <!-- ##### FUNCTION g_strrstr_len ##### --> <para> </para> @haystack: @haystack_len: @needle: @Returns: <!-- ##### FUNCTION g_str_has_prefix ##### --> <para> </para> @str: @prefix: @Returns: <!-- ##### FUNCTION g_str_has_suffix ##### --> <para> </para> @str: @suffix: @Returns: <!-- ##### FUNCTION g_strlcpy ##### --> <para> 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. </para> @dest: destination buffer @src: source buffer @dest_size: length of @dest in bytes @Returns: length of @src <!-- ##### FUNCTION g_strlcat ##### --> <para> 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. </para> @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 <!-- ##### FUNCTION g_strdup_printf ##### --> <para> 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. </para> @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. @Varargs: the parameters to insert into the format string. @Returns: a newly-allocated string holding the result. <!-- ##### FUNCTION g_strdup_vprintf ##### --> <para> 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. </para> <para> See also g_vasprintf(), which offers the same functionality, but additionally returns the length of the allocated string. </para> @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. @args: the list of parameters to insert into the format string. @Returns: a newly-allocated string holding the result. <!-- ##### FUNCTION g_printf ##### --> <para> </para> @format: @Varargs: @Returns: <!-- ##### FUNCTION g_vprintf ##### --> <para> </para> @format: @args: @Returns: <!-- ##### FUNCTION g_fprintf ##### --> <para> </para> @file: @format: @Varargs: @Returns: <!-- ##### FUNCTION g_vfprintf ##### --> <para> </para> @file: @format: @args: @Returns: <!-- ##### FUNCTION g_sprintf ##### --> <para> </para> @string: @format: @Varargs: @Returns: <!-- ##### FUNCTION g_vsprintf ##### --> <para> </para> @string: @format: @args: @Returns: <!-- ##### FUNCTION g_snprintf ##### --> <para> </para> @string: @n: @format: @Varargs: @Returns: <!-- ##### FUNCTION g_vsnprintf ##### --> <para> </para> @string: @n: @format: @args: @Returns: <!-- ##### FUNCTION g_vasprintf ##### --> <para> </para> @string: @format: @args: @Returns: <!-- ##### FUNCTION g_printf_string_upper_bound ##### --> <para> Calculates the maximum space needed to store the output of the sprintf() function. </para> @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. <!-- ##### FUNCTION g_ascii_isalnum ##### --> <para> Determines whether a character is alphanumeric. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII alphanumeric character <!-- ##### FUNCTION g_ascii_isalpha ##### --> <para> Determines whether a character is alphabetic (i.e. a letter). </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII alphabetic character <!-- ##### FUNCTION g_ascii_iscntrl ##### --> <para> Determines whether a character is a control character. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII control character. <!-- ##### FUNCTION g_ascii_isdigit ##### --> <para> Determines whether a character is digit (0-9). </para> <para> Unlike the standard C library isdigit() function, this takes a <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII digit. <!-- ##### FUNCTION g_ascii_isgraph ##### --> <para> Determines whether a character is a printing character and not a space. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII printing character other than space. <!-- ##### FUNCTION g_ascii_islower ##### --> <para> Determines whether a character is an ASCII lower case letter. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to worry about casting to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII lower case letter <!-- ##### FUNCTION g_ascii_isprint ##### --> <para> Determines whether a character is a printing character. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII printing character. <!-- ##### FUNCTION g_ascii_ispunct ##### --> <para> Determines whether a character is a punctuation character. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII punctuation character. <!-- ##### FUNCTION g_ascii_isspace ##### --> <para> Determines whether a character is a white-space character. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII white-space character <!-- ##### FUNCTION g_ascii_isupper ##### --> <para> Determines whether a character is an ASCII upper case letter. </para> <para> 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 <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to worry about casting to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII upper case letter <!-- ##### FUNCTION g_ascii_isxdigit ##### --> <para> Determines whether a character is a hexadecimal-digit character. </para> <para> Unlike the standard C library isxdigit() function, this takes a <type>char</type>, not an <type>int</type>, so don't call it on %EOF but no need to cast to #guchar before passing a possibly non-ASCII character in. </para> @c: any character @Returns: %TRUE if @c is an ASCII hexadecimal-digit character. <!-- ##### FUNCTION g_ascii_digit_value ##### --> <para> </para> @c: @Returns: <!-- ##### FUNCTION g_ascii_xdigit_value ##### --> <para> </para> @c: @Returns: <!-- ##### FUNCTION g_ascii_strcasecmp ##### --> <para> </para> @s1: @s2: @Returns: <!-- ##### FUNCTION g_ascii_strncasecmp ##### --> <para> </para> @s1: @s2: @n: @Returns: <!-- ##### FUNCTION g_ascii_strup ##### --> <para> </para> @str: @len: @Returns: <!-- # Unused Parameters # --> @string: <!-- ##### FUNCTION g_ascii_strdown ##### --> <para> </para> @str: @len: @Returns: <!-- ##### FUNCTION g_ascii_tolower ##### --> <para> </para> @c: @Returns: <!-- ##### FUNCTION g_ascii_toupper ##### --> <para> </para> @c: @Returns: <!-- ##### FUNCTION g_string_ascii_up ##### --> <para> </para> @string: @Returns: <!-- ##### FUNCTION g_string_ascii_down ##### --> <para> </para> @string: @Returns: <!-- ##### FUNCTION g_strup ##### --> <para> </para> @string: @Returns: <!-- ##### FUNCTION g_strdown ##### --> <para> </para> @string: @Returns: <!-- ##### FUNCTION g_strcasecmp ##### --> <para> </para> @s1: @s2: @Returns: <!-- ##### FUNCTION g_strncasecmp ##### --> <para> </para> @s1: @s2: @n: @Returns: <!-- ##### FUNCTION g_strreverse ##### --> <para> Reverses all of the bytes in a string. For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba". </para> <para> Note that g_strreverse() doesn't work on UTF-8 strings containing multibyte characters. For that purpose, use g_utf8_strreverse(). </para> @string: the string to reverse. @Returns: the same pointer passed in as @string. <!-- ##### FUNCTION g_ascii_strtoull ##### --> <para> </para> @nptr: @endptr: @base: @Returns: <!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### --> <para> 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. </para> <para> The typical usage would be something like: <informalexample><programlisting> char buf[G_ASCII_DTOSTR_BUF_SIZE]; fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value)); </programlisting></informalexample> </para> <!-- ##### FUNCTION g_ascii_strtod ##### --> <para> </para> @nptr: @endptr: @Returns: <!-- ##### FUNCTION g_ascii_dtostr ##### --> <para> </para> @buffer: @buf_len: @d: @Returns: <!-- ##### FUNCTION g_ascii_formatd ##### --> <para> </para> @buffer: @buf_len: @format: @d: @Returns: <!-- ##### FUNCTION g_strtod ##### --> <para> </para> @nptr: @endptr: @Returns: <!-- ##### FUNCTION g_strchug ##### --> <para> Removes leading whitespace from a string, by moving the rest of the characters forward. </para> @string: a string to remove the leading whitespace from. @Returns: @string. <!-- ##### FUNCTION g_strchomp ##### --> <para> Removes trailing whitespace from a string. </para> @string: a string to remove the trailing whitespace from. @Returns: @string. <!-- ##### MACRO g_strstrip ##### --> <para> Removes leading and trailing whitespace from a string. </para> @string: a string to remove the leading and trailing whitespace from. <!-- ##### FUNCTION g_strdelimit ##### --> <para> 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 <literal>g_ascii_strup (g_strdelimit (str, "abc", '?'))</literal>. </para> @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. <!-- ##### MACRO G_STR_DELIMITERS ##### --> <para> The standard delimiters, used in g_strdelimit(). </para> <!-- ##### FUNCTION g_strescape ##### --> <para> 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. </para> <para> g_strcompress() does the reverse conversion. </para> @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. <!-- ##### FUNCTION g_strcompress ##### --> <para> Replaces all escaped characters with their one byte equivalent. It does the reverse conversion of g_strescape(). </para> @source: a string to compress. @Returns: a newly-allocated copy of @source with all escaped character compressed. <!-- ##### FUNCTION g_strcanon ##### --> <para> 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 <literal>g_ascii_strup (g_strcanon (str, "abc", '?'))</literal>. </para> @string: a nul-terminated array of bytes. @valid_chars: bytes permitted in @string. @substitutor: replacement character for disallowed bytes. @Returns: @string. <!-- ##### FUNCTION g_strsplit ##### --> <para> </para> @string: @delimiter: @max_tokens: @Returns: <!-- ##### FUNCTION g_strsplit_set ##### --> <para> </para> @string: @delimiters: @max_tokens: @Returns: <!-- ##### FUNCTION g_strfreev ##### --> <para> </para> @str_array: <!-- ##### FUNCTION g_strconcat ##### --> <para> Concatenates all of the given strings into one long string. The returned string should be freed when no longer needed. </para> <warning><para> The variable argument list <emphasis>must</emphasis> end with %NULL. If you forget the %NULL, g_strconcat() will start appending random memory junk to your string. </para></warning> @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. <!-- ##### FUNCTION g_strjoin ##### --> <para> Joins a number of strings together to form one long string, with the optional @separator inserted between each of them. </para> @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. <!-- ##### FUNCTION g_strjoinv ##### --> <para> Joins a number of strings together to form one long string, with the optional @separator inserted between each of them. </para> @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. <!-- ##### FUNCTION g_strerror ##### --> <para> 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. </para> @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(). <!-- ##### FUNCTION g_strsignal ##### --> <para> Returns a string describing the given signal, e.g. "Segmentation fault". This function is included since not all platforms support the strsignal() function. </para> @signum: the signal number. See the <literal>signal</literal> 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().