| <!-- ##### 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 ##### --> |
| |
| |
| <!-- ##### 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> |
| <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> |
| 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_strv_length ##### --> |
| <para> |
| |
| </para> |
| |
| @str_array: |
| @Returns: |
| |
| |
| <!-- ##### 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(). |
| |
| |