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() */
43 /* Needed on BSD/OS X for e.g. strtod_l */
51 /* do not include <unistd.h> here, it may interfere with g_strsignal() */
53 #include "gstrfuncs.h"
56 #include "gprintfint.h"
61 * SECTION:string_utils
62 * @title: String Utility Functions
63 * @short_description: various string-related functions
65 * This section describes a number of utility functions for creating,
66 * duplicating, and manipulating strings.
68 * Note that the functions g_printf(), g_fprintf(), g_sprintf(),
69 * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
70 * are declared in the header <filename>gprintf.h</filename> which is
71 * <emphasis>not</emphasis> included in <filename>glib.h</filename>
72 * (otherwise using <filename>glib.h</filename> would drag in
73 * <filename>stdio.h</filename>), so you'll have to explicitly include
74 * <literal><glib/gprintf.h></literal> in order to use the GLib
77 * <para id="string-precision">While you may use the printf() functions
78 * to format UTF-8 strings, notice that the precision of a
79 * <literal>%Ns</literal> parameter is interpreted as the
80 * number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis>
81 * to print. On top of that, the GNU libc implementation of the printf()
82 * functions has the "feature" that it checks that the string given for
83 * the <literal>%Ns</literal> parameter consists of a whole number
84 * of characters in the current encoding. So, unless you are sure you are
85 * always going to be in an UTF-8 locale or your know your text is restricted
86 * to ASCII, avoid using <literal>%Ns</literal>. If your intention is
87 * to format strings for a certain number of columns, then
88 * <literal>%Ns</literal> is not a correct solution anyway, since it
89 * fails to take wide characters (see g_unichar_iswide()) into account.
97 * Determines whether a character is alphanumeric.
99 * Unlike the standard C library isalnum() function, this only
100 * recognizes standard ASCII letters and ignores the locale,
101 * returning %FALSE for all non-ASCII characters. Also, unlike
102 * the standard library function, this takes a <type>char</type>,
103 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
104 * cast to #guchar before passing a possibly non-ASCII character in.
106 * Returns: %TRUE if @c is an ASCII alphanumeric character
113 * Determines whether a character is alphabetic (i.e. a letter).
115 * Unlike the standard C library isalpha() function, this only
116 * recognizes standard ASCII letters and ignores the locale,
117 * returning %FALSE for all non-ASCII characters. Also, unlike
118 * the standard library function, this takes a <type>char</type>,
119 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
120 * cast to #guchar before passing a possibly non-ASCII character in.
122 * Returns: %TRUE if @c is an ASCII alphabetic character
129 * Determines whether a character is a control character.
131 * Unlike the standard C library iscntrl() function, this only
132 * recognizes standard ASCII control characters and ignores the
133 * locale, returning %FALSE for all non-ASCII characters. Also,
134 * unlike the standard library function, this takes a <type>char</type>,
135 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
136 * cast to #guchar before passing a possibly non-ASCII character in.
138 * Returns: %TRUE if @c is an ASCII control character.
145 * Determines whether a character is digit (0-9).
147 * Unlike the standard C library isdigit() function, this takes
148 * a <type>char</type>, not an <type>int</type>, so don't call it
149 * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
150 * non-ASCII character in.
152 * Returns: %TRUE if @c is an ASCII digit.
159 * Determines whether a character is a printing character and not a space.
161 * Unlike the standard C library isgraph() function, this only
162 * recognizes standard ASCII characters and ignores the locale,
163 * returning %FALSE for all non-ASCII characters. Also, unlike
164 * the standard library function, this takes a <type>char</type>,
165 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
166 * to cast to #guchar before passing a possibly non-ASCII character in.
168 * Returns: %TRUE if @c is an ASCII printing character other than space.
175 * Determines whether a character is an ASCII lower case letter.
177 * Unlike the standard C library islower() function, this only
178 * recognizes standard ASCII letters and ignores the locale,
179 * returning %FALSE for all non-ASCII characters. Also, unlike
180 * the standard library function, this takes a <type>char</type>,
181 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
182 * to worry about casting to #guchar before passing a possibly
183 * non-ASCII character in.
185 * Returns: %TRUE if @c is an ASCII lower case letter
192 * Determines whether a character is a printing character.
194 * Unlike the standard C library isprint() function, this only
195 * recognizes standard ASCII characters and ignores the locale,
196 * returning %FALSE for all non-ASCII characters. Also, unlike
197 * the standard library function, this takes a <type>char</type>,
198 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
199 * to cast to #guchar before passing a possibly non-ASCII character in.
201 * Returns: %TRUE if @c is an ASCII printing character.
208 * Determines whether a character is a punctuation character.
210 * Unlike the standard C library ispunct() function, this only
211 * recognizes standard ASCII letters and ignores the locale,
212 * returning %FALSE for all non-ASCII characters. Also, unlike
213 * the standard library function, this takes a <type>char</type>,
214 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
215 * cast to #guchar before passing a possibly non-ASCII character in.
217 * Returns: %TRUE if @c is an ASCII punctuation character.
224 * Determines whether a character is a white-space character.
226 * Unlike the standard C library isspace() function, this only
227 * recognizes standard ASCII white-space and ignores the locale,
228 * returning %FALSE for all non-ASCII characters. Also, unlike
229 * the standard library function, this takes a <type>char</type>,
230 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
231 * cast to #guchar before passing a possibly non-ASCII character in.
233 * Returns: %TRUE if @c is an ASCII white-space character
240 * Determines whether a character is an ASCII upper case letter.
242 * Unlike the standard C library isupper() function, this only
243 * recognizes standard ASCII letters and ignores the locale,
244 * returning %FALSE for all non-ASCII characters. Also, unlike
245 * the standard library function, this takes a <type>char</type>,
246 * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
247 * worry about casting to #guchar before passing a possibly non-ASCII
250 * Returns: %TRUE if @c is an ASCII upper case letter
257 * Determines whether a character is a hexadecimal-digit character.
259 * Unlike the standard C library isxdigit() function, this takes
260 * a <type>char</type>, not an <type>int</type>, so don't call it
261 * on <literal>EOF</literal>, but no need to cast to #guchar before passing a
262 * possibly non-ASCII character in.
264 * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
268 * G_ASCII_DTOSTR_BUF_SIZE:
270 * A good size for a buffer to be passed into g_ascii_dtostr().
271 * It is guaranteed to be enough for all output of that function
272 * on systems with 64bit IEEE-compatible doubles.
274 * The typical usage would be something like:
276 * char buf[G_ASCII_DTOSTR_BUF_SIZE];
278 * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
284 * @string: a string to remove the leading and trailing whitespace from
286 * Removes leading and trailing whitespace from a string.
287 * See g_strchomp() and g_strchug().
295 * The standard delimiters, used in g_strdelimit().
298 static const guint16 ascii_table_data[256] = {
299 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
300 0x004, 0x104, 0x104, 0x004, 0x104, 0x104, 0x004, 0x004,
301 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
302 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
303 0x140, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
304 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
305 0x459, 0x459, 0x459, 0x459, 0x459, 0x459, 0x459, 0x459,
306 0x459, 0x459, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
307 0x0d0, 0x653, 0x653, 0x653, 0x653, 0x653, 0x653, 0x253,
308 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253,
309 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253,
310 0x253, 0x253, 0x253, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
311 0x0d0, 0x473, 0x473, 0x473, 0x473, 0x473, 0x473, 0x073,
312 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073,
313 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073,
314 0x073, 0x073, 0x073, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x004
315 /* the upper 128 are all zeroes */
318 const guint16 * const g_ascii_table = ascii_table_data;
320 #if defined (HAVE_NEWLOCALE) && \
321 defined (HAVE_USELOCALE) && \
322 defined (HAVE_STRTOD_L) && \
323 defined (HAVE_STRTOULL_L) && \
324 defined (HAVE_STRTOLL_L)
325 #define USE_XLOCALE 1
332 static gsize initialized = FALSE;
333 static locale_t C_locale = NULL;
335 if (g_once_init_enter (&initialized))
337 C_locale = newlocale (LC_ALL_MASK, "C", NULL);
338 g_once_init_leave (&initialized, TRUE);
347 * @str: the string to duplicate
349 * Duplicates a string. If @str is %NULL it returns %NULL.
350 * The returned string should be freed with g_free()
351 * when no longer needed.
353 * Returns: a newly-allocated copy of @str
356 g_strdup (const gchar *str)
363 length = strlen (str) + 1;
364 new_str = g_new (char, length);
365 memcpy (new_str, str, length);
375 * @mem: the memory to copy.
376 * @byte_size: the number of bytes to copy.
378 * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
379 * from @mem. If @mem is %NULL it returns %NULL.
381 * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
385 g_memdup (gconstpointer mem,
392 new_mem = g_malloc (byte_size);
393 memcpy (new_mem, mem, byte_size);
403 * @str: the string to duplicate
404 * @n: the maximum number of bytes to copy from @str
406 * Duplicates the first @n bytes of a string, returning a newly-allocated
407 * buffer @n + 1 bytes long which will always be nul-terminated.
408 * If @str is less than @n bytes long the buffer is padded with nuls.
409 * If @str is %NULL it returns %NULL.
410 * The returned value should be freed when no longer needed.
413 * To copy a number of characters from a UTF-8 encoded string, use
414 * g_utf8_strncpy() instead.
417 * Returns: a newly-allocated buffer containing the first @n bytes
418 * of @str, nul-terminated
421 g_strndup (const gchar *str,
428 new_str = g_new (gchar, n + 1);
429 strncpy (new_str, str, n);
440 * @length: the length of the new string
441 * @fill_char: the byte to fill the string with
443 * Creates a new string @length bytes long filled with @fill_char.
444 * The returned string should be freed when no longer needed.
446 * Returns: a newly-allocated string filled the @fill_char
449 g_strnfill (gsize length,
454 str = g_new (gchar, length + 1);
455 memset (str, (guchar)fill_char, length);
463 * @dest: destination buffer.
464 * @src: source string.
466 * Copies a nul-terminated string into the dest buffer, include the
467 * trailing nul, and return a pointer to the trailing nul byte.
468 * This is useful for concatenating multiple strings together
469 * without having to repeatedly scan for the end.
471 * Return value: a pointer to trailing nul byte.
474 g_stpcpy (gchar *dest,
478 g_return_val_if_fail (dest != NULL, NULL);
479 g_return_val_if_fail (src != NULL, NULL);
480 return stpcpy (dest, src);
482 register gchar *d = dest;
483 register const gchar *s = src;
485 g_return_val_if_fail (dest != NULL, NULL);
486 g_return_val_if_fail (src != NULL, NULL);
489 while (*s++ != '\0');
497 * @format: a standard printf() format string, but notice
498 * <link linkend="string-precision">string precision pitfalls</link>
499 * @args: the list of parameters to insert into the format string
501 * Similar to the standard C vsprintf() function but safer, since it
502 * calculates the maximum space required and allocates memory to hold
503 * the result. The returned string should be freed with g_free() when
506 * See also g_vasprintf(), which offers the same functionality, but
507 * additionally returns the length of the allocated string.
509 * Returns: a newly-allocated string holding the result
512 g_strdup_vprintf (const gchar *format,
515 gchar *string = NULL;
517 g_vasprintf (&string, format, args);
524 * @format: a standard printf() format string, but notice
525 * <link linkend="string-precision">string precision pitfalls</link>
526 * @...: the parameters to insert into the format string
528 * Similar to the standard C sprintf() function but safer, since it
529 * calculates the maximum space required and allocates memory to hold
530 * the result. The returned string should be freed with g_free() when no
533 * Returns: a newly-allocated string holding the result
536 g_strdup_printf (const gchar *format,
542 va_start (args, format);
543 buffer = g_strdup_vprintf (format, args);
551 * @string1: the first string to add, which must not be %NULL
552 * @...: a %NULL-terminated list of strings to append to the string
554 * Concatenates all of the given strings into one long string.
555 * The returned string should be freed with g_free() when no longer needed.
557 * Note that this function is usually not the right function to use to
558 * assemble a translated message from pieces, since proper translation
559 * often requires the pieces to be reordered.
561 * <warning><para>The variable argument list <emphasis>must</emphasis> end
562 * with %NULL. If you forget the %NULL, g_strconcat() will start appending
563 * random memory junk to your string.</para></warning>
565 * Returns: a newly-allocated string containing all the string arguments
568 g_strconcat (const gchar *string1, ...)
579 l = 1 + strlen (string1);
580 va_start (args, string1);
581 s = va_arg (args, gchar*);
585 s = va_arg (args, gchar*);
589 concat = g_new (gchar, l);
592 ptr = g_stpcpy (ptr, string1);
593 va_start (args, string1);
594 s = va_arg (args, gchar*);
597 ptr = g_stpcpy (ptr, s);
598 s = va_arg (args, gchar*);
607 * @nptr: the string to convert to a numeric value.
608 * @endptr: if non-%NULL, it returns the character after
609 * the last character used in the conversion.
611 * Converts a string to a #gdouble value.
612 * It calls the standard strtod() function to handle the conversion, but
613 * if the string is not completely converted it attempts the conversion
614 * again with g_ascii_strtod(), and returns the best match.
616 * This function should seldom be used. The normal situation when reading
617 * numbers not for human consumption is to use g_ascii_strtod(). Only when
618 * you know that you must expect both locale formatted and C formatted numbers
619 * should you use this. Make sure that you don't pass strings such as comma
620 * separated lists of values, since the commas may be interpreted as a decimal
621 * point in some locales, causing unexpected results.
623 * Return value: the #gdouble value.
626 g_strtod (const gchar *nptr,
634 g_return_val_if_fail (nptr != NULL, 0);
639 val_1 = strtod (nptr, &fail_pos_1);
641 if (fail_pos_1 && fail_pos_1[0] != 0)
642 val_2 = g_ascii_strtod (nptr, &fail_pos_2);
644 if (!fail_pos_1 || fail_pos_1[0] == 0 || fail_pos_1 >= fail_pos_2)
647 *endptr = fail_pos_1;
653 *endptr = fail_pos_2;
660 * @nptr: the string to convert to a numeric value.
661 * @endptr: if non-%NULL, it returns the character after
662 * the last character used in the conversion.
664 * Converts a string to a #gdouble value.
666 * This function behaves like the standard strtod() function
667 * does in the C locale. It does this without actually changing
668 * the current locale, since that would not be thread-safe.
669 * A limitation of the implementation is that this function
670 * will still accept localized versions of infinities and NANs.
672 * This function is typically used when reading configuration
673 * files or other non-user input that should be locale independent.
674 * To handle input from the user you should normally use the
675 * locale-sensitive system strtod() function.
677 * To convert from a #gdouble to a string in a locale-insensitive
678 * way, use g_ascii_dtostr().
680 * If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
681 * is returned (according to the sign of the value), and <literal>ERANGE</literal> is
682 * stored in <literal>errno</literal>. If the correct value would cause underflow,
683 * zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
685 * This function resets <literal>errno</literal> before calling strtod() so that
686 * you can reliably detect overflow and underflow.
688 * Return value: the #gdouble value.
691 g_ascii_strtod (const gchar *nptr,
696 g_return_val_if_fail (nptr != NULL, 0);
700 return strtod_l (nptr, endptr, get_C_locale ());
707 struct lconv *locale_data;
709 const char *decimal_point;
710 int decimal_point_len;
711 const char *p, *decimal_point_pos;
712 const char *end = NULL; /* Silence gcc */
715 g_return_val_if_fail (nptr != NULL, 0);
720 locale_data = localeconv ();
721 decimal_point = locale_data->decimal_point;
722 decimal_point_len = strlen (decimal_point);
725 decimal_point_len = 1;
728 g_assert (decimal_point_len != 0);
730 decimal_point_pos = NULL;
733 if (decimal_point[0] != '.' ||
734 decimal_point[1] != 0)
737 /* Skip leading space */
738 while (g_ascii_isspace (*p))
741 /* Skip leading optional sign */
742 if (*p == '+' || *p == '-')
746 (p[1] == 'x' || p[1] == 'X'))
749 /* HEX - find the (optional) decimal point */
751 while (g_ascii_isxdigit (*p))
755 decimal_point_pos = p++;
757 while (g_ascii_isxdigit (*p))
760 if (*p == 'p' || *p == 'P')
762 if (*p == '+' || *p == '-')
764 while (g_ascii_isdigit (*p))
769 else if (g_ascii_isdigit (*p) || *p == '.')
771 while (g_ascii_isdigit (*p))
775 decimal_point_pos = p++;
777 while (g_ascii_isdigit (*p))
780 if (*p == 'e' || *p == 'E')
782 if (*p == '+' || *p == '-')
784 while (g_ascii_isdigit (*p))
789 /* For the other cases, we need not convert the decimal point */
792 if (decimal_point_pos)
796 /* We need to convert the '.' to the locale specific decimal point */
797 copy = g_malloc (end - nptr + 1 + decimal_point_len);
800 memcpy (c, nptr, decimal_point_pos - nptr);
801 c += decimal_point_pos - nptr;
802 memcpy (c, decimal_point, decimal_point_len);
803 c += decimal_point_len;
804 memcpy (c, decimal_point_pos + 1, end - (decimal_point_pos + 1));
805 c += end - (decimal_point_pos + 1);
809 val = strtod (copy, &fail_pos);
810 strtod_errno = errno;
814 if (fail_pos - copy > decimal_point_pos - nptr)
815 fail_pos = (char *)nptr + (fail_pos - copy) - (decimal_point_len - 1);
817 fail_pos = (char *)nptr + (fail_pos - copy);
827 copy = g_malloc (end - (char *)nptr + 1);
828 memcpy (copy, nptr, end - nptr);
829 *(copy + (end - (char *)nptr)) = 0;
832 val = strtod (copy, &fail_pos);
833 strtod_errno = errno;
837 fail_pos = (char *)nptr + (fail_pos - copy);
845 val = strtod (nptr, &fail_pos);
846 strtod_errno = errno;
852 errno = strtod_errno;
861 * @buffer: A buffer to place the resulting string in
862 * @buf_len: The length of the buffer.
863 * @d: The #gdouble to convert
865 * Converts a #gdouble to a string, using the '.' as
868 * This function generates enough precision that converting
869 * the string back using g_ascii_strtod() gives the same machine-number
870 * (on machines with IEEE compatible 64bit doubles). It is
871 * guaranteed that the size of the resulting string will never
872 * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes.
874 * Return value: The pointer to the buffer with the converted string.
877 g_ascii_dtostr (gchar *buffer,
881 return g_ascii_formatd (buffer, buf_len, "%.17g", d);
884 #pragma GCC diagnostic push
885 #pragma GCC diagnostic ignored "-Wformat-nonliteral"
889 * @buffer: A buffer to place the resulting string in
890 * @buf_len: The length of the buffer.
891 * @format: The printf()-style format to use for the
892 * code to use for converting.
893 * @d: The #gdouble to convert
895 * Converts a #gdouble to a string, using the '.' as
896 * decimal point. To format the number you pass in
897 * a printf()-style format string. Allowed conversion
898 * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
900 * If you just want to want to serialize the value into a
901 * string, use g_ascii_dtostr().
903 * Return value: The pointer to the buffer with the converted string.
906 g_ascii_formatd (gchar *buffer,
914 old_locale = uselocale (get_C_locale ());
915 _g_snprintf (buffer, buf_len, format, d);
916 uselocale (old_locale);
921 struct lconv *locale_data;
923 const char *decimal_point;
924 int decimal_point_len;
929 g_return_val_if_fail (buffer != NULL, NULL);
930 g_return_val_if_fail (format[0] == '%', NULL);
931 g_return_val_if_fail (strpbrk (format + 1, "'l%") == NULL, NULL);
933 format_char = format[strlen (format) - 1];
935 g_return_val_if_fail (format_char == 'e' || format_char == 'E' ||
936 format_char == 'f' || format_char == 'F' ||
937 format_char == 'g' || format_char == 'G',
940 if (format[0] != '%')
943 if (strpbrk (format + 1, "'l%"))
946 if (!(format_char == 'e' || format_char == 'E' ||
947 format_char == 'f' || format_char == 'F' ||
948 format_char == 'g' || format_char == 'G'))
951 _g_snprintf (buffer, buf_len, format, d);
954 locale_data = localeconv ();
955 decimal_point = locale_data->decimal_point;
956 decimal_point_len = strlen (decimal_point);
959 decimal_point_len = 1;
962 g_assert (decimal_point_len != 0);
964 if (decimal_point[0] != '.' ||
965 decimal_point[1] != 0)
969 while (g_ascii_isspace (*p))
972 if (*p == '+' || *p == '-')
975 while (isdigit ((guchar)*p))
978 if (strncmp (p, decimal_point, decimal_point_len) == 0)
982 if (decimal_point_len > 1)
984 rest_len = strlen (p + (decimal_point_len-1));
985 memmove (p, p + (decimal_point_len-1), rest_len);
994 #pragma GCC diagnostic pop
996 #define ISSPACE(c) ((c) == ' ' || (c) == '\f' || (c) == '\n' || \
997 (c) == '\r' || (c) == '\t' || (c) == '\v')
998 #define ISUPPER(c) ((c) >= 'A' && (c) <= 'Z')
999 #define ISLOWER(c) ((c) >= 'a' && (c) <= 'z')
1000 #define ISALPHA(c) (ISUPPER (c) || ISLOWER (c))
1001 #define TOUPPER(c) (ISLOWER (c) ? (c) - 'a' + 'A' : (c))
1002 #define TOLOWER(c) (ISUPPER (c) ? (c) - 'A' + 'a' : (c))
1007 g_parse_long_long (const gchar *nptr,
1008 const gchar **endptr,
1012 /* this code is based on on the strtol(3) code from GNU libc released under
1013 * the GNU Lesser General Public License.
1015 * Copyright (C) 1991,92,94,95,96,97,98,99,2000,01,02
1016 * Free Software Foundation, Inc.
1022 const gchar *s, *save;
1025 g_return_val_if_fail (nptr != NULL, 0);
1028 if (base == 1 || base > 36)
1038 /* Skip white space. */
1039 while (ISSPACE (*s))
1042 if (G_UNLIKELY (!*s))
1045 /* Check for a sign. */
1054 /* Recognize number prefix and if BASE is zero, figure it out ourselves. */
1057 if ((base == 0 || base == 16) && TOUPPER (s[1]) == 'X')
1068 /* Save the pointer so we can check later if anything happened. */
1070 cutoff = G_MAXUINT64 / base;
1071 cutlim = G_MAXUINT64 % base;
1078 if (c >= '0' && c <= '9')
1080 else if (ISALPHA (c))
1081 c = TOUPPER (c) - 'A' + 10;
1086 /* Check for overflow. */
1087 if (ui64 > cutoff || (ui64 == cutoff && c > cutlim))
1096 /* Check if anything actually happened. */
1100 /* Store in ENDPTR the address of one character
1101 past the last character we converted. */
1105 if (G_UNLIKELY (overflow))
1114 /* We must handle a special case here: the base is 0 or 16 and the
1115 first two characters are '0' and 'x', but the rest are no
1116 hexadecimal digits. This is no error case. We return 0 and
1117 ENDPTR points to the `x`. */
1120 if (save - nptr >= 2 && TOUPPER (save[-1]) == 'X'
1122 *endptr = &save[-1];
1124 /* There was no number to convert. */
1129 #endif /* !USE_XLOCALE */
1133 * @nptr: the string to convert to a numeric value.
1134 * @endptr: if non-%NULL, it returns the character after
1135 * the last character used in the conversion.
1136 * @base: to be used for the conversion, 2..36 or 0
1138 * Converts a string to a #guint64 value.
1139 * This function behaves like the standard strtoull() function
1140 * does in the C locale. It does this without actually
1141 * changing the current locale, since that would not be
1144 * This function is typically used when reading configuration
1145 * files or other non-user input that should be locale independent.
1146 * To handle input from the user you should normally use the
1147 * locale-sensitive system strtoull() function.
1149 * If the correct value would cause overflow, %G_MAXUINT64
1150 * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
1151 * If the base is outside the valid range, zero is returned, and
1152 * <literal>EINVAL</literal> is stored in <literal>errno</literal>.
1153 * If the string conversion fails, zero is returned, and @endptr returns
1154 * @nptr (if @endptr is non-%NULL).
1156 * Return value: the #guint64 value or zero on error.
1161 g_ascii_strtoull (const gchar *nptr,
1166 return strtoull_l (nptr, endptr, base, get_C_locale ());
1171 result = g_parse_long_long (nptr, (const gchar **) endptr, base, &negative);
1173 /* Return the result of the appropriate sign. */
1174 return negative ? -result : result;
1180 * @nptr: the string to convert to a numeric value.
1181 * @endptr: if non-%NULL, it returns the character after
1182 * the last character used in the conversion.
1183 * @base: to be used for the conversion, 2..36 or 0
1185 * Converts a string to a #gint64 value.
1186 * This function behaves like the standard strtoll() function
1187 * does in the C locale. It does this without actually
1188 * changing the current locale, since that would not be
1191 * This function is typically used when reading configuration
1192 * files or other non-user input that should be locale independent.
1193 * To handle input from the user you should normally use the
1194 * locale-sensitive system strtoll() function.
1196 * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
1197 * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
1198 * If the base is outside the valid range, zero is returned, and
1199 * <literal>EINVAL</literal> is stored in <literal>errno</literal>. If the
1200 * string conversion fails, zero is returned, and @endptr returns @nptr
1201 * (if @endptr is non-%NULL).
1203 * Return value: the #gint64 value or zero on error.
1208 g_ascii_strtoll (const gchar *nptr,
1213 return strtoll_l (nptr, endptr, base, get_C_locale ());
1218 result = g_parse_long_long (nptr, (const gchar **) endptr, base, &negative);
1220 if (negative && result > (guint64) G_MININT64)
1225 else if (!negative && result > (guint64) G_MAXINT64)
1231 return - (gint64) result;
1233 return (gint64) result;
1239 * @errnum: the system error number. See the standard C %errno
1242 * Returns a string corresponding to the given error code, e.g.
1243 * "no such process". You should use this function in preference to
1244 * strerror(), because it returns a string in UTF-8 encoding, and since
1245 * not all platforms support the strerror() function.
1247 * Returns: a UTF-8 string describing the error code. If the error code
1248 * is unknown, it returns "unknown error (<code>)".
1251 g_strerror (gint errnum)
1257 gint saved_errno = errno;
1259 msg = tofree = NULL;
1261 #ifdef HAVE_STRERROR
1262 msg = strerror (errnum);
1263 if (!g_get_charset (NULL))
1264 msg = tofree = g_locale_to_utf8 (msg, -1, NULL, NULL, NULL);
1270 _g_sprintf (msg, "unknown error (%d)", errnum);
1273 ret = g_intern_string (msg);
1275 errno = saved_errno;
1281 * @signum: the signal number. See the <literal>signal</literal>
1284 * Returns a string describing the given signal, e.g. "Segmentation fault".
1285 * You should use this function in preference to strsignal(), because it
1286 * returns a string in UTF-8 encoding, and since not all platforms support
1287 * the strsignal() function.
1289 * Returns: a UTF-8 string describing the signal. If the signal is unknown,
1290 * it returns "unknown signal (<signum>)".
1293 g_strsignal (gint signum)
1299 msg = tofree = NULL;
1301 #ifdef HAVE_STRSIGNAL
1302 msg = strsignal (signum);
1303 if (!g_get_charset (NULL))
1304 msg = tofree = g_locale_to_utf8 (msg, -1, NULL, NULL, NULL);
1308 msg = tofree = g_strdup_printf ("unknown signal (%d)", signum);
1309 ret = g_intern_string (msg);
1315 /* Functions g_strlcpy and g_strlcat were originally developed by
1316 * Todd C. Miller <Todd.Miller@courtesan.com> to simplify writing secure code.
1317 * See http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
1318 * for more information.
1322 /* Use the native ones, if available; they might be implemented in assembly */
1324 g_strlcpy (gchar *dest,
1328 g_return_val_if_fail (dest != NULL, 0);
1329 g_return_val_if_fail (src != NULL, 0);
1331 return strlcpy (dest, src, dest_size);
1335 g_strlcat (gchar *dest,
1339 g_return_val_if_fail (dest != NULL, 0);
1340 g_return_val_if_fail (src != NULL, 0);
1342 return strlcat (dest, src, dest_size);
1345 #else /* ! HAVE_STRLCPY */
1348 * @dest: destination buffer
1349 * @src: source buffer
1350 * @dest_size: length of @dest in bytes
1352 * Portability wrapper that calls strlcpy() on systems which have it,
1353 * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
1354 * guaranteed to be nul-terminated; @src must be nul-terminated;
1355 * @dest_size is the buffer size, not the number of chars to copy.
1357 * At most dest_size - 1 characters will be copied. Always nul-terminates
1358 * (unless dest_size == 0). This function does <emphasis>not</emphasis>
1359 * allocate memory. Unlike strncpy(), this function doesn't pad dest (so
1360 * it's often faster). It returns the size of the attempted result,
1361 * strlen (src), so if @retval >= @dest_size, truncation occurred.
1363 * <note><para>Caveat: strlcpy() is supposedly more secure than
1364 * strcpy() or strncpy(), but if you really want to avoid screwups,
1365 * g_strdup() is an even better idea.</para></note>
1367 * Returns: length of @src
1370 g_strlcpy (gchar *dest,
1374 register gchar *d = dest;
1375 register const gchar *s = src;
1376 register gsize n = dest_size;
1378 g_return_val_if_fail (dest != NULL, 0);
1379 g_return_val_if_fail (src != NULL, 0);
1381 /* Copy as many bytes as will fit */
1382 if (n != 0 && --n != 0)
1385 register gchar c = *s++;
1393 /* If not enough room in dest, add NUL and traverse rest of src */
1402 return s - src - 1; /* count does not include NUL */
1407 * @dest: destination buffer, already containing one nul-terminated string
1408 * @src: source buffer
1409 * @dest_size: length of @dest buffer in bytes (not length of existing string
1412 * Portability wrapper that calls strlcat() on systems which have it,
1413 * and emulates it otherwise. Appends nul-terminated @src string to @dest,
1414 * guaranteeing nul-termination for @dest. The total size of @dest won't
1415 * exceed @dest_size.
1417 * At most dest_size - 1 characters will be copied.
1418 * Unlike strncat, dest_size is the full size of dest, not the space left over.
1419 * This function does NOT allocate memory.
1420 * This always NUL terminates (unless siz == 0 or there were no NUL characters
1421 * in the dest_size characters of dest to start with).
1423 * <note><para>Caveat: this is supposedly a more secure alternative to
1424 * strcat() or strncat(), but for real security g_strconcat() is harder
1425 * to mess up.</para></note>
1427 * Returns: size of attempted result, which is MIN (dest_size, strlen
1428 * (original dest)) + strlen (src), so if retval >= dest_size,
1429 * truncation occurred.
1432 g_strlcat (gchar *dest,
1436 register gchar *d = dest;
1437 register const gchar *s = src;
1438 register gsize bytes_left = dest_size;
1439 gsize dlength; /* Logically, MIN (strlen (d), dest_size) */
1441 g_return_val_if_fail (dest != NULL, 0);
1442 g_return_val_if_fail (src != NULL, 0);
1444 /* Find the end of dst and adjust bytes left but don't go past end */
1445 while (*d != 0 && bytes_left-- != 0)
1448 bytes_left = dest_size - dlength;
1450 if (bytes_left == 0)
1451 return dlength + strlen (s);
1455 if (bytes_left != 1)
1464 return dlength + (s - src); /* count does not include NUL */
1466 #endif /* ! HAVE_STRLCPY */
1471 * @len: length of @str in bytes, or -1 if @str is nul-terminated.
1473 * Converts all upper case ASCII letters to lower case ASCII letters.
1475 * Return value: a newly-allocated string, with all the upper case
1476 * characters in @str converted to lower case, with
1477 * semantics that exactly match g_ascii_tolower(). (Note
1478 * that this is unlike the old g_strdown(), which modified
1479 * the string in place.)
1482 g_ascii_strdown (const gchar *str,
1487 g_return_val_if_fail (str != NULL, NULL);
1492 result = g_strndup (str, len);
1493 for (s = result; *s; s++)
1494 *s = g_ascii_tolower (*s);
1502 * @len: length of @str in bytes, or -1 if @str is nul-terminated.
1504 * Converts all lower case ASCII letters to upper case ASCII letters.
1506 * Return value: a newly allocated string, with all the lower case
1507 * characters in @str converted to upper case, with
1508 * semantics that exactly match g_ascii_toupper(). (Note
1509 * that this is unlike the old g_strup(), which modified
1510 * the string in place.)
1513 g_ascii_strup (const gchar *str,
1518 g_return_val_if_fail (str != NULL, NULL);
1523 result = g_strndup (str, len);
1524 for (s = result; *s; s++)
1525 *s = g_ascii_toupper (*s);
1532 * @string: a string.
1534 * Determines if a string is pure ASCII. A string is pure ASCII if it
1535 * contains no bytes with the high bit set.
1537 * Returns: %TRUE if @string is ascii
1542 g_str_is_ascii (const gchar *string)
1546 for (i = 0; string[i]; i++)
1547 if (string[i] & 0x80)
1555 * @string: the string to convert.
1557 * Converts a string to lower case.
1559 * Return value: the string
1561 * Deprecated:2.2: This function is totally broken for the reasons discussed
1562 * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
1566 g_strdown (gchar *string)
1570 g_return_val_if_fail (string != NULL, NULL);
1572 s = (guchar *) string;
1581 return (gchar *) string;
1586 * @string: the string to convert.
1588 * Converts a string to upper case.
1590 * Return value: the string
1592 * Deprecated:2.2: This function is totally broken for the reasons discussed
1593 * in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
1596 g_strup (gchar *string)
1600 g_return_val_if_fail (string != NULL, NULL);
1602 s = (guchar *) string;
1611 return (gchar *) string;
1616 * @string: the string to reverse
1618 * Reverses all of the bytes in a string. For example,
1619 * <literal>g_strreverse ("abcdef")</literal> will result
1622 * Note that g_strreverse() doesn't work on UTF-8 strings
1623 * containing multibyte characters. For that purpose, use
1624 * g_utf8_strreverse().
1626 * Returns: the same pointer passed in as @string
1629 g_strreverse (gchar *string)
1631 g_return_val_if_fail (string != NULL, NULL);
1635 register gchar *h, *t;
1638 t = string + strlen (string) - 1;
1657 * @c: any character.
1659 * Convert a character to ASCII lower case.
1661 * Unlike the standard C library tolower() function, this only
1662 * recognizes standard ASCII letters and ignores the locale, returning
1663 * all non-ASCII characters unchanged, even if they are lower case
1664 * letters in a particular character set. Also unlike the standard
1665 * library function, this takes and returns a char, not an int, so
1666 * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
1667 * before passing a possibly non-ASCII character in.
1669 * Return value: the result of converting @c to lower case.
1670 * If @c is not an ASCII upper case letter,
1671 * @c is returned unchanged.
1674 g_ascii_tolower (gchar c)
1676 return g_ascii_isupper (c) ? c - 'A' + 'a' : c;
1681 * @c: any character.
1683 * Convert a character to ASCII upper case.
1685 * Unlike the standard C library toupper() function, this only
1686 * recognizes standard ASCII letters and ignores the locale, returning
1687 * all non-ASCII characters unchanged, even if they are upper case
1688 * letters in a particular character set. Also unlike the standard
1689 * library function, this takes and returns a char, not an int, so
1690 * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
1691 * before passing a possibly non-ASCII character in.
1693 * Return value: the result of converting @c to upper case.
1694 * If @c is not an ASCII lower case letter,
1695 * @c is returned unchanged.
1698 g_ascii_toupper (gchar c)
1700 return g_ascii_islower (c) ? c - 'a' + 'A' : c;
1704 * g_ascii_digit_value:
1705 * @c: an ASCII character.
1707 * Determines the numeric value of a character as a decimal
1708 * digit. Differs from g_unichar_digit_value() because it takes
1709 * a char, so there's no worry about sign extension if characters
1712 * Return value: If @c is a decimal digit (according to
1713 * g_ascii_isdigit()), its numeric value. Otherwise, -1.
1716 g_ascii_digit_value (gchar c)
1718 if (g_ascii_isdigit (c))
1724 * g_ascii_xdigit_value:
1725 * @c: an ASCII character.
1727 * Determines the numeric value of a character as a hexidecimal
1728 * digit. Differs from g_unichar_xdigit_value() because it takes
1729 * a char, so there's no worry about sign extension if characters
1732 * Return value: If @c is a hex digit (according to
1733 * g_ascii_isxdigit()), its numeric value. Otherwise, -1.
1736 g_ascii_xdigit_value (gchar c)
1738 if (c >= 'A' && c <= 'F')
1739 return c - 'A' + 10;
1740 if (c >= 'a' && c <= 'f')
1741 return c - 'a' + 10;
1742 return g_ascii_digit_value (c);
1746 * g_ascii_strcasecmp:
1747 * @s1: string to compare with @s2.
1748 * @s2: string to compare with @s1.
1750 * Compare two strings, ignoring the case of ASCII characters.
1752 * Unlike the BSD strcasecmp() function, this only recognizes standard
1753 * ASCII letters and ignores the locale, treating all non-ASCII
1754 * bytes as if they are not letters.
1756 * This function should be used only on strings that are known to be
1757 * in encodings where the bytes corresponding to ASCII letters always
1758 * represent themselves. This includes UTF-8 and the ISO-8859-*
1759 * charsets, but not for instance double-byte encodings like the
1760 * Windows Codepage 932, where the trailing bytes of double-byte
1761 * characters include all ASCII letters. If you compare two CP932
1762 * strings using this function, you will get false matches.
1764 * Both @s1 and @s2 must be non-%NULL.
1766 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1767 * or a positive value if @s1 > @s2.
1770 g_ascii_strcasecmp (const gchar *s1,
1775 g_return_val_if_fail (s1 != NULL, 0);
1776 g_return_val_if_fail (s2 != NULL, 0);
1780 c1 = (gint)(guchar) TOLOWER (*s1);
1781 c2 = (gint)(guchar) TOLOWER (*s2);
1787 return (((gint)(guchar) *s1) - ((gint)(guchar) *s2));
1791 * g_ascii_strncasecmp:
1792 * @s1: string to compare with @s2.
1793 * @s2: string to compare with @s1.
1794 * @n: number of characters to compare.
1796 * Compare @s1 and @s2, ignoring the case of ASCII characters and any
1797 * characters after the first @n in each string.
1799 * Unlike the BSD strcasecmp() function, this only recognizes standard
1800 * ASCII letters and ignores the locale, treating all non-ASCII
1801 * characters as if they are not letters.
1803 * The same warning as in g_ascii_strcasecmp() applies: Use this
1804 * function only on strings known to be in encodings where bytes
1805 * corresponding to ASCII letters always represent themselves.
1807 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1808 * or a positive value if @s1 > @s2.
1811 g_ascii_strncasecmp (const gchar *s1,
1817 g_return_val_if_fail (s1 != NULL, 0);
1818 g_return_val_if_fail (s2 != NULL, 0);
1820 while (n && *s1 && *s2)
1823 c1 = (gint)(guchar) TOLOWER (*s1);
1824 c2 = (gint)(guchar) TOLOWER (*s2);
1831 return (((gint) (guchar) *s1) - ((gint) (guchar) *s2));
1839 * @s2: a string to compare with @s1.
1841 * A case-insensitive string comparison, corresponding to the standard
1842 * strcasecmp() function on platforms which support it.
1844 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1845 * or a positive value if @s1 > @s2.
1847 * Deprecated:2.2: See g_strncasecmp() for a discussion of why this function
1848 * is deprecated and how to replace it.
1851 g_strcasecmp (const gchar *s1,
1854 #ifdef HAVE_STRCASECMP
1855 g_return_val_if_fail (s1 != NULL, 0);
1856 g_return_val_if_fail (s2 != NULL, 0);
1858 return strcasecmp (s1, s2);
1862 g_return_val_if_fail (s1 != NULL, 0);
1863 g_return_val_if_fail (s2 != NULL, 0);
1867 /* According to A. Cox, some platforms have islower's that
1868 * don't work right on non-uppercase
1870 c1 = isupper ((guchar)*s1) ? tolower ((guchar)*s1) : *s1;
1871 c2 = isupper ((guchar)*s2) ? tolower ((guchar)*s2) : *s2;
1877 return (((gint)(guchar) *s1) - ((gint)(guchar) *s2));
1884 * @s2: a string to compare with @s1.
1885 * @n: the maximum number of characters to compare.
1887 * A case-insensitive string comparison, corresponding to the standard
1888 * strncasecmp() function on platforms which support it.
1889 * It is similar to g_strcasecmp() except it only compares the first @n
1890 * characters of the strings.
1892 * Return value: 0 if the strings match, a negative value if @s1 < @s2,
1893 * or a positive value if @s1 > @s2.
1895 * Deprecated:2.2: The problem with g_strncasecmp() is that it does the
1896 * comparison by calling toupper()/tolower(). These functions are
1897 * locale-specific and operate on single bytes. However, it is impossible
1898 * to handle things correctly from an I18N standpoint by operating on
1899 * bytes, since characters may be multibyte. Thus g_strncasecmp() is
1900 * broken if your string is guaranteed to be ASCII, since it's
1901 * locale-sensitive, and it's broken if your string is localized, since
1902 * it doesn't work on many encodings at all, including UTF-8, EUC-JP,
1905 * There are therefore two replacement techniques: g_ascii_strncasecmp(),
1906 * which only works on ASCII and is not locale-sensitive, and
1907 * g_utf8_casefold() followed by strcmp() on the resulting strings, which is
1908 * good for case-insensitive sorting of UTF-8.
1911 g_strncasecmp (const gchar *s1,
1915 #ifdef HAVE_STRNCASECMP
1916 return strncasecmp (s1, s2, n);
1920 g_return_val_if_fail (s1 != NULL, 0);
1921 g_return_val_if_fail (s2 != NULL, 0);
1923 while (n && *s1 && *s2)
1926 /* According to A. Cox, some platforms have islower's that
1927 * don't work right on non-uppercase
1929 c1 = isupper ((guchar)*s1) ? tolower ((guchar)*s1) : *s1;
1930 c2 = isupper ((guchar)*s2) ? tolower ((guchar)*s2) : *s2;
1937 return (((gint) (guchar) *s1) - ((gint) (guchar) *s2));
1945 * @string: the string to convert
1946 * @delimiters: (allow-none): a string containing the current delimiters, or %NULL
1947 * to use the standard delimiters defined in #G_STR_DELIMITERS
1948 * @new_delimiter: the new delimiter character
1950 * Converts any delimiter characters in @string to @new_delimiter.
1951 * Any characters in @string which are found in @delimiters are
1952 * changed to the @new_delimiter character. Modifies @string in place,
1953 * and returns @string itself, not a copy. The return value is to
1954 * allow nesting such as
1956 * g_ascii_strup (g_strdelimit (str, "abc", '?'))
1962 g_strdelimit (gchar *string,
1963 const gchar *delimiters,
1968 g_return_val_if_fail (string != NULL, NULL);
1971 delimiters = G_STR_DELIMITERS;
1973 for (c = string; *c; c++)
1975 if (strchr (delimiters, *c))
1984 * @string: a nul-terminated array of bytes
1985 * @valid_chars: bytes permitted in @string
1986 * @substitutor: replacement character for disallowed bytes
1988 * For each character in @string, if the character is not in
1989 * @valid_chars, replaces the character with @substitutor.
1990 * Modifies @string in place, and return @string itself, not
1991 * a copy. The return value is to allow nesting such as
1993 * g_ascii_strup (g_strcanon (str, "abc", '?'))
1999 g_strcanon (gchar *string,
2000 const gchar *valid_chars,
2005 g_return_val_if_fail (string != NULL, NULL);
2006 g_return_val_if_fail (valid_chars != NULL, NULL);
2008 for (c = string; *c; c++)
2010 if (!strchr (valid_chars, *c))
2019 * @source: a string to compress
2021 * Replaces all escaped characters with their one byte equivalent.
2023 * This function does the reverse conversion of g_strescape().
2025 * Returns: a newly-allocated copy of @source with all escaped
2026 * character compressed
2029 g_strcompress (const gchar *source)
2031 const gchar *p = source, *octal;
2035 g_return_val_if_fail (source != NULL, NULL);
2037 dest = g_malloc (strlen (source) + 1);
2048 g_warning ("g_strcompress: trailing \\");
2050 case '0': case '1': case '2': case '3': case '4':
2051 case '5': case '6': case '7':
2054 while ((p < octal + 3) && (*p >= '0') && (*p <= '7'))
2056 *q = (*q * 8) + (*p - '0');
2080 default: /* Also handles \" and \\ */
2097 * @source: a string to escape
2098 * @exceptions: a string of characters not to escape in @source
2100 * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
2101 * and '"' in the string @source by inserting a '\' before
2102 * them. Additionally all characters in the range 0x01-0x1F (everything
2103 * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
2104 * replaced with a '\' followed by their octal representation.
2105 * Characters supplied in @exceptions are not escaped.
2107 * g_strcompress() does the reverse conversion.
2109 * Returns: a newly-allocated copy of @source with certain
2110 * characters escaped. See above.
2113 g_strescape (const gchar *source,
2114 const gchar *exceptions)
2121 g_return_val_if_fail (source != NULL, NULL);
2123 p = (guchar *) source;
2124 /* Each source byte needs maximally four destination chars (\777) */
2125 q = dest = g_malloc (strlen (source) * 4 + 1);
2127 memset (excmap, 0, 256);
2130 guchar *e = (guchar *) exceptions;
2180 if ((*p < ' ') || (*p >= 0177))
2183 *q++ = '0' + (((*p) >> 6) & 07);
2184 *q++ = '0' + (((*p) >> 3) & 07);
2185 *q++ = '0' + ((*p) & 07);
2200 * @string: a string to remove the leading whitespace from
2202 * Removes leading whitespace from a string, by moving the rest
2203 * of the characters forward.
2205 * This function doesn't allocate or reallocate any memory;
2206 * it modifies @string in place. The pointer to @string is
2207 * returned to allow the nesting of functions.
2209 * Also see g_strchomp() and g_strstrip().
2214 g_strchug (gchar *string)
2218 g_return_val_if_fail (string != NULL, NULL);
2220 for (start = (guchar*) string; *start && g_ascii_isspace (*start); start++)
2223 g_memmove (string, start, strlen ((gchar *) start) + 1);
2230 * @string: a string to remove the trailing whitespace from
2232 * Removes trailing whitespace from a string.
2234 * This function doesn't allocate or reallocate any memory;
2235 * it modifies @string in place. The pointer to @string is
2236 * returned to allow the nesting of functions.
2238 * Also see g_strchug() and g_strstrip().
2243 g_strchomp (gchar *string)
2247 g_return_val_if_fail (string != NULL, NULL);
2249 len = strlen (string);
2252 if (g_ascii_isspace ((guchar) string[len]))
2263 * @string: a string to split
2264 * @delimiter: a string which specifies the places at which to split
2265 * the string. The delimiter is not included in any of the resulting
2266 * strings, unless @max_tokens is reached.
2267 * @max_tokens: the maximum number of pieces to split @string into.
2268 * If this is less than 1, the string is split completely.
2270 * Splits a string into a maximum of @max_tokens pieces, using the given
2271 * @delimiter. If @max_tokens is reached, the remainder of @string is
2272 * appended to the last token.
2274 * As a special case, the result of splitting the empty string "" is an empty
2275 * vector, not a vector containing a single string. The reason for this
2276 * special case is that being able to represent a empty vector is typically
2277 * more useful than consistent handling of empty elements. If you do need
2278 * to represent empty elements, you'll need to check for the empty string
2279 * before calling g_strsplit().
2281 * Return value: a newly-allocated %NULL-terminated array of strings. Use
2282 * g_strfreev() to free it.
2285 g_strsplit (const gchar *string,
2286 const gchar *delimiter,
2289 GSList *string_list = NULL, *slist;
2290 gchar **str_array, *s;
2292 const gchar *remainder;
2294 g_return_val_if_fail (string != NULL, NULL);
2295 g_return_val_if_fail (delimiter != NULL, NULL);
2296 g_return_val_if_fail (delimiter[0] != '\0', NULL);
2299 max_tokens = G_MAXINT;
2302 s = strstr (remainder, delimiter);
2305 gsize delimiter_len = strlen (delimiter);
2307 while (--max_tokens && s)
2311 len = s - remainder;
2312 string_list = g_slist_prepend (string_list,
2313 g_strndup (remainder, len));
2315 remainder = s + delimiter_len;
2316 s = strstr (remainder, delimiter);
2322 string_list = g_slist_prepend (string_list, g_strdup (remainder));
2325 str_array = g_new (gchar*, n + 1);
2327 str_array[n--] = NULL;
2328 for (slist = string_list; slist; slist = slist->next)
2329 str_array[n--] = slist->data;
2331 g_slist_free (string_list);
2338 * @string: The string to be tokenized
2339 * @delimiters: A nul-terminated string containing bytes that are used
2340 * to split the string.
2341 * @max_tokens: The maximum number of tokens to split @string into.
2342 * If this is less than 1, the string is split completely
2344 * Splits @string into a number of tokens not containing any of the characters
2345 * in @delimiter. A token is the (possibly empty) longest string that does not
2346 * contain any of the characters in @delimiters. If @max_tokens is reached, the
2347 * remainder is appended to the last token.
2349 * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
2350 * %NULL-terminated vector containing the three strings "abc", "def",
2353 * The result if g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
2354 * vector containing the four strings "", "def", "ghi", and "".
2356 * As a special case, the result of splitting the empty string "" is an empty
2357 * vector, not a vector containing a single string. The reason for this
2358 * special case is that being able to represent a empty vector is typically
2359 * more useful than consistent handling of empty elements. If you do need
2360 * to represent empty elements, you'll need to check for the empty string
2361 * before calling g_strsplit_set().
2363 * Note that this function works on bytes not characters, so it can't be used
2364 * to delimit UTF-8 strings for anything but ASCII characters.
2366 * Return value: a newly-allocated %NULL-terminated array of strings. Use
2367 * g_strfreev() to free it.
2372 g_strsplit_set (const gchar *string,
2373 const gchar *delimiters,
2376 gboolean delim_table[256];
2377 GSList *tokens, *list;
2380 const gchar *current;
2384 g_return_val_if_fail (string != NULL, NULL);
2385 g_return_val_if_fail (delimiters != NULL, NULL);
2388 max_tokens = G_MAXINT;
2390 if (*string == '\0')
2392 result = g_new (char *, 1);
2397 memset (delim_table, FALSE, sizeof (delim_table));
2398 for (s = delimiters; *s != '\0'; ++s)
2399 delim_table[*(guchar *)s] = TRUE;
2404 s = current = string;
2407 if (delim_table[*(guchar *)s] && n_tokens + 1 < max_tokens)
2409 token = g_strndup (current, s - current);
2410 tokens = g_slist_prepend (tokens, token);
2419 token = g_strndup (current, s - current);
2420 tokens = g_slist_prepend (tokens, token);
2423 result = g_new (gchar *, n_tokens + 1);
2425 result[n_tokens] = NULL;
2426 for (list = tokens; list != NULL; list = list->next)
2427 result[--n_tokens] = list->data;
2429 g_slist_free (tokens);
2436 * @str_array: a %NULL-terminated array of strings to free
2438 * Frees a %NULL-terminated array of strings, and the array itself.
2439 * If called on a %NULL value, g_strfreev() simply returns.
2442 g_strfreev (gchar **str_array)
2448 for (i = 0; str_array[i] != NULL; i++)
2449 g_free (str_array[i]);
2457 * @str_array: a %NULL-terminated array of strings
2459 * Copies %NULL-terminated array of strings. The copy is a deep copy;
2460 * the new array should be freed by first freeing each string, then
2461 * the array itself. g_strfreev() does this for you. If called
2462 * on a %NULL value, g_strdupv() simply returns %NULL.
2464 * Return value: a new %NULL-terminated array of strings.
2467 g_strdupv (gchar **str_array)
2475 while (str_array[i])
2478 retval = g_new (gchar*, i + 1);
2481 while (str_array[i])
2483 retval[i] = g_strdup (str_array[i]);
2496 * @separator: (allow-none): a string to insert between each of the strings, or %NULL
2497 * @str_array: a %NULL-terminated array of strings to join
2499 * Joins a number of strings together to form one long string, with the
2500 * optional @separator inserted between each of them. The returned string
2501 * should be freed with g_free().
2503 * Returns: a newly-allocated string containing all of the strings joined
2504 * together, with @separator between them
2507 g_strjoinv (const gchar *separator,
2513 g_return_val_if_fail (str_array != NULL, NULL);
2515 if (separator == NULL)
2522 gsize separator_len;
2524 separator_len = strlen (separator);
2525 /* First part, getting length */
2526 len = 1 + strlen (str_array[0]);
2527 for (i = 1; str_array[i] != NULL; i++)
2528 len += strlen (str_array[i]);
2529 len += separator_len * (i - 1);
2531 /* Second part, building string */
2532 string = g_new (gchar, len);
2533 ptr = g_stpcpy (string, *str_array);
2534 for (i = 1; str_array[i] != NULL; i++)
2536 ptr = g_stpcpy (ptr, separator);
2537 ptr = g_stpcpy (ptr, str_array[i]);
2541 string = g_strdup ("");
2548 * @separator: (allow-none): a string to insert between each of the strings, or %NULL
2549 * @...: a %NULL-terminated list of strings to join
2551 * Joins a number of strings together to form one long string, with the
2552 * optional @separator inserted between each of them. The returned string
2553 * should be freed with g_free().
2555 * Returns: a newly-allocated string containing all of the strings joined
2556 * together, with @separator between them
2559 g_strjoin (const gchar *separator,
2565 gsize separator_len;
2568 if (separator == NULL)
2571 separator_len = strlen (separator);
2573 va_start (args, separator);
2575 s = va_arg (args, gchar*);
2579 /* First part, getting length */
2580 len = 1 + strlen (s);
2582 s = va_arg (args, gchar*);
2585 len += separator_len + strlen (s);
2586 s = va_arg (args, gchar*);
2590 /* Second part, building string */
2591 string = g_new (gchar, len);
2593 va_start (args, separator);
2595 s = va_arg (args, gchar*);
2596 ptr = g_stpcpy (string, s);
2598 s = va_arg (args, gchar*);
2601 ptr = g_stpcpy (ptr, separator);
2602 ptr = g_stpcpy (ptr, s);
2603 s = va_arg (args, gchar*);
2607 string = g_strdup ("");
2617 * @haystack: a string
2618 * @haystack_len: the maximum length of @haystack. Note that -1 is
2619 * a valid length, if @haystack is nul-terminated, meaning it will
2620 * search through the whole string.
2621 * @needle: the string to search for
2623 * Searches the string @haystack for the first occurrence
2624 * of the string @needle, limiting the length of the search
2627 * Return value: a pointer to the found occurrence, or
2628 * %NULL if not found.
2631 g_strstr_len (const gchar *haystack,
2632 gssize haystack_len,
2633 const gchar *needle)
2635 g_return_val_if_fail (haystack != NULL, NULL);
2636 g_return_val_if_fail (needle != NULL, NULL);
2638 if (haystack_len < 0)
2639 return strstr (haystack, needle);
2642 const gchar *p = haystack;
2643 gsize needle_len = strlen (needle);
2647 if (needle_len == 0)
2648 return (gchar *)haystack;
2650 if (haystack_len < needle_len)
2653 end = haystack + haystack_len - needle_len;
2655 while (p <= end && *p)
2657 for (i = 0; i < needle_len; i++)
2658 if (p[i] != needle[i])
2673 * @haystack: a nul-terminated string
2674 * @needle: the nul-terminated string to search for
2676 * Searches the string @haystack for the last occurrence
2677 * of the string @needle.
2679 * Return value: a pointer to the found occurrence, or
2680 * %NULL if not found.
2683 g_strrstr (const gchar *haystack,
2684 const gchar *needle)
2691 g_return_val_if_fail (haystack != NULL, NULL);
2692 g_return_val_if_fail (needle != NULL, NULL);
2694 needle_len = strlen (needle);
2695 haystack_len = strlen (haystack);
2697 if (needle_len == 0)
2698 return (gchar *)haystack;
2700 if (haystack_len < needle_len)
2703 p = haystack + haystack_len - needle_len;
2705 while (p >= haystack)
2707 for (i = 0; i < needle_len; i++)
2708 if (p[i] != needle[i])
2722 * @haystack: a nul-terminated string
2723 * @haystack_len: the maximum length of @haystack
2724 * @needle: the nul-terminated string to search for
2726 * Searches the string @haystack for the last occurrence
2727 * of the string @needle, limiting the length of the search
2730 * Return value: a pointer to the found occurrence, or
2731 * %NULL if not found.
2734 g_strrstr_len (const gchar *haystack,
2735 gssize haystack_len,
2736 const gchar *needle)
2738 g_return_val_if_fail (haystack != NULL, NULL);
2739 g_return_val_if_fail (needle != NULL, NULL);
2741 if (haystack_len < 0)
2742 return g_strrstr (haystack, needle);
2745 gsize needle_len = strlen (needle);
2746 const gchar *haystack_max = haystack + haystack_len;
2747 const gchar *p = haystack;
2750 while (p < haystack_max && *p)
2753 if (p < haystack + needle_len)
2758 while (p >= haystack)
2760 for (i = 0; i < needle_len; i++)
2761 if (p[i] != needle[i])
2777 * @str: a nul-terminated string
2778 * @suffix: the nul-terminated suffix to look for
2780 * Looks whether the string @str ends with @suffix.
2782 * Return value: %TRUE if @str end with @suffix, %FALSE otherwise.
2787 g_str_has_suffix (const gchar *str,
2788 const gchar *suffix)
2793 g_return_val_if_fail (str != NULL, FALSE);
2794 g_return_val_if_fail (suffix != NULL, FALSE);
2796 str_len = strlen (str);
2797 suffix_len = strlen (suffix);
2799 if (str_len < suffix_len)
2802 return strcmp (str + str_len - suffix_len, suffix) == 0;
2807 * @str: a nul-terminated string
2808 * @prefix: the nul-terminated prefix to look for
2810 * Looks whether the string @str begins with @prefix.
2812 * Return value: %TRUE if @str begins with @prefix, %FALSE otherwise.
2817 g_str_has_prefix (const gchar *str,
2818 const gchar *prefix)
2823 g_return_val_if_fail (str != NULL, FALSE);
2824 g_return_val_if_fail (prefix != NULL, FALSE);
2826 str_len = strlen (str);
2827 prefix_len = strlen (prefix);
2829 if (str_len < prefix_len)
2832 return strncmp (str, prefix, prefix_len) == 0;
2837 * @str_array: a %NULL-terminated array of strings
2839 * Returns the length of the given %NULL-terminated
2840 * string array @str_array.
2842 * Return value: length of @str_array.
2847 g_strv_length (gchar **str_array)
2851 g_return_val_if_fail (str_array != NULL, 0);
2853 while (str_array[i])
2860 index_add_folded (GPtrArray *array,
2866 normal = g_utf8_normalize (start, end - start, G_NORMALIZE_ALL_COMPOSE);
2868 /* TODO: Invent time machine. Converse with Mustafa Ataturk... */
2869 if (strstr (normal, "ı") || strstr (normal, "İ"))
2874 tmp = g_string_new (NULL);
2880 i = strstr (s, "ı");
2881 I = strstr (s, "İ");
2894 g_string_append_len (tmp, s, e - s);
2895 g_string_append_c (tmp, 'i');
2896 s = g_utf8_next_char (e);
2899 g_string_append (tmp, s);
2901 normal = g_string_free (tmp, FALSE);
2904 g_ptr_array_add (array, g_utf8_casefold (normal, -1));
2909 split_words (const gchar *value)
2911 const gchar *start = NULL;
2915 result = g_ptr_array_new ();
2917 for (s = value; *s; s = g_utf8_next_char (s))
2919 gunichar c = g_utf8_get_char (s);
2923 if (g_unichar_isalnum (c) || g_unichar_ismark (c))
2928 if (!g_unichar_isalnum (c) && !g_unichar_ismark (c))
2930 index_add_folded (result, start, s);
2937 index_add_folded (result, start, s);
2939 g_ptr_array_add (result, NULL);
2941 return (gchar **) g_ptr_array_free (result, FALSE);
2945 * g_str_tokenize_and_fold:
2947 * @translit_locale: (allow-none): the language code (like 'de' or
2948 * 'en_GB') from which @string originates
2949 * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a
2950 * return location for ASCII alternates
2952 * Tokenises @string and performs folding on each token.
2954 * A token is a non-empty sequence of alphanumeric characters in the
2955 * source string, separated by non-alphanumeric characters. An
2956 * "alphanumeric" character for this purpose is one that matches
2957 * g_unichar_isalnum() or g_unichar_ismark().
2959 * Each token is then (Unicode) normalised and case-folded. If
2960 * @ascii_alternates is non-%NULL and some of the returned tokens
2961 * contain non-ASCII characters, ASCII alternatives will be generated.
2963 * The number of ASCII alternatives that are generated and the method
2964 * for doing so is unspecified, but @translit_locale (if specified) may
2965 * improve the transliteration if the language of the source string is
2968 * Returns: the folded tokens
2973 g_str_tokenize_and_fold (const gchar *string,
2974 const gchar *translit_locale,
2975 gchar ***ascii_alternates)
2979 if (ascii_alternates && g_str_is_ascii (string))
2981 *ascii_alternates = g_new0 (gchar *, 0 + 1);
2982 ascii_alternates = NULL;
2985 result = split_words (string);
2987 /* TODO: proper iconv transliteration (locale-dependent) */
2988 if (ascii_alternates)
2992 n = g_strv_length (result);
2993 *ascii_alternates = g_new (gchar *, n + 1);
2996 for (i = 0; i < n; i++)
2998 if (!g_str_is_ascii (result[i]))
3005 decomposed = g_utf8_normalize (result[i], -1, G_NORMALIZE_ALL);
3006 ascii = g_malloc (strlen (decomposed) + 1);
3008 for (k = 0; decomposed[k]; k++)
3009 if (~decomposed[k] & 0x80)
3010 ascii[l++] = decomposed[k];
3013 (*ascii_alternates)[j++] = ascii;
3014 g_free (decomposed);
3018 (*ascii_alternates)[j] = NULL;
3025 * g_str_match_string:
3026 * @search_term: the search term from the user
3027 * @potential_hit: the text that may be a hit
3028 * @accept_alternates: %TRUE to accept ASCII alternates
3030 * Checks if a search conducted for @search_term should match
3033 * This function calls g_str_tokenize_and_fold() on both
3034 * @search_term and @potential_hit. ASCII alternates are never taken
3035 * for @search_term but will be taken for @potential_hit according to
3036 * the value of @accept_alternates.
3038 * A hit occurs when each folded token in @search_term is a prefix of a
3039 * folded token from @potential_hit.
3041 * Depending on how you're performing the search, it will typically be
3042 * faster to call g_str_tokenize_and_fold() on each string in
3043 * your corpus and build an index on the returned folded tokens, then
3044 * call g_str_tokenize_and_fold() on the search term and
3045 * perform lookups into that index.
3047 * As some examples, searching for "fred" would match the potential hit
3048 * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match
3049 * "Frédéric" but not "Frederic" (due to the one-directional nature of
3050 * accent matching). Searching "fo" would match "Foo" and "Bar Foo
3051 * Baz", but not "SFO" (because no word as "fo" as a prefix).
3053 * Returns: %TRUE if @potential_hit is a hit
3058 g_str_match_string (const gchar *search_term,
3059 const gchar *potential_hit,
3060 gboolean accept_alternates)
3062 gchar **alternates = NULL;
3063 gchar **term_tokens;
3068 term_tokens = g_str_tokenize_and_fold (search_term, NULL, NULL);
3069 hit_tokens = g_str_tokenize_and_fold (potential_hit, NULL, accept_alternates ? &alternates : NULL);
3073 for (i = 0; term_tokens[i]; i++)
3075 for (j = 0; hit_tokens[j]; j++)
3076 if (g_str_has_prefix (hit_tokens[j], term_tokens[i]))
3079 if (accept_alternates)
3080 for (j = 0; alternates[j]; j++)
3081 if (g_str_has_prefix (alternates[j], term_tokens[i]))
3091 g_strfreev (term_tokens);
3092 g_strfreev (hit_tokens);
3093 g_strfreev (alternates);