1 /* GLIB - Library of useful routines for C programming
2 * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
22 * file for a list of people on the GLib Team. See the ChangeLog
23 * files for a list of changes. These files are distributed with
24 * GLib at ftp://ftp.gtk.org/pub/gtk/.
40 #include <ctype.h> /* For tolower() */
46 /* do not include <unistd.h> here, it may interfere with g_strsignal() */
48 #include "gstrfuncs.h"
51 #include "gprintfint.h"
53 #include "gthreadprivate.h"
57 * SECTION:string_utils
58 * @title: String Utility Functions
59 * @short_description: various string-related functions
61 * This section describes a number of utility functions for creating,
62 * duplicating, and manipulating strings.
64 * Note that the functions g_printf(), g_fprintf(), g_sprintf(),
65 * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
66 * are declared in the header <filename>gprintf.h</filename> which is
67 * <emphasis>not</emphasis> included in <filename>glib.h</filename>
68 * (otherwise using <filename>glib.h</filename> would drag in
69 * <filename>stdio.h</filename>), so you'll have to explicitly include
70 * <literal><glib/gprintf.h></literal> in order to use the GLib
73 * <para id="string-precision">While you may use the printf() functions
74 * to format UTF-8 strings, notice that the precision of a
75 * <literal>%Ns</literal> parameter is interpreted as the
76 * number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis>
77 * to print. On top of that, the GNU libc implementation of the printf()
78 * functions has the "feature" that it checks that the string given for
79 * the <literal>%Ns</literal> parameter consists of a whole number
80 * of characters in the current encoding. So, unless you are sure you are
81 * always going to be in an UTF-8 locale or your know your text is restricted
82 * to ASCII, avoid using <literal>%Ns</literal>. If your intention is
83 * to format strings for a certain number of columns, then
84 * <literal>%Ns</literal> is not a correct solution anyway, since it
85 * fails to take wide characters (see g_unichar_iswide()) into account.
93 * Determines whether a character is alphanumeric.
95 * Unlike the standard C library isalnum() function, this only
96 * recognizes standard ASCII letters and ignores the locale,
97 * returning %FALSE for all non-ASCII characters. Also, unlike
98 * the standard library function, this takes a <type>char</type>,
99 * not an <type>int</type>, so don't call it on %EOF, but no need to
100 * cast to #guchar before passing a possibly non-ASCII character in.
102 * Returns: %TRUE if @c is an ASCII alphanumeric character
109 * Determines whether a character is alphabetic (i.e. a letter).
111 * Unlike the standard C library isalpha() function, this only
112 * recognizes standard ASCII letters and ignores the locale,
113 * returning %FALSE for all non-ASCII characters. Also, unlike
114 * the standard library function, this takes a <type>char</type>,
115 * not an <type>int</type>, so don't call it on %EOF, but no need to
116 * cast to #guchar before passing a possibly non-ASCII character in.
118 * Returns: %TRUE if @c is an ASCII alphabetic character
125 * Determines whether a character is a control character.
127 * Unlike the standard C library iscntrl() function, this only
128 * recognizes standard ASCII control characters and ignores the
129 * locale, returning %FALSE for all non-ASCII characters. Also,
130 * unlike the standard library function, this takes a <type>char</type>,
131 * not an <type>int</type>, so don't call it on %EOF, but no need to
132 * cast to #guchar before passing a possibly non-ASCII character in.
134 * Returns: %TRUE if @c is an ASCII control character.
141 * Determines whether a character is digit (0-9).
143 * Unlike the standard C library isdigit() function, this takes
144 * a <type>char</type>, not an <type>int</type>, so don't call it
145 * on %EOF, but no need to cast to #guchar before passing a possibly
146 * non-ASCII character in.
148 * Returns: %TRUE if @c is an ASCII digit.
155 * Determines whether a character is a printing character and not a space.
157 * Unlike the standard C library isgraph() function, this only
158 * recognizes standard ASCII characters and ignores the locale,
159 * returning %FALSE for all non-ASCII characters. Also, unlike
160 * the standard library function, this takes a <type>char</type>,
161 * not an <type>int</type>, so don't call it on %EOF, but no need
162 * to cast to #guchar before passing a possibly non-ASCII character in.
164 * Returns: %TRUE if @c is an ASCII printing character other than space.
171 * Determines whether a character is an ASCII lower case letter.
173 * Unlike the standard C library islower() function, this only
174 * recognizes standard ASCII letters and ignores the locale,
175 * returning %FALSE for all non-ASCII characters. Also, unlike
176 * the standard library function, this takes a <type>char</type>,
177 * not an <type>int</type>, so don't call it on %EOF, but no need
178 * to worry about casting to #guchar before passing a possibly
179 * non-ASCII character in.
181 * Returns: %TRUE if @c is an ASCII lower case letter
188 * Determines whether a character is a printing character.
190 * Unlike the standard C library isprint() function, this only
191 * recognizes standard ASCII characters and ignores the locale,
192 * returning %FALSE for all non-ASCII characters. Also, unlike
193 * the standard library function, this takes a <type>char</type>,
194 * not an <type>int</type>, so don't call it on %EOF, but no need
195 * to cast to #guchar before passing a possibly non-ASCII character in.
197 * Returns: %TRUE if @c is an ASCII printing character.
204 * Determines whether a character is a punctuation character.
206 * Unlike the standard C library ispunct() function, this only
207 * recognizes standard ASCII letters and ignores the locale,
208 * returning %FALSE for all non-ASCII characters. Also, unlike
209 * the standard library function, this takes a <type>char</type>,
210 * not an <type>int</type>, so don't call it on %EOF, but no need to
211 * cast to #guchar before passing a possibly non-ASCII character in.
213 * Returns: %TRUE if @c is an ASCII punctuation character.
220 * Determines whether a character is a white-space character.
222 * Unlike the standard C library isspace() function, this only
223 * recognizes standard ASCII white-space and ignores the locale,
224 * returning %FALSE for all non-ASCII characters. Also, unlike
225 * the standard library function, this takes a <type>char</type>,
226 * not an <type>int</type>, so don't call it on %EOF, but no need to
227 * cast to #guchar before passing a possibly non-ASCII character in.
229 * Returns: %TRUE if @c is an ASCII white-space character
236 * Determines whether a character is an ASCII upper case letter.
238 * Unlike the standard C library isupper() function, this only
239 * recognizes standard ASCII letters and ignores the locale,
240 * returning %FALSE for all non-ASCII characters. Also, unlike
241 * the standard library function, this takes a <type>char</type>,
242 * not an <type>int</type>, so don't call it on %EOF, but no need to
243 * worry about casting to #guchar before passing a possibly non-ASCII
246 * Returns: %TRUE if @c is an ASCII upper case letter
253 * Determines whether a character is a hexadecimal-digit character.
255 * Unlike the standard C library isxdigit() function, this takes
256 * a <type>char</type>, not an <type>int</type>, so don't call it
257 * on %EOF, but no need to cast to #guchar before passing a
258 * possibly non-ASCII character in.
260 * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
264 * G_ASCII_DTOSTR_BUF_SIZE:
266 * A good size for a buffer to be passed into g_ascii_dtostr().
267 * It is guaranteed to be enough for all output of that function
268 * on systems with 64bit IEEE-compatible doubles.
270 * The typical usage would be something like:
272 * char buf[G_ASCII_DTOSTR_BUF_SIZE];
274 * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
280 * @string: a string to remove the leading and trailing whitespace from
282 * Removes leading and trailing whitespace from a string.
283 * See g_strchomp() and g_strchug().
291 * The standard delimiters, used in g_strdelimit().
294 static const guint16 ascii_table_data[256] = {
295 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
296 0x004, 0x104, 0x104, 0x004, 0x104, 0x104, 0x004, 0x004,
297 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
298 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
299 0x140, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
300 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
301 0x459, 0x459, 0x459, 0x459, 0x459, 0x459, 0x459, 0x459,
302 0x459, 0x459, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
303 0x0d0, 0x653, 0x653, 0x653, 0x653, 0x653, 0x653, 0x253,
304 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253,
305 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253,
306 0x253, 0x253, 0x253, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
307 0x0d0, 0x473, 0x473, 0x473, 0x473, 0x473, 0x473, 0x073,
308 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073,
309 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073,
310 0x073, 0x073, 0x073, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x004
311 /* the upper 128 are all zeroes */
314 const guint16 * const g_ascii_table = ascii_table_data;
316 #ifdef HAVE_NEWLOCALE
320 static gsize initialized = FALSE;
321 static locale_t C_locale = NULL;
323 if (g_once_init_enter (&initialized))
325 C_locale = newlocale (LC_ALL_MASK, "C", NULL);
326 g_once_init_leave (&initialized, TRUE);
335 * @str: the string to duplicate
337 * Duplicates a string. If @str is %NULL it returns %NULL.
338 * The returned string should be freed with g_free()
339 * when no longer needed.
341 * Returns: a newly-allocated copy of @str
344 g_strdup (const gchar *str)
351 length = strlen (str) + 1;
352 new_str = g_new (char, length);
353 memcpy (new_str, str, length);
363 * @mem: the memory to copy.
364 * @byte_size: the number of bytes to copy.
366 * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
367 * from @mem. If @mem is %NULL it returns %NULL.
369 * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
373 g_memdup (gconstpointer mem,
380 new_mem = g_malloc (byte_size);
381 memcpy (new_mem, mem, byte_size);
391 * @str: the string to duplicate
392 * @n: the maximum number of bytes to copy from @str
394 * Duplicates the first @n bytes of a string, returning a newly-allocated
395 * buffer @n + 1 bytes long which will always be nul-terminated.
396 * If @str is less than @n bytes long the buffer is padded with nuls.
397 * If @str is %NULL it returns %NULL.
398 * The returned value should be freed when no longer needed.
401 * To copy a number of characters from a UTF-8 encoded string, use
402 * g_utf8_strncpy() instead.
405 * Returns: a newly-allocated buffer containing the first @n bytes
406 * of @str, nul-terminated
409 g_strndup (const gchar *str,
416 new_str = g_new (gchar, n + 1);
417 strncpy (new_str, str, n);
428 * @length: the length of the new string
429 * @fill_char: the byte to fill the string with
431 * Creates a new string @length bytes long filled with @fill_char.
432 * The returned string should be freed when no longer needed.
434 * Returns: a newly-allocated string filled the @fill_char
437 g_strnfill (gsize length,
442 str = g_new (gchar, length + 1);
443 memset (str, (guchar)fill_char, length);
451 * @dest: destination buffer.
452 * @src: source string.
454 * Copies a nul-terminated string into the dest buffer, include the
455 * trailing nul, and return a pointer to the trailing nul byte.
456 * This is useful for concatenating multiple strings together
457 * without having to repeatedly scan for the end.
459 * Return value: a pointer to trailing nul byte.
462 g_stpcpy (gchar *dest,
466 g_return_val_if_fail (dest != NULL, NULL);
467 g_return_val_if_fail (src != NULL, NULL);
468 return stpcpy (dest, src);
470 register gchar *d = dest;
471 register const gchar *s = src;
473 g_return_val_if_fail (dest != NULL, NULL);
474 g_return_val_if_fail (src != NULL, NULL);
477 while (*s++ != '\0');
485 * @format: a standard printf() format string, but notice
486 * <link linkend="string-precision">string precision pitfalls</link>
487 * @args: the list of parameters to insert into the format string
489 * Similar to the standard C vsprintf() function but safer, since it
490 * calculates the maximum space required and allocates memory to hold
491 * the result. The returned string should be freed with g_free() when
494 * See also g_vasprintf(), which offers the same functionality, but
495 * additionally returns the length of the allocated string.
497 * Returns: a newly-allocated string holding the result
500 g_strdup_vprintf (const gchar *format,
503 gchar *string = NULL;
505 g_vasprintf (&string, format, args);
512 * @format: a standard printf() format string, but notice
513 * <link linkend="string-precision">string precision pitfalls</link>
514 * @...: the parameters to insert into the format string
516 * Similar to the standard C sprintf() function but safer, since it
517 * calculates the maximum space required and allocates memory to hold
518 * the result. The returned string should be freed with g_free() when no
521 * Returns: a newly-allocated string holding the result
524 g_strdup_printf (const gchar *format,
530 va_start (args, format);
531 buffer = g_strdup_vprintf (format, args);
539 * @string1: the first string to add, which must not be %NULL
540 * @...: a %NULL-terminated list of strings to append to the string
542 * Concatenates all of the given strings into one long string.
543 * The returned string should be freed with g_free() when no longer needed.
545 * Note that this function is usually not the right function to use to
546 * assemble a translated message from pieces, since proper translation
547 * often requires the pieces to be reordered.
549 * <warning><para>The variable argument list <emphasis>must</emphasis> end
550 * with %NULL. If you forget the %NULL, g_strconcat() will start appending
551 * random memory junk to your string.</para></warning>
553 * Returns: a newly-allocated string containing all the string arguments
556 g_strconcat (const gchar *string1, ...)
567 l = 1 + strlen (string1);
568 va_start (args, string1);
569 s = va_arg (args, gchar*);
573 s = va_arg (args, gchar*);
577 concat = g_new (gchar, l);
580 ptr = g_stpcpy (ptr, string1);
581 va_start (args, string1);
582 s = va_arg (args, gchar*);
585 ptr = g_stpcpy (ptr, s);
586 s = va_arg (args, gchar*);
595 * @nptr: the string to convert to a numeric value.
596 * @endptr: if non-%NULL, it returns the character after
597 * the last character used in the conversion.
599 * Converts a string to a #gdouble value.
600 * It calls the standard strtod() function to handle the conversion, but
601 * if the string is not completely converted it attempts the conversion
602 * again with g_ascii_strtod(), and returns the best match.
604 * This function should seldom be used. The normal situation when reading
605 * numbers not for human consumption is to use g_ascii_strtod(). Only when
606 * you know that you must expect both locale formatted and C formatted numbers
607 * should you use this. Make sure that you don't pass strings such as comma
608 * separated lists of values, since the commas may be interpreted as a decimal
609 * point in some locales, causing unexpected results.
611 * Return value: the #gdouble value.
614 g_strtod (const gchar *nptr,
622 g_return_val_if_fail (nptr != NULL, 0);
627 val_1 = strtod (nptr, &fail_pos_1);
629 if (fail_pos_1 && fail_pos_1[0] != 0)
630 val_2 = g_ascii_strtod (nptr, &fail_pos_2);
632 if (!fail_pos_1 || fail_pos_1[0] == 0 || fail_pos_1 >= fail_pos_2)
635 *endptr = fail_pos_1;
641 *endptr = fail_pos_2;
648 * @nptr: the string to convert to a numeric value.
649 * @endptr: if non-%NULL, it returns the character after
650 * the last character used in the conversion.
652 * Converts a string to a #gdouble value.
654 * This function behaves like the standard strtod() function
655 * does in the C locale. It does this without actually changing
656 * the current locale, since that would not be thread-safe.
657 * A limitation of the implementation is that this function
658 * will still accept localized versions of infinities and NANs.
660 * This function is typically used when reading configuration
661 * files or other non-user input that should be locale independent.
662 * To handle input from the user you should normally use the
663 * locale-sensitive system strtod() function.
665 * To convert from a #gdouble to a string in a locale-insensitive
666 * way, use g_ascii_dtostr().
668 * If the correct value would cause overflow, plus or minus %HUGE_VAL
669 * is returned (according to the sign of the value), and %ERANGE is
670 * stored in %errno. If the correct value would cause underflow,
671 * zero is returned and %ERANGE is stored in %errno.
673 * This function resets %errno before calling strtod() so that
674 * you can reliably detect overflow and underflow.
676 * Return value: the #gdouble value.
679 g_ascii_strtod (const gchar *nptr,
683 return strtod_l (nptr, endptr, get_C_locale ());
687 struct lconv *locale_data;
688 const char *decimal_point;
689 int decimal_point_len;
690 const char *p, *decimal_point_pos;
691 const char *end = NULL; /* Silence gcc */
694 g_return_val_if_fail (nptr != NULL, 0);
698 locale_data = localeconv ();
699 decimal_point = locale_data->decimal_point;
700 decimal_point_len = strlen (decimal_point);
702 g_assert (decimal_point_len != 0);
704 decimal_point_pos = NULL;
707 if (decimal_point[0] != '.' ||
708 decimal_point[1] != 0)
711 /* Skip leading space */
712 while (g_ascii_isspace (*p))
715 /* Skip leading optional sign */
716 if (*p == '+' || *p == '-')
720 (p[1] == 'x' || p[1] == 'X'))
723 /* HEX - find the (optional) decimal point */
725 while (g_ascii_isxdigit (*p))
729 decimal_point_pos = p++;
731 while (g_ascii_isxdigit (*p))
734 if (*p == 'p' || *p == 'P')
736 if (*p == '+' || *p == '-')
738 while (g_ascii_isdigit (*p))
743 else if (g_ascii_isdigit (*p) || *p == '.')
745 while (g_ascii_isdigit (*p))
749 decimal_point_pos = p++;
751 while (g_ascii_isdigit (*p))
754 if (*p == 'e' || *p == 'E')
756 if (*p == '+' || *p == '-')
758 while (g_ascii_isdigit (*p))
763 /* For the other cases, we need not convert the decimal point */
766 if (decimal_point_pos)
770 /* We need to convert the '.' to the locale specific decimal point */
771 copy = g_malloc (end - nptr + 1 + decimal_point_len);
774 memcpy (c, nptr, decimal_point_pos - nptr);
775 c += decimal_point_pos - nptr;
776 memcpy (c, decimal_point, decimal_point_len);
777 c += decimal_point_len;
778 memcpy (c, decimal_point_pos + 1, end - (decimal_point_pos + 1));
779 c += end - (decimal_point_pos + 1);
783 val = strtod (copy, &fail_pos);
784 strtod_errno = errno;
788 if (fail_pos - copy > decimal_point_pos - nptr)
789 fail_pos = (char *)nptr + (fail_pos - copy) - (decimal_point_len - 1);
791 fail_pos = (char *)nptr + (fail_pos - copy);
801 copy = g_malloc (end - (char *)nptr + 1);
802 memcpy (copy, nptr, end - nptr);
803 *(copy + (end - (char *)nptr)) = 0;
806 val = strtod (copy, &fail_pos);
807 strtod_errno = errno;
811 fail_pos = (char *)nptr + (fail_pos - copy);
819 val = strtod (nptr, &fail_pos);
820 strtod_errno = errno;
826 errno = strtod_errno;
835 * @buffer: A buffer to place the resulting string in
836 * @buf_len: The length of the buffer.
837 * @d: The #gdouble to convert
839 * Converts a #gdouble to a string, using the '.' as
842 * This functions generates enough precision that converting
843 * the string back using g_ascii_strtod() gives the same machine-number
844 * (on machines with IEEE compatible 64bit doubles). It is
845 * guaranteed that the size of the resulting string will never
846 * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes.
848 * Return value: The pointer to the buffer with the converted string.
851 g_ascii_dtostr (gchar *buffer,
855 return g_ascii_formatd (buffer, buf_len, "%.17g", d);
860 * @buffer: A buffer to place the resulting string in
861 * @buf_len: The length of the buffer.
862 * @format: The printf()-style format to use for the
863 * code to use for converting.
864 * @d: The #gdouble to convert
866 * Converts a #gdouble to a string, using the '.' as
867 * decimal point. To format the number you pass in
868 * a printf()-style format string. Allowed conversion
869 * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
871 * If you just want to want to serialize the value into a
872 * string, use g_ascii_dtostr().
874 * Return value: The pointer to the buffer with the converted string.
877 g_ascii_formatd (gchar *buffer,
882 #ifdef HAVE_USELOCALE
885 old_locale = uselocale (get_C_locale ());
886 _g_snprintf (buffer, buf_len, format, d);
887 uselocale (old_locale);
891 struct lconv *locale_data;
892 const char *decimal_point;
893 int decimal_point_len;
898 g_return_val_if_fail (buffer != NULL, NULL);
899 g_return_val_if_fail (format[0] == '%', NULL);
900 g_return_val_if_fail (strpbrk (format + 1, "'l%") == NULL, NULL);
902 format_char = format[strlen (format) - 1];
904 g_return_val_if_fail (format_char == 'e' || format_char == 'E' ||
905 format_char == 'f' || format_char == 'F' ||
906 format_char == 'g' || format_char == 'G',
909 if (format[0] != '%')
912 if (strpbrk (format + 1, "'l%"))
915 if (!(format_char == 'e' || format_char == 'E' ||
916 format_char == 'f' || format_char == 'F' ||
917 format_char == 'g' || format_char == 'G'))
920 _g_snprintf (buffer, buf_len, format, d);
922 locale_data = localeconv ();
923 decimal_point = locale_data->decimal_point;
924 decimal_point_len = strlen (decimal_point);
926 g_assert (decimal_point_len != 0);
928 if (decimal_point[0] != '.' ||
929 decimal_point[1] != 0)
933 while (g_ascii_isspace (*p))
936 if (*p == '+' || *p == '-')
939 while (isdigit ((guchar)*p))
942 if (strncmp (p, decimal_point, decimal_point_len) == 0)
946 if (decimal_point_len > 1)
948 rest_len = strlen (p + (decimal_point_len-1));
949 memmove (p, p + (decimal_point_len-1), rest_len);
959 #define ISSPACE(c) ((c) == ' ' || (c) == '\f' || (c) == '\n' || \
960 (c) == '\r' || (c) == '\t' || (c) == '\v')
961 #define ISUPPER(c) ((c) >= 'A' && (c) <= 'Z')
962 #define ISLOWER(c) ((c) >= 'a' && (c) <= 'z')
963 #define ISALPHA(c) (ISUPPER (c) || ISLOWER (c))
964 #define TOUPPER(c) (ISLOWER (c) ? (c) - 'a' + 'A' : (c))
965 #define TOLOWER(c) (ISUPPER (c) ? (c) - 'A' + 'a' : (c))
967 #if !defined(HAVE_STRTOLL_L) || !defined(HAVE_STRTOULL_L)
970 g_parse_long_long (const gchar *nptr,
971 const gchar **endptr,
975 /* this code is based on on the strtol(3) code from GNU libc released under
976 * the GNU Lesser General Public License.
978 * Copyright (C) 1991,92,94,95,96,97,98,99,2000,01,02
979 * Free Software Foundation, Inc.
985 const gchar *s, *save;
988 g_return_val_if_fail (nptr != NULL, 0);
991 if (base == 1 || base > 36)
1001 /* Skip white space. */
1002 while (ISSPACE (*s))
1005 if (G_UNLIKELY (!*s))
1008 /* Check for a sign. */
1017 /* Recognize number prefix and if BASE is zero, figure it out ourselves. */
1020 if ((base == 0 || base == 16) && TOUPPER (s[1]) == 'X')
1031 /* Save the pointer so we can check later if anything happened. */
1033 cutoff = G_MAXUINT64 / base;
1034 cutlim = G_MAXUINT64 % base;
1041 if (c >= '0' && c <= '9')
1043 else if (ISALPHA (c))
1044 c = TOUPPER (c) - 'A' + 10;
1049 /* Check for overflow. */
1050 if (ui64 > cutoff || (ui64 == cutoff && c > cutlim))
1059 /* Check if anything actually happened. */
1063 /* Store in ENDPTR the address of one character
1064 past the last character we converted. */
1068 if (G_UNLIKELY (overflow))
1077 /* We must handle a special case here: the base is 0 or 16 and the
1078 first two characters are '0' and 'x', but the rest are no
1079 hexadecimal digits. This is no error case. We return 0 and
1080 ENDPTR points to the `x`. */
1083 if (save - nptr >= 2 && TOUPPER (save[-1]) == 'X'
1085 *endptr = &save[-1];
1087 /* There was no number to convert. */
1096 * @nptr: the string to convert to a numeric value.
1097 * @endptr: if non-%NULL, it returns the character after
1098 * the last character used in the conversion.
1099 * @base: to be used for the conversion, 2..36 or 0
1101 * Converts a string to a #guint64 value.
1102 * This function behaves like the standard strtoull() function
1103 * does in the C locale. It does this without actually
1104 * changing the current locale, since that would not be
1107 * This function is typically used when reading configuration
1108 * files or other non-user input that should be locale independent.
1109 * To handle input from the user you should normally use the
1110 * locale-sensitive system strtoull() function.
1112 * If the correct value would cause overflow, %G_MAXUINT64
1113 * is returned, and %ERANGE is stored in %errno. If the base is
1114 * outside the valid range, zero is returned, and %EINVAL is stored
1115 * in %errno. If the string conversion fails, zero is returned, and
1116 * @endptr returns @nptr (if @endptr is non-%NULL).
1118 * Return value: the #guint64 value or zero on error.
1123 g_ascii_strtoull (const gchar *nptr,
1127 #ifdef HAVE_STRTOULL_L
1128 return strtoull_l (nptr, endptr, base, get_C_locale ());
1133 result = g_parse_long_long (nptr, (const gchar **) endptr, base, &negative);
1135 /* Return the result of the appropriate sign. */
1136 return negative ? -result : result;
1142 * @nptr: the string to convert to a numeric value.
1143 * @endptr: if non-%NULL, it returns the character after
1144 * the last character used in the conversion.
1145 * @base: to be used for the conversion, 2..36 or 0
1147 * Converts a string to a #gint64 value.
1148 * This function behaves like the standard strtoll() function
1149 * does in the C locale. It does this without actually
1150 * changing the current locale, since that would not be
1153 * This function is typically used when reading configuration
1154 * files or other non-user input that should be locale independent.
1155 * To handle input from the user you should normally use the
1156 * locale-sensitive system strtoll() function.
1158 * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
1159 * is returned, and %ERANGE is stored in %errno. If the base is
1160 * outside the valid range, zero is returned, and %EINVAL is stored
1161 * in %errno. If the string conversion fails, zero is returned, and
1162 * @endptr returns @nptr (if @endptr is non-%NULL).
1164 * Return value: the #gint64 value or zero on error.
1169 g_ascii_strtoll (const gchar *nptr,
1173 #ifdef HAVE_STRTOLL_L
1174 return strtoll_l (nptr, endptr, base, get_C_locale ());
1179 result = g_parse_long_long (nptr, (const gchar **) endptr, base, &negative);
1181 if (negative && result > (guint64) G_MININT64)
1186 else if (!negative && result > (guint64) G_MAXINT64)
1192 return - (gint64) result;
1194 return (gint64) result;
1200 * @errnum: the system error number. See the standard C %errno
1203 * Returns a string corresponding to the given error code, e.g.
1204 * "no such process". You should use this function in preference to
1205 * strerror(), because it returns a string in UTF-8 encoding, and since
1206 * not all platforms support the strerror() function.
1208 * Returns: a UTF-8 string describing the error code. If the error code
1209 * is unknown, it returns "unknown error (<code>)".
1212 g_strerror (gint errnum)
1218 gint saved_errno = errno;
1220 msg = tofree = NULL;
1222 #ifdef HAVE_STRERROR
1223 msg = strerror (errnum);
1224 if (!g_get_charset (NULL))
1225 msg = tofree = g_locale_to_utf8 (msg, -1, NULL, NULL, NULL);
1231 _g_sprintf (msg, "unknown error (%d)", errnum);
1234 ret = g_intern_string (msg);
1236 errno = saved_errno;
1242 * @signum: the signal number. See the <literal>signal</literal>
1245 * Returns a string describing the given signal, e.g. "Segmentation fault".
1246 * You should use this function in preference to strsignal(), because it
1247 * returns a string in UTF-8 encoding, and since not all platforms support
1248 * the strsignal() function.
1250 * Returns: a UTF-8 string describing the signal. If the signal is unknown,
1251 * it returns "unknown signal (<signum>)".
1254 g_strsignal (gint signum)
1260 msg = tofree = NULL;
1262 #ifdef HAVE_STRSIGNAL
1263 msg = strsignal (signum);
1264 if (!g_get_charset (NULL))
1265 msg = tofree = g_locale_to_utf8 (msg, -1, NULL, NULL, NULL);
1269 msg = tofree = g_strdup_printf ("unknown signal (%d)", signum);
1270 ret = g_intern_string (msg);
1276 /* Functions g_strlcpy and g_strlcat were originally developed by
1277 * Todd C. Miller <Todd.Miller@courtesan.com> to simplify writing secure code.
1278 * See http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
1279 * for more information.
1283 /* Use the native ones, if available; they might be implemented in assembly */
1285 g_strlcpy (gchar *dest,
1289 g_return_val_if_fail (dest != NULL, 0);
1290 g_return_val_if_fail (src != NULL, 0);
1292 return strlcpy (dest, src, dest_size);
1296 g_strlcat (gchar *dest,
1300 g_return_val_if_fail (dest != NULL, 0);
1301 g_return_val_if_fail (src != NULL, 0);
1303 return strlcat (dest, src, dest_size);
1306 #else /* ! HAVE_STRLCPY */
1309 * @dest: destination buffer
1310 * @src: source buffer
1311 * @dest_size: length of @dest in bytes
1313 * Portability wrapper that calls strlcpy() on systems which have it,
1314 * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
1315 * guaranteed to be nul-terminated; @src must be nul-terminated;
1316 * @dest_size is the buffer size, not the number of chars to copy.
1318 * At most dest_size - 1 characters will be copied. Always nul-terminates
1319 * (unless dest_size == 0). This function does <emphasis>not</emphasis>
1320 * allocate memory. Unlike strncpy(), this function doesn't pad dest (so
1321 * it's often faster). It returns the size of the attempted result,
1322 * strlen (src), so if @retval >= @dest_size, truncation occurred.
1324 * <note><para>Caveat: strlcpy() is supposedly more secure than
1325 * strcpy() or strncpy(), but if you really want to avoid screwups,
1326 * g_strdup() is an even better idea.</para></note>
1328 * Returns: length of @src
1331 g_strlcpy (gchar *dest,
1335 register gchar *d = dest;
1336 register const gchar *s = src;
1337 register gsize n = dest_size;
1339 g_return_val_if_fail (dest != NULL, 0);
1340 g_return_val_if_fail (src != NULL, 0);
1342 /* Copy as many bytes as will fit */
1343 if (n != 0 && --n != 0)
1346 register gchar c = *s++;
1354 /* If not enough room in dest, add NUL and traverse rest of src */
1363 return s - src - 1; /* count does not include NUL */
1368 * @dest: destination buffer, already containing one nul-terminated string
1369 * @src: source buffer
1370 * @dest_size: length of @dest buffer in bytes (not length of existing string
1373 * Portability wrapper that calls strlcat() on systems which have it,
1374 * and emulates it otherwise. Appends nul-terminated @src string to @dest,
1375 * guaranteeing nul-termination for @dest. The total size of @dest won't
1376 * exceed @dest_size.
1378 * At most dest_size - 1 characters will be copied.
1379 * Unlike strncat, dest_size is the full size of dest, not the space left over.
1380 * This function does NOT allocate memory.
1381 * This always NUL terminates (unless siz == 0 or there were no NUL characters
1382 * in the dest_size characters of dest to start with).
1384 * <note><para>Caveat: this is supposedly a more secure alternative to
1385 * strcat() or strncat(), but for real security g_strconcat() is harder
1386 * to mess up.</para></note>
1388 * Returns: size of attempted result, which is MIN (dest_size, strlen
1389 * (original dest)) + strlen (src), so if retval >= dest_size,
1390 * truncation occurred.
1393 g_strlcat (gchar *dest,
1397 register gchar *d = dest;
1398 register const gchar *s = src;
1399 register gsize bytes_left = dest_size;
1400 gsize dlength; /* Logically, MIN (strlen (d), dest_size) */
1402 g_return_val_if_fail (dest != NULL, 0);
1403 g_return_val_if_fail (src != NULL, 0);
1405 /* Find the end of dst and adjust bytes left but don't go past end */
1406 while (*d != 0 && bytes_left-- != 0)
1409 bytes_left = dest_size - dlength;
1411 if (bytes_left == 0)
1412 return dlength + strlen (s);
1416 if (bytes_left != 1)
1425 return dlength + (s - src); /* count does not include NUL */
1427 #endif /* ! HAVE_STRLCPY */
1432 * @len: length of @str in bytes, or -1 if @str is nul-terminated.
1434 * Converts all upper case ASCII letters to lower case ASCII letters.
1436 * Return value: a newly-allocated string, with all the upper case
1437 * characters in @str converted to lower case, with
1438 * semantics that exactly match g_ascii_tolower(). (Note
1439 * that this is unlike the old g_strdown(), which modified
1440 * the string in place.)
1443 g_ascii_strdown (const gchar *str,
1448 g_return_val_if_fail (str != NULL, NULL);
1453 result = g_strndup (str, len);
1454 for (s = result; *s; s++)
1455 *s = g_ascii_tolower (*s);
1463 * @len: length of @str in bytes, or -1 if @str is nul-terminated.
1465 * Converts all lower case ASCII letters to upper case ASCII letters.
1467 * Return value: a newly allocated string, with all the lower case
1468 * characters in @str converted to upper case, with
1469 * semantics that exactly match g_ascii_toupper(). (Note
1470 * that this is unlike the old g_strup(), which modified
1471 * the string in place.)
1474 g_ascii_strup (const gchar *str,
1479 g_return_val_if_fail (str != NULL, NULL);
1484 result = g_strndup (str, len);
1485 for (s = result; *s; s++)
1486 *s = g_ascii_toupper (*s);
1493 * @string: the string to convert.
1495 * Converts a string to lower case.
1497 * Return value: the string
1499 * Deprecated:2.2: This function is totally broken for the reasons discussed
1500 * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
1504 g_strdown (gchar *string)
1508 g_return_val_if_fail (string != NULL, NULL);
1510 s = (guchar *) string;
1519 return (gchar *) string;
1524 * @string: the string to convert.
1526 * Converts a string to upper case.
1528 * Return value: the string
1530 * Deprecated:2.2: This function is totally broken for the reasons discussed
1531 * in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
1534 g_strup (gchar *string)
1538 g_return_val_if_fail (string != NULL, NULL);
1540 s = (guchar *) string;
1549 return (gchar *) string;
1554 * @string: the string to reverse
1556 * Reverses all of the bytes in a string. For example,
1557 * <literal>g_strreverse ("abcdef")</literal> will result
1560 * Note that g_strreverse() doesn't work on UTF-8 strings
1561 * containing multibyte characters. For that purpose, use
1562 * g_utf8_strreverse().
1564 * Returns: the same pointer passed in as @string
1567 g_strreverse (gchar *string)
1569 g_return_val_if_fail (string != NULL, NULL);
1573 register gchar *h, *t;
1576 t = string + strlen (string) - 1;
1595 * @c: any character.
1597 * Convert a character to ASCII lower case.
1599 * Unlike the standard C library tolower() function, this only
1600 * recognizes standard ASCII letters and ignores the locale, returning
1601 * all non-ASCII characters unchanged, even if they are lower case
1602 * letters in a particular character set. Also unlike the standard
1603 * library function, this takes and returns a char, not an int, so
1604 * don't call it on %EOF but no need to worry about casting to #guchar
1605 * before passing a possibly non-ASCII character in.
1607 * Return value: the result of converting @c to lower case.
1608 * If @c is not an ASCII upper case letter,
1609 * @c is returned unchanged.
1612 g_ascii_tolower (gchar c)
1614 return g_ascii_isupper (c) ? c - 'A' + 'a' : c;
1619 * @c: any character.
1621 * Convert a character to ASCII upper case.
1623 * Unlike the standard C library toupper() function, this only
1624 * recognizes standard ASCII letters and ignores the locale, returning
1625 * all non-ASCII characters unchanged, even if they are upper case
1626 * letters in a particular character set. Also unlike the standard
1627 * library function, this takes and returns a char, not an int, so
1628 * don't call it on %EOF but no need to worry about casting to #guchar
1629 * before passing a possibly non-ASCII character in.
1631 * Return value: the result of converting @c to upper case.
1632 * If @c is not an ASCII lower case letter,
1633 * @c is returned unchanged.
1636 g_ascii_toupper (gchar c)
1638 return g_ascii_islower (c) ? c - 'a' + 'A' : c;
1642 * g_ascii_digit_value:
1643 * @c: an ASCII character.
1645 * Determines the numeric value of a character as a decimal
1646 * digit. Differs from g_unichar_digit_value() because it takes
1647 * a char, so there's no worry about sign extension if characters
1650 * Return value: If @c is a decimal digit (according to
1651 * g_ascii_isdigit()), its numeric value. Otherwise, -1.
1654 g_ascii_digit_value (gchar c)
1656 if (g_ascii_isdigit (c))
1662 * g_ascii_xdigit_value:
1663 * @c: an ASCII character.
1665 * Determines the numeric value of a character as a hexidecimal
1666 * digit. Differs from g_unichar_xdigit_value() because it takes
1667 * a char, so there's no worry about sign extension if characters
1670 * Return value: If @c is a hex digit (according to
1671 * g_ascii_isxdigit()), its numeric value. Otherwise, -1.
1674 g_ascii_xdigit_value (gchar c)
1676 if (c >= 'A' && c <= 'F')
1677 return c - 'A' + 10;
1678 if (c >= 'a' && c <= 'f')
1679 return c - 'a' + 10;
1680 return g_ascii_digit_value (c);
1684 * g_ascii_strcasecmp:
1685 * @s1: string to compare with @s2.
1686 * @s2: string to compare with @s1.
1688 * Compare two strings, ignoring the case of ASCII characters.
1690 * Unlike the BSD strcasecmp() function, this only recognizes standard
1691 * ASCII letters and ignores the locale, treating all non-ASCII
1692 * bytes as if they are not letters.
1694 * This function should be used only on strings that are known to be
1695 * in encodings where the bytes corresponding to ASCII letters always
1696 * represent themselves. This includes UTF-8 and the ISO-8859-*
1697 * charsets, but not for instance double-byte encodings like the
1698 * Windows Codepage 932, where the trailing bytes of double-byte
1699 * characters include all ASCII letters. If you compare two CP932
1700 * strings using this function, you will get false matches.
1702 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1703 * or a positive value if @s1 > @s2.
1706 g_ascii_strcasecmp (const gchar *s1,
1711 g_return_val_if_fail (s1 != NULL, 0);
1712 g_return_val_if_fail (s2 != NULL, 0);
1716 c1 = (gint)(guchar) TOLOWER (*s1);
1717 c2 = (gint)(guchar) TOLOWER (*s2);
1723 return (((gint)(guchar) *s1) - ((gint)(guchar) *s2));
1727 * g_ascii_strncasecmp:
1728 * @s1: string to compare with @s2.
1729 * @s2: string to compare with @s1.
1730 * @n: number of characters to compare.
1732 * Compare @s1 and @s2, ignoring the case of ASCII characters and any
1733 * characters after the first @n in each string.
1735 * Unlike the BSD strcasecmp() function, this only recognizes standard
1736 * ASCII letters and ignores the locale, treating all non-ASCII
1737 * characters as if they are not letters.
1739 * The same warning as in g_ascii_strcasecmp() applies: Use this
1740 * function only on strings known to be in encodings where bytes
1741 * corresponding to ASCII letters always represent themselves.
1743 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1744 * or a positive value if @s1 > @s2.
1747 g_ascii_strncasecmp (const gchar *s1,
1753 g_return_val_if_fail (s1 != NULL, 0);
1754 g_return_val_if_fail (s2 != NULL, 0);
1756 while (n && *s1 && *s2)
1759 c1 = (gint)(guchar) TOLOWER (*s1);
1760 c2 = (gint)(guchar) TOLOWER (*s2);
1767 return (((gint) (guchar) *s1) - ((gint) (guchar) *s2));
1775 * @s2: a string to compare with @s1.
1777 * A case-insensitive string comparison, corresponding to the standard
1778 * strcasecmp() function on platforms which support it.
1780 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1781 * or a positive value if @s1 > @s2.
1783 * Deprecated:2.2: See g_strncasecmp() for a discussion of why this function
1784 * is deprecated and how to replace it.
1787 g_strcasecmp (const gchar *s1,
1790 #ifdef HAVE_STRCASECMP
1791 g_return_val_if_fail (s1 != NULL, 0);
1792 g_return_val_if_fail (s2 != NULL, 0);
1794 return strcasecmp (s1, s2);
1798 g_return_val_if_fail (s1 != NULL, 0);
1799 g_return_val_if_fail (s2 != NULL, 0);
1803 /* According to A. Cox, some platforms have islower's that
1804 * don't work right on non-uppercase
1806 c1 = isupper ((guchar)*s1) ? tolower ((guchar)*s1) : *s1;
1807 c2 = isupper ((guchar)*s2) ? tolower ((guchar)*s2) : *s2;
1813 return (((gint)(guchar) *s1) - ((gint)(guchar) *s2));
1820 * @s2: a string to compare with @s1.
1821 * @n: the maximum number of characters to compare.
1823 * A case-insensitive string comparison, corresponding to the standard
1824 * strncasecmp() function on platforms which support it.
1825 * It is similar to g_strcasecmp() except it only compares the first @n
1826 * characters of the strings.
1828 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1829 * or a positive value if @s1 > @s2.
1831 * Deprecated:2.2: The problem with g_strncasecmp() is that it does the
1832 * comparison by calling toupper()/tolower(). These functions are
1833 * locale-specific and operate on single bytes. However, it is impossible
1834 * to handle things correctly from an I18N standpoint by operating on
1835 * bytes, since characters may be multibyte. Thus g_strncasecmp() is
1836 * broken if your string is guaranteed to be ASCII, since it's
1837 * locale-sensitive, and it's broken if your string is localized, since
1838 * it doesn't work on many encodings at all, including UTF-8, EUC-JP,
1841 * There are therefore two replacement functions: g_ascii_strncasecmp(),
1842 * which only works on ASCII and is not locale-sensitive, and
1843 * g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8.
1846 g_strncasecmp (const gchar *s1,
1850 #ifdef HAVE_STRNCASECMP
1851 return strncasecmp (s1, s2, n);
1855 g_return_val_if_fail (s1 != NULL, 0);
1856 g_return_val_if_fail (s2 != NULL, 0);
1858 while (n && *s1 && *s2)
1861 /* According to A. Cox, some platforms have islower's that
1862 * don't work right on non-uppercase
1864 c1 = isupper ((guchar)*s1) ? tolower ((guchar)*s1) : *s1;
1865 c2 = isupper ((guchar)*s2) ? tolower ((guchar)*s2) : *s2;
1872 return (((gint) (guchar) *s1) - ((gint) (guchar) *s2));
1880 * @string: the string to convert
1881 * @delimiters: a string containing the current delimiters, or %NULL
1882 * to use the standard delimiters defined in #G_STR_DELIMITERS
1883 * @new_delimiter: the new delimiter character
1885 * Converts any delimiter characters in @string to @new_delimiter.
1886 * Any characters in @string which are found in @delimiters are
1887 * changed to the @new_delimiter character. Modifies @string in place,
1888 * and returns @string itself, not a copy. The return value is to
1889 * allow nesting such as
1891 * g_ascii_strup (g_strdelimit (str, "abc", '?'))
1897 g_strdelimit (gchar *string,
1898 const gchar *delimiters,
1903 g_return_val_if_fail (string != NULL, NULL);
1906 delimiters = G_STR_DELIMITERS;
1908 for (c = string; *c; c++)
1910 if (strchr (delimiters, *c))
1919 * @string: a nul-terminated array of bytes
1920 * @valid_chars: bytes permitted in @string
1921 * @substitutor: replacement character for disallowed bytes
1923 * For each character in @string, if the character is not in
1924 * @valid_chars, replaces the character with @substitutor.
1925 * Modifies @string in place, and return @string itself, not
1926 * a copy. The return value is to allow nesting such as
1928 * g_ascii_strup (g_strcanon (str, "abc", '?'))
1934 g_strcanon (gchar *string,
1935 const gchar *valid_chars,
1940 g_return_val_if_fail (string != NULL, NULL);
1941 g_return_val_if_fail (valid_chars != NULL, NULL);
1943 for (c = string; *c; c++)
1945 if (!strchr (valid_chars, *c))
1954 * @source: a string to compress
1956 * Replaces all escaped characters with their one byte equivalent.
1958 * This function does the reverse conversion of g_strescape().
1960 * Returns: a newly-allocated copy of @source with all escaped
1961 * character compressed
1964 g_strcompress (const gchar *source)
1966 const gchar *p = source, *octal;
1967 gchar *dest = g_malloc (strlen (source) + 1);
1978 g_warning ("g_strcompress: trailing \\");
1980 case '0': case '1': case '2': case '3': case '4':
1981 case '5': case '6': case '7':
1984 while ((p < octal + 3) && (*p >= '0') && (*p <= '7'))
1986 *q = (*q * 8) + (*p - '0');
2007 default: /* Also handles \" and \\ */
2024 * @source: a string to escape
2025 * @exceptions: a string of characters not to escape in @source
2027 * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\'
2028 * and '"' in the string @source by inserting a '\' before
2029 * them. Additionally all characters in the range 0x01-0x1F (everything
2030 * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
2031 * replaced with a '\' followed by their octal representation.
2032 * Characters supplied in @exceptions are not escaped.
2034 * g_strcompress() does the reverse conversion.
2036 * Returns: a newly-allocated copy of @source with certain
2037 * characters escaped. See above.
2040 g_strescape (const gchar *source,
2041 const gchar *exceptions)
2048 g_return_val_if_fail (source != NULL, NULL);
2050 p = (guchar *) source;
2051 /* Each source byte needs maximally four destination chars (\777) */
2052 q = dest = g_malloc (strlen (source) * 4 + 1);
2054 memset (excmap, 0, 256);
2057 guchar *e = (guchar *) exceptions;
2103 if ((*p < ' ') || (*p >= 0177))
2106 *q++ = '0' + (((*p) >> 6) & 07);
2107 *q++ = '0' + (((*p) >> 3) & 07);
2108 *q++ = '0' + ((*p) & 07);
2123 * @string: a string to remove the leading whitespace from
2125 * Removes leading whitespace from a string, by moving the rest
2126 * of the characters forward.
2128 * This function doesn't allocate or reallocate any memory;
2129 * it modifies @string in place. The pointer to @string is
2130 * returned to allow the nesting of functions.
2132 * Also see g_strchomp() and g_strstrip().
2137 g_strchug (gchar *string)
2141 g_return_val_if_fail (string != NULL, NULL);
2143 for (start = (guchar*) string; *start && g_ascii_isspace (*start); start++)
2146 g_memmove (string, start, strlen ((gchar *) start) + 1);
2153 * @string: a string to remove the trailing whitespace from
2155 * Removes trailing whitespace from a string.
2157 * This function doesn't allocate or reallocate any memory;
2158 * it modifies @string in place. The pointer to @string is
2159 * returned to allow the nesting of functions.
2161 * Also see g_strchug() and g_strstrip().
2166 g_strchomp (gchar *string)
2170 g_return_val_if_fail (string != NULL, NULL);
2172 len = strlen (string);
2175 if (g_ascii_isspace ((guchar) string[len]))
2186 * @string: a string to split
2187 * @delimiter: a string which specifies the places at which to split
2188 * the string. The delimiter is not included in any of the resulting
2189 * strings, unless @max_tokens is reached.
2190 * @max_tokens: the maximum number of pieces to split @string into.
2191 * If this is less than 1, the string is split completely.
2193 * Splits a string into a maximum of @max_tokens pieces, using the given
2194 * @delimiter. If @max_tokens is reached, the remainder of @string is
2195 * appended to the last token.
2197 * As a special case, the result of splitting the empty string "" is an empty
2198 * vector, not a vector containing a single string. The reason for this
2199 * special case is that being able to represent a empty vector is typically
2200 * more useful than consistent handling of empty elements. If you do need
2201 * to represent empty elements, you'll need to check for the empty string
2202 * before calling g_strsplit().
2204 * Return value: a newly-allocated %NULL-terminated array of strings. Use
2205 * g_strfreev() to free it.
2208 g_strsplit (const gchar *string,
2209 const gchar *delimiter,
2212 GSList *string_list = NULL, *slist;
2213 gchar **str_array, *s;
2215 const gchar *remainder;
2217 g_return_val_if_fail (string != NULL, NULL);
2218 g_return_val_if_fail (delimiter != NULL, NULL);
2219 g_return_val_if_fail (delimiter[0] != '\0', NULL);
2222 max_tokens = G_MAXINT;
2225 s = strstr (remainder, delimiter);
2228 gsize delimiter_len = strlen (delimiter);
2230 while (--max_tokens && s)
2234 len = s - remainder;
2235 string_list = g_slist_prepend (string_list,
2236 g_strndup (remainder, len));
2238 remainder = s + delimiter_len;
2239 s = strstr (remainder, delimiter);
2245 string_list = g_slist_prepend (string_list, g_strdup (remainder));
2248 str_array = g_new (gchar*, n + 1);
2250 str_array[n--] = NULL;
2251 for (slist = string_list; slist; slist = slist->next)
2252 str_array[n--] = slist->data;
2254 g_slist_free (string_list);
2261 * @string: The string to be tokenized
2262 * @delimiters: A nul-terminated string containing bytes that are used
2263 * to split the string.
2264 * @max_tokens: The maximum number of tokens to split @string into.
2265 * If this is less than 1, the string is split completely
2267 * Splits @string into a number of tokens not containing any of the characters
2268 * in @delimiter. A token is the (possibly empty) longest string that does not
2269 * contain any of the characters in @delimiters. If @max_tokens is reached, the
2270 * remainder is appended to the last token.
2272 * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
2273 * %NULL-terminated vector containing the three strings "abc", "def",
2276 * The result if g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
2277 * vector containing the four strings "", "def", "ghi", and "".
2279 * As a special case, the result of splitting the empty string "" is an empty
2280 * vector, not a vector containing a single string. The reason for this
2281 * special case is that being able to represent a empty vector is typically
2282 * more useful than consistent handling of empty elements. If you do need
2283 * to represent empty elements, you'll need to check for the empty string
2284 * before calling g_strsplit_set().
2286 * Note that this function works on bytes not characters, so it can't be used
2287 * to delimit UTF-8 strings for anything but ASCII characters.
2289 * Return value: a newly-allocated %NULL-terminated array of strings. Use
2290 * g_strfreev() to free it.
2295 g_strsplit_set (const gchar *string,
2296 const gchar *delimiters,
2299 gboolean delim_table[256];
2300 GSList *tokens, *list;
2303 const gchar *current;
2307 g_return_val_if_fail (string != NULL, NULL);
2308 g_return_val_if_fail (delimiters != NULL, NULL);
2311 max_tokens = G_MAXINT;
2313 if (*string == '\0')
2315 result = g_new (char *, 1);
2320 memset (delim_table, FALSE, sizeof (delim_table));
2321 for (s = delimiters; *s != '\0'; ++s)
2322 delim_table[*(guchar *)s] = TRUE;
2327 s = current = string;
2330 if (delim_table[*(guchar *)s] && n_tokens + 1 < max_tokens)
2332 token = g_strndup (current, s - current);
2333 tokens = g_slist_prepend (tokens, token);
2342 token = g_strndup (current, s - current);
2343 tokens = g_slist_prepend (tokens, token);
2346 result = g_new (gchar *, n_tokens + 1);
2348 result[n_tokens] = NULL;
2349 for (list = tokens; list != NULL; list = list->next)
2350 result[--n_tokens] = list->data;
2352 g_slist_free (tokens);
2359 * @str_array: a %NULL-terminated array of strings to free
2361 * Frees a %NULL-terminated array of strings, and the array itself.
2362 * If called on a %NULL value, g_strfreev() simply returns.
2365 g_strfreev (gchar **str_array)
2371 for (i = 0; str_array[i] != NULL; i++)
2372 g_free (str_array[i]);
2380 * @str_array: a %NULL-terminated array of strings
2382 * Copies %NULL-terminated array of strings. The copy is a deep copy;
2383 * the new array should be freed by first freeing each string, then
2384 * the array itself. g_strfreev() does this for you. If called
2385 * on a %NULL value, g_strdupv() simply returns %NULL.
2387 * Return value: a new %NULL-terminated array of strings.
2390 g_strdupv (gchar **str_array)
2398 while (str_array[i])
2401 retval = g_new (gchar*, i + 1);
2404 while (str_array[i])
2406 retval[i] = g_strdup (str_array[i]);
2419 * @separator: a string to insert between each of the strings, or %NULL
2420 * @str_array: a %NULL-terminated array of strings to join
2422 * Joins a number of strings together to form one long string, with the
2423 * optional @separator inserted between each of them. The returned string
2424 * should be freed with g_free().
2426 * Returns: a newly-allocated string containing all of the strings joined
2427 * together, with @separator between them
2430 g_strjoinv (const gchar *separator,
2436 g_return_val_if_fail (str_array != NULL, NULL);
2438 if (separator == NULL)
2445 gsize separator_len;
2447 separator_len = strlen (separator);
2448 /* First part, getting length */
2449 len = 1 + strlen (str_array[0]);
2450 for (i = 1; str_array[i] != NULL; i++)
2451 len += strlen (str_array[i]);
2452 len += separator_len * (i - 1);
2454 /* Second part, building string */
2455 string = g_new (gchar, len);
2456 ptr = g_stpcpy (string, *str_array);
2457 for (i = 1; str_array[i] != NULL; i++)
2459 ptr = g_stpcpy (ptr, separator);
2460 ptr = g_stpcpy (ptr, str_array[i]);
2464 string = g_strdup ("");
2471 * @separator: a string to insert between each of the strings, or %NULL
2472 * @...: a %NULL-terminated list of strings to join
2474 * Joins a number of strings together to form one long string, with the
2475 * optional @separator inserted between each of them. The returned string
2476 * should be freed with g_free().
2478 * Returns: a newly-allocated string containing all of the strings joined
2479 * together, with @separator between them
2482 g_strjoin (const gchar *separator,
2488 gsize separator_len;
2491 if (separator == NULL)
2494 separator_len = strlen (separator);
2496 va_start (args, separator);
2498 s = va_arg (args, gchar*);
2502 /* First part, getting length */
2503 len = 1 + strlen (s);
2505 s = va_arg (args, gchar*);
2508 len += separator_len + strlen (s);
2509 s = va_arg (args, gchar*);
2513 /* Second part, building string */
2514 string = g_new (gchar, len);
2516 va_start (args, separator);
2518 s = va_arg (args, gchar*);
2519 ptr = g_stpcpy (string, s);
2521 s = va_arg (args, gchar*);
2524 ptr = g_stpcpy (ptr, separator);
2525 ptr = g_stpcpy (ptr, s);
2526 s = va_arg (args, gchar*);
2530 string = g_strdup ("");
2540 * @haystack: a string
2541 * @haystack_len: the maximum length of @haystack. Note that -1 is
2542 * a valid length, if @haystack is nul-terminated, meaning it will
2543 * search through the whole string.
2544 * @needle: the string to search for
2546 * Searches the string @haystack for the first occurrence
2547 * of the string @needle, limiting the length of the search
2550 * Return value: a pointer to the found occurrence, or
2551 * %NULL if not found.
2554 g_strstr_len (const gchar *haystack,
2555 gssize haystack_len,
2556 const gchar *needle)
2558 g_return_val_if_fail (haystack != NULL, NULL);
2559 g_return_val_if_fail (needle != NULL, NULL);
2561 if (haystack_len < 0)
2562 return strstr (haystack, needle);
2565 const gchar *p = haystack;
2566 gsize needle_len = strlen (needle);
2570 if (needle_len == 0)
2571 return (gchar *)haystack;
2573 if (haystack_len < needle_len)
2576 end = haystack + haystack_len - needle_len;
2578 while (p <= end && *p)
2580 for (i = 0; i < needle_len; i++)
2581 if (p[i] != needle[i])
2596 * @haystack: a nul-terminated string
2597 * @needle: the nul-terminated string to search for
2599 * Searches the string @haystack for the last occurrence
2600 * of the string @needle.
2602 * Return value: a pointer to the found occurrence, or
2603 * %NULL if not found.
2606 g_strrstr (const gchar *haystack,
2607 const gchar *needle)
2614 g_return_val_if_fail (haystack != NULL, NULL);
2615 g_return_val_if_fail (needle != NULL, NULL);
2617 needle_len = strlen (needle);
2618 haystack_len = strlen (haystack);
2620 if (needle_len == 0)
2621 return (gchar *)haystack;
2623 if (haystack_len < needle_len)
2626 p = haystack + haystack_len - needle_len;
2628 while (p >= haystack)
2630 for (i = 0; i < needle_len; i++)
2631 if (p[i] != needle[i])
2645 * @haystack: a nul-terminated string
2646 * @haystack_len: the maximum length of @haystack
2647 * @needle: the nul-terminated string to search for
2649 * Searches the string @haystack for the last occurrence
2650 * of the string @needle, limiting the length of the search
2653 * Return value: a pointer to the found occurrence, or
2654 * %NULL if not found.
2657 g_strrstr_len (const gchar *haystack,
2658 gssize haystack_len,
2659 const gchar *needle)
2661 g_return_val_if_fail (haystack != NULL, NULL);
2662 g_return_val_if_fail (needle != NULL, NULL);
2664 if (haystack_len < 0)
2665 return g_strrstr (haystack, needle);
2668 gsize needle_len = strlen (needle);
2669 const gchar *haystack_max = haystack + haystack_len;
2670 const gchar *p = haystack;
2673 while (p < haystack_max && *p)
2676 if (p < haystack + needle_len)
2681 while (p >= haystack)
2683 for (i = 0; i < needle_len; i++)
2684 if (p[i] != needle[i])
2700 * @str: a nul-terminated string
2701 * @suffix: the nul-terminated suffix to look for
2703 * Looks whether the string @str ends with @suffix.
2705 * Return value: %TRUE if @str end with @suffix, %FALSE otherwise.
2710 g_str_has_suffix (const gchar *str,
2711 const gchar *suffix)
2716 g_return_val_if_fail (str != NULL, FALSE);
2717 g_return_val_if_fail (suffix != NULL, FALSE);
2719 str_len = strlen (str);
2720 suffix_len = strlen (suffix);
2722 if (str_len < suffix_len)
2725 return strcmp (str + str_len - suffix_len, suffix) == 0;
2730 * @str: a nul-terminated string
2731 * @prefix: the nul-terminated prefix to look for
2733 * Looks whether the string @str begins with @prefix.
2735 * Return value: %TRUE if @str begins with @prefix, %FALSE otherwise.
2740 g_str_has_prefix (const gchar *str,
2741 const gchar *prefix)
2746 g_return_val_if_fail (str != NULL, FALSE);
2747 g_return_val_if_fail (prefix != NULL, FALSE);
2749 str_len = strlen (str);
2750 prefix_len = strlen (prefix);
2752 if (str_len < prefix_len)
2755 return strncmp (str, prefix, prefix_len) == 0;
2760 * @str_array: a %NULL-terminated array of strings
2762 * Returns the length of the given %NULL-terminated
2763 * string array @str_array.
2765 * Return value: length of @str_array.
2770 g_strv_length (gchar **str_array)
2774 g_return_val_if_fail (str_array != NULL, 0);
2776 while (str_array[i])