| <!-- ##### 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> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### SECTION Image ##### --> |
| |
| |
| <!-- ##### FUNCTION g_strdup ##### --> |
| <para> |
| |
| </para> |
| |
| @str: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strndup ##### --> |
| <para> |
| |
| </para> |
| |
| @str: |
| @n: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strdupv ##### --> |
| <para> |
| </para> |
| |
| @str_array: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strnfill ##### --> |
| <para> |
| |
| </para> |
| |
| @length: |
| @fill_char: |
| @Returns: |
| |
| |
| <!-- ##### 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_strcmp0 ##### --> |
| <para> |
| |
| </para> |
| |
| @str1: |
| @str2: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strlcpy ##### --> |
| <para> |
| |
| </para> |
| |
| @dest: |
| @src: |
| @dest_size: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strlcat ##### --> |
| <para> |
| |
| </para> |
| |
| @dest: |
| @src: |
| @dest_size: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strdup_printf ##### --> |
| <para> |
| </para> |
| |
| @format: |
| @Varargs: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strdup_vprintf ##### --> |
| <para> |
| |
| </para> |
| |
| @format: |
| @args: |
| @Returns: |
| |
| |
| <!-- ##### 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: |
| |
| |
| <!-- ##### 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> |
| |
| </para> |
| |
| @string: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_ascii_strtoll ##### --> |
| <para> |
| |
| </para> |
| |
| @nptr: |
| @endptr: |
| @base: |
| @Returns: |
| |
| |
| <!-- ##### 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> |
| <para> |
| This function doesn't allocate or reallocate any memory; it modifies @string |
| in place. The pointer to @string is returned to allow the nesting of functions. |
| </para> |
| <para> |
| Also see g_strchomp() and g_strstrip(). |
| </para> |
| |
| @string: a string to remove the leading whitespace from. |
| @Returns: @string. |
| |
| |
| <!-- ##### FUNCTION g_strchomp ##### --> |
| <para> |
| Removes trailing whitespace from a string. |
| </para> |
| <para> |
| This function doesn't allocate or reallocate any memory; it modifies @string in |
| place. The pointer to @string is returned to allow the nesting of functions. |
| </para> |
| <para> |
| Also see g_strchug() and g_strstrip(). |
| </para> |
| |
| @string: a string to remove the trailing whitespace from. |
| @Returns: @string. |
| |
| |
| <!-- ##### MACRO g_strstrip ##### --> |
| <para> |
| Removes leading and trailing whitespace from a string. See g_strchomp() and |
| g_strchug(). |
| </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> |
| |
| </para> |
| |
| @string1: |
| @Varargs: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strjoin ##### --> |
| <para> |
| |
| </para> |
| |
| @separator: |
| @Varargs: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strjoinv ##### --> |
| <para> |
| |
| </para> |
| |
| @separator: |
| @str_array: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strv_length ##### --> |
| <para> |
| |
| </para> |
| |
| @str_array: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strerror ##### --> |
| <para> |
| |
| </para> |
| |
| @errnum: |
| @Returns: |
| |
| |
| <!-- ##### FUNCTION g_strsignal ##### --> |
| <para> |
| |
| </para> |
| |
| @signum: |
| @Returns: |
| |
| |