+++ /dev/null
-<!-- ##### 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:
-
-
#include <signal.h>
#endif
+#ifdef G_OS_WIN32
+#include <windows.h>
+#endif
+
+/* do not include <unistd.h> here, it may interfere with g_strsignal() */
+
#include "gstrfuncs.h"
#include "gprintf.h"
#include "gthreadprivate.h"
-#ifdef G_OS_WIN32
-#include <windows.h>
-#endif
+/**
+ * SECTION:string_utils
+ * @title: String Utility Functions
+ * @short_description: 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 <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 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>
+ */
+
+/**
+ * g_ascii_isalnum:
+ * @c: any character
+ *
+ * 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII alphanumeric character
+ */
+
+/**
+ * g_ascii_isalpha:
+ * @c: any 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII alphabetic character
+ */
+
+/**
+ * g_ascii_iscntrl:
+ * @c: any 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII control character.
+ */
+
+/**
+ * g_ascii_isdigit:
+ * @c: any character
+ *
+ * Determines whether a character is digit (0-9).
+ *
+ * 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.
+ *
+ * Returns: %TRUE if @c is an ASCII digit.
+ */
+
+/**
+ * g_ascii_isgraph:
+ * @c: any character
+ *
+ * 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII printing character other than space.
+ */
+
+/**
+ * g_ascii_islower:
+ * @c: any character
+ *
+ * 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII lower case letter
+ */
+
+/**
+ * g_ascii_isprint:
+ * @c: any character
+ *
+ * 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII printing character.
+ */
+
+/**
+ * g_ascii_ispunct:
+ * @c: any 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII punctuation character.
+ */
+
+/**
+ * g_ascii_isspace:
+ * @c: any 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII white-space character
+ */
+
+/**
+ * g_ascii_isupper:
+ * @c: any 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 <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.
+ *
+ * Returns: %TRUE if @c is an ASCII upper case letter
+ */
+
+/**
+ * g_ascii_isxdigit:
+ * @c: any character
+ *
+ * Determines whether a character is a hexadecimal-digit character.
+ *
+ * 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.
+ *
+ * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
+ */
+
+/**
+ * G_ASCII_DTOSTR_BUF_SIZE:
+ *
+ * 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));
+ * ]|
+ */
-/* do not include <unistd.h> in this place since it
- * interferes with g_strsignal() on some OSes
+/**
+ * g_strstrip:
+ * @string: a string to remove the leading and trailing whitespace from
+ *
+ * Removes leading and trailing whitespace from a string.
+ * See g_strchomp() and g_strchug().
+ *
+ * Returns: @string
+ */
+
+/**
+ * G_STR_DELIMITERS:
+ *
+ * The standard delimiters, used in g_strdelimit().
*/
static const guint16 ascii_table_data[256] = {
#endif
}
-gchar*
+/**
+ * g_strdelimit:
+ * @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
+ *
+ * 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", '?'))
+ * ]|
+ *
+ * Returns: @string
+ */
+gchar *
g_strdelimit (gchar *string,
const gchar *delimiters,
gchar new_delim)
return string;
}
-gchar*
+/**
+ * g_strcanon:
+ * @string: a nul-terminated array of bytes
+ * @valid_chars: bytes permitted in @string
+ * @substitutor: replacement character for disallowed bytes
+ *
+ * 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", '?'))
+ * ]|
+ *
+ * Returns: @string
+ */
+gchar *
g_strcanon (gchar *string,
const gchar *valid_chars,
gchar substitutor)
return string;
}
-gchar*
+/**
+ * g_strcompress:
+ * @source: a string to compress
+ *
+ * Replaces all escaped characters with their one byte equivalent.
+ *
+ * This function does the reverse conversion of g_strescape().
+ *
+ * Returns: a newly-allocated copy of @source with all escaped
+ * character compressed
+ */
+gchar *
g_strcompress (const gchar *source)
{
const gchar *p = source, *octal;
return dest;
}
+/**
+ * g_strescape:
+ * @source: a string to escape
+ * @exceptions: a string of characters not to escape in @source
+ *
+ * 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.
+ *
+ * Returns: a newly-allocated copy of @source with certain
+ * characters escaped. See above.
+ */
gchar *
g_strescape (const gchar *source,
const gchar *exceptions)
return dest;
}
-gchar*
+/**
+ * g_strchug:
+ * @string: a string to remove the leading whitespace from
+ *
+ * Removes leading whitespace from a string, by moving the rest
+ * of the characters forward.
+ *
+ * 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.
+ *
+ * Also see g_strchomp() and g_strstrip().
+ *
+ * Returns: @string
+ */
+gchar *
g_strchug (gchar *string)
{
guchar *start;
return string;
}
-gchar*
+/**
+ * g_strchomp:
+ * @string: a string to remove the trailing whitespace from
+ *
+ * Removes trailing whitespace from a string.
+ *
+ * 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.
+ *
+ * Also see g_strchug() and g_strstrip().
+ *
+ * Returns: @string.
+ */
+gchar *
g_strchomp (gchar *string)
{
gsize len;
/**
* 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.
+ * @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.
*
* 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.
+ * @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
*
* Return value: a newly-allocated %NULL-terminated array of strings. Use
* g_strfreev() to free it.
- **/
+ */
gchar**
g_strsplit (const gchar *string,
const gchar *delimiter,
* g_strsplit_set:
* @string: The string to be tokenized
* @delimiters: A nul-terminated string containing bytes that are used
- * to split the string.
+ * to split the string.
* @max_tokens: The maximum number of tokens to split @string into.
- * If this is less than 1, the string is split completely
+ * If this is less than 1, the string is split completely
*
* Splits @string into a number of tokens not containing any of the characters
* in @delimiter. A token is the (possibly empty) longest string that does not
/**
* g_strfreev:
- * @str_array: a %NULL-terminated array of strings to free.
+ * @str_array: a %NULL-terminated array of strings to free
* Frees a %NULL-terminated array of strings, and the array itself.
* If called on a %NULL value, g_strfreev() simply returns.
/**
* g_strdupv:
- * @str_array: %NULL-terminated array of strings.
+ * @str_array: a %NULL-terminated array of strings
*
* Copies %NULL-terminated array of strings. The copy is a deep copy;
* the new array should be freed by first freeing each string, then
* on a %NULL value, g_strdupv() simply returns %NULL.
*
* Return value: a new %NULL-terminated array of strings.
- **/
+ */
gchar**
g_strdupv (gchar **str_array)
{
* together, with @separator between them
*/
gchar*
-g_strjoin (const gchar *separator,
+g_strjoin (const gchar *separator,
...)
{
gchar *string, *s;
/**
* g_strstr_len:
- * @haystack: a string.
+ * @haystack: a string
* @haystack_len: the maximum length of @haystack. Note that -1 is
- * a valid length, if @haystack is nul-terminated, meaning it will
- * search through the whole string.
- * @needle: the string to search for.
+ * a valid length, if @haystack is nul-terminated, meaning it will
+ * search through the whole string.
+ * @needle: the string to search for
*
* Searches the string @haystack for the first occurrence
* of the string @needle, limiting the length of the search
*
* Return value: a pointer to the found occurrence, or
* %NULL if not found.
- **/
+ */
gchar *
g_strstr_len (const gchar *haystack,
gssize haystack_len,
/**
* g_strrstr:
- * @haystack: a nul-terminated string.
- * @needle: the nul-terminated string to search for.
+ * @haystack: a nul-terminated string
+ * @needle: the nul-terminated string to search for
*
* Searches the string @haystack for the last occurrence
* of the string @needle.
*
* Return value: a pointer to the found occurrence, or
* %NULL if not found.
- **/
+ */
gchar *
g_strrstr (const gchar *haystack,
const gchar *needle)
/**
* g_strrstr_len:
- * @haystack: a nul-terminated string.
- * @haystack_len: the maximum length of @haystack.
- * @needle: the nul-terminated string to search for.
+ * @haystack: a nul-terminated string
+ * @haystack_len: the maximum length of @haystack
+ * @needle: the nul-terminated string to search for
*
* Searches the string @haystack for the last occurrence
* of the string @needle, limiting the length of the search
*
* Return value: a pointer to the found occurrence, or
* %NULL if not found.
- **/
+ */
gchar *
g_strrstr_len (const gchar *haystack,
gssize haystack_len,
/**
* g_str_has_suffix:
- * @str: a nul-terminated string.
- * @suffix: the nul-terminated suffix to look for.
+ * @str: a nul-terminated string
+ * @suffix: the nul-terminated suffix to look for
*
* Looks whether the string @str ends with @suffix.
*
* Return value: %TRUE if @str end with @suffix, %FALSE otherwise.
*
* Since: 2.2
- **/
+ */
gboolean
-g_str_has_suffix (const gchar *str,
- const gchar *suffix)
+g_str_has_suffix (const gchar *str,
+ const gchar *suffix)
{
int str_len;
int suffix_len;
/**
* g_str_has_prefix:
- * @str: a nul-terminated string.
- * @prefix: the nul-terminated prefix to look for.
+ * @str: a nul-terminated string
+ * @prefix: the nul-terminated prefix to look for
*
* Looks whether the string @str begins with @prefix.
*
* Return value: %TRUE if @str begins with @prefix, %FALSE otherwise.
*
* Since: 2.2
- **/
+ */
gboolean
-g_str_has_prefix (const gchar *str,
- const gchar *prefix)
+g_str_has_prefix (const gchar *str,
+ const gchar *prefix)
{
int str_len;
int prefix_len;
* the first '|' character is returned.
*
* Since: 2.4
- **/
+ */
const gchar *
g_strip_context (const gchar *msgid,
const gchar *msgval)
/**
* g_strv_length:
- * @str_array: a %NULL-terminated array of strings.
+ * @str_array: a %NULL-terminated array of strings
*
* Returns the length of the given %NULL-terminated
* string array @str_array.
* '\004' character to separate the message context and
* message id in @msgctxtid.
*
- * This uses g_dgettext() internally. See that functions for differences
+ * This uses g_dgettext() internally. See that functions for differences
* with dgettext() proper.
*
* This function differs from C_() in that it is not a macro and