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, see <http://www.gnu.org/licenses/>.
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
38 #include <ctype.h> /* For tolower() */
41 /* Needed on BSD/OS X for e.g. strtod_l */
49 /* do not include <unistd.h> here, it may interfere with g_strsignal() */
51 #include "gstrfuncs.h"
54 #include "gprintfint.h"
59 * SECTION:string_utils
60 * @title: String Utility Functions
61 * @short_description: various string-related functions
63 * This section describes a number of utility functions for creating,
64 * duplicating, and manipulating strings.
66 * Note that the functions g_printf(), g_fprintf(), g_sprintf(),
67 * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
68 * are declared in the header `gprintf.h` which is not included in `glib.h`
69 * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
70 * explicitly include `<glib/gprintf.h>` in order to use the GLib
73 * ## String precision pitfalls # {#string-precision}
75 * While you may use the printf() functions to format UTF-8 strings,
76 * notice that the precision of a \%Ns parameter is interpreted
77 * as the number of bytes, not characters to print. On top of that,
78 * the GNU libc implementation of the printf() functions has the
79 * "feature" that it checks that the string given for the \%Ns
80 * parameter consists of a whole number of characters in the current
81 * encoding. So, unless you are sure you are always going to be in an
82 * UTF-8 locale or your know your text is restricted to ASCII, avoid
83 * using \%Ns. If your intention is to format strings for a
84 * certain number of columns, then \%Ns is not a correct solution
85 * anyway, since it fails to take wide characters (see g_unichar_iswide())
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 char, not an int,
99 * so don't call it on %EOF, but no need to cast to #guchar before
100 * 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 char, not an int,
115 * so don't call it on %EOF, but no need to cast to #guchar before
116 * 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 char, not
131 * an int, so don't call it on %EOF, but no need to cast to #guchar
132 * 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 char, not an int, so don't call it on %EOF, but no need to
145 * cast to #guchar before passing a possibly non-ASCII character in.
147 * Returns: %TRUE if @c is an ASCII digit.
154 * Determines whether a character is a printing character and not a space.
156 * Unlike the standard C library isgraph() function, this only
157 * recognizes standard ASCII characters and ignores the locale,
158 * returning %FALSE for all non-ASCII characters. Also, unlike
159 * the standard library function, this takes a char, not an int,
160 * so don't call it on %EOF, but no need to cast to #guchar before
161 * passing a possibly non-ASCII character in.
163 * Returns: %TRUE if @c is an ASCII printing character other than space.
170 * Determines whether a character is an ASCII lower case letter.
172 * Unlike the standard C library islower() function, this only
173 * recognizes standard ASCII letters and ignores the locale,
174 * returning %FALSE for all non-ASCII characters. Also, unlike
175 * the standard library function, this takes a char, not an int,
176 * so don't call it on %EOF, but no need to worry about casting
177 * to #guchar before passing a possibly non-ASCII character in.
179 * Returns: %TRUE if @c is an ASCII lower case letter
186 * Determines whether a character is a printing character.
188 * Unlike the standard C library isprint() function, this only
189 * recognizes standard ASCII characters and ignores the locale,
190 * returning %FALSE for all non-ASCII characters. Also, unlike
191 * the standard library function, this takes a char, not an int,
192 * so don't call it on %EOF, but no need to cast to #guchar before
193 * passing a possibly non-ASCII character in.
195 * Returns: %TRUE if @c is an ASCII printing character.
202 * Determines whether a character is a punctuation character.
204 * Unlike the standard C library ispunct() function, this only
205 * recognizes standard ASCII letters and ignores the locale,
206 * returning %FALSE for all non-ASCII characters. Also, unlike
207 * the standard library function, this takes a char, not an int,
208 * so don't call it on %EOF, but no need to cast to #guchar before
209 * passing a possibly non-ASCII character in.
211 * Returns: %TRUE if @c is an ASCII punctuation character.
218 * Determines whether a character is a white-space character.
220 * Unlike the standard C library isspace() function, this only
221 * recognizes standard ASCII white-space and ignores the locale,
222 * returning %FALSE for all non-ASCII characters. Also, unlike
223 * the standard library function, this takes a char, not an int,
224 * so don't call it on %EOF, but no need to cast to #guchar before
225 * passing a possibly non-ASCII character in.
227 * Returns: %TRUE if @c is an ASCII white-space character
234 * Determines whether a character is an ASCII upper case letter.
236 * Unlike the standard C library isupper() function, this only
237 * recognizes standard ASCII letters and ignores the locale,
238 * returning %FALSE for all non-ASCII characters. Also, unlike
239 * the standard library function, this takes a char, not an int,
240 * so don't call it on %EOF, but no need to worry about casting
241 * to #guchar before passing a possibly non-ASCII character in.
243 * Returns: %TRUE if @c is an ASCII upper case letter
250 * Determines whether a character is a hexadecimal-digit character.
252 * Unlike the standard C library isxdigit() function, this takes
253 * a char, not an int, so don't call it on %EOF, but no need to
254 * cast to #guchar before passing a possibly non-ASCII character in.
256 * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
260 * G_ASCII_DTOSTR_BUF_SIZE:
262 * A good size for a buffer to be passed into g_ascii_dtostr().
263 * It is guaranteed to be enough for all output of that function
264 * on systems with 64bit IEEE-compatible doubles.
266 * The typical usage would be something like:
267 * |[<!-- language="C" -->
268 * char buf[G_ASCII_DTOSTR_BUF_SIZE];
270 * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
276 * @string: a string to remove the leading and trailing whitespace from
278 * Removes leading and trailing whitespace from a string.
279 * See g_strchomp() and g_strchug().
287 * The standard delimiters, used in g_strdelimit().
290 static const guint16 ascii_table_data
[256] = {
291 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
292 0x004, 0x104, 0x104, 0x004, 0x104, 0x104, 0x004, 0x004,
293 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
294 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004, 0x004,
295 0x140, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
296 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
297 0x459, 0x459, 0x459, 0x459, 0x459, 0x459, 0x459, 0x459,
298 0x459, 0x459, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
299 0x0d0, 0x653, 0x653, 0x653, 0x653, 0x653, 0x653, 0x253,
300 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253,
301 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253, 0x253,
302 0x253, 0x253, 0x253, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x0d0,
303 0x0d0, 0x473, 0x473, 0x473, 0x473, 0x473, 0x473, 0x073,
304 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073,
305 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073, 0x073,
306 0x073, 0x073, 0x073, 0x0d0, 0x0d0, 0x0d0, 0x0d0, 0x004
307 /* the upper 128 are all zeroes */
310 const guint16
* const g_ascii_table
= ascii_table_data
;
312 #if defined (HAVE_NEWLOCALE) && \
313 defined (HAVE_USELOCALE) && \
314 defined (HAVE_STRTOD_L) && \
315 defined (HAVE_STRTOULL_L) && \
316 defined (HAVE_STRTOLL_L)
317 #define USE_XLOCALE 1
324 static gsize initialized
= FALSE
;
325 static locale_t C_locale
= NULL
;
327 if (g_once_init_enter (&initialized
))
329 C_locale
= newlocale (LC_ALL_MASK
, "C", NULL
);
330 g_once_init_leave (&initialized
, TRUE
);
339 * @str: the string to duplicate
341 * Duplicates a string. If @str is %NULL it returns %NULL.
342 * The returned string should be freed with g_free()
343 * when no longer needed.
345 * Returns: a newly-allocated copy of @str
348 g_strdup (const gchar
*str
)
355 length
= strlen (str
) + 1;
356 new_str
= g_new (char, length
);
357 memcpy (new_str
, str
, length
);
367 * @mem: the memory to copy.
368 * @byte_size: the number of bytes to copy.
370 * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
371 * from @mem. If @mem is %NULL it returns %NULL.
373 * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
377 g_memdup (gconstpointer mem
,
384 new_mem
= g_malloc (byte_size
);
385 memcpy (new_mem
, mem
, byte_size
);
395 * @str: the string to duplicate
396 * @n: the maximum number of bytes to copy from @str
398 * Duplicates the first @n bytes of a string, returning a newly-allocated
399 * buffer @n + 1 bytes long which will always be nul-terminated. If @str
400 * is less than @n bytes long the buffer is padded with nuls. If @str is
401 * %NULL it returns %NULL. The returned value should be freed when no longer
404 * To copy a number of characters from a UTF-8 encoded string,
405 * use g_utf8_strncpy() instead.
407 * Returns: a newly-allocated buffer containing the first @n bytes
408 * of @str, nul-terminated
411 g_strndup (const gchar
*str
,
418 new_str
= g_new (gchar
, n
+ 1);
419 strncpy (new_str
, str
, n
);
430 * @length: the length of the new string
431 * @fill_char: the byte to fill the string with
433 * Creates a new string @length bytes long filled with @fill_char.
434 * The returned string should be freed when no longer needed.
436 * Returns: a newly-allocated string filled the @fill_char
439 g_strnfill (gsize length
,
444 str
= g_new (gchar
, length
+ 1);
445 memset (str
, (guchar
)fill_char
, length
);
453 * @dest: destination buffer.
454 * @src: source string.
456 * Copies a nul-terminated string into the dest buffer, include the
457 * trailing nul, and return a pointer to the trailing nul byte.
458 * This is useful for concatenating multiple strings together
459 * without having to repeatedly scan for the end.
461 * Returns: a pointer to trailing nul byte.
464 g_stpcpy (gchar
*dest
,
468 g_return_val_if_fail (dest
!= NULL
, NULL
);
469 g_return_val_if_fail (src
!= NULL
, NULL
);
470 return stpcpy (dest
, src
);
473 const gchar
*s
= src
;
475 g_return_val_if_fail (dest
!= NULL
, NULL
);
476 g_return_val_if_fail (src
!= NULL
, NULL
);
479 while (*s
++ != '\0');
487 * @format: a standard printf() format string, but notice
488 * [string precision pitfalls][string-precision]
489 * @args: the list of parameters to insert into the format string
491 * Similar to the standard C vsprintf() function but safer, since it
492 * calculates the maximum space required and allocates memory to hold
493 * the result. The returned string should be freed with g_free() when
496 * See also g_vasprintf(), which offers the same functionality, but
497 * additionally returns the length of the allocated string.
499 * Returns: a newly-allocated string holding the result
502 g_strdup_vprintf (const gchar
*format
,
505 gchar
*string
= NULL
;
507 g_vasprintf (&string
, format
, args
);
514 * @format: a standard printf() format string, but notice
515 * [string precision pitfalls][string-precision]
516 * @...: the parameters to insert into the format string
518 * Similar to the standard C sprintf() function but safer, since it
519 * calculates the maximum space required and allocates memory to hold
520 * the result. The returned string should be freed with g_free() when no
523 * Returns: a newly-allocated string holding the result
526 g_strdup_printf (const gchar
*format
,
532 va_start (args
, format
);
533 buffer
= g_strdup_vprintf (format
, args
);
541 * @string1: the first string to add, which must not be %NULL
542 * @...: a %NULL-terminated list of strings to append to the string
544 * Concatenates all of the given strings into one long string. The
545 * returned string should be freed with g_free() when no longer needed.
547 * The variable argument list must end with %NULL. If you forget the %NULL,
548 * g_strconcat() will start appending random memory junk to your string.
550 * Note that this function is usually not the right function to use to
551 * assemble a translated message from pieces, since proper translation
552 * often requires the pieces to be reordered.
554 * Returns: a newly-allocated string containing all the string arguments
557 g_strconcat (const gchar
*string1
, ...)
568 l
= 1 + strlen (string1
);
569 va_start (args
, string1
);
570 s
= va_arg (args
, gchar
*);
574 s
= va_arg (args
, gchar
*);
578 concat
= g_new (gchar
, l
);
581 ptr
= g_stpcpy (ptr
, string1
);
582 va_start (args
, string1
);
583 s
= va_arg (args
, gchar
*);
586 ptr
= g_stpcpy (ptr
, s
);
587 s
= va_arg (args
, gchar
*);
596 * @nptr: the string to convert to a numeric value.
597 * @endptr: if non-%NULL, it returns the character after
598 * the last character used in the conversion.
600 * Converts a string to a #gdouble value.
601 * It calls the standard strtod() function to handle the conversion, but
602 * if the string is not completely converted it attempts the conversion
603 * again with g_ascii_strtod(), and returns the best match.
605 * This function should seldom be used. The normal situation when reading
606 * numbers not for human consumption is to use g_ascii_strtod(). Only when
607 * you know that you must expect both locale formatted and C formatted numbers
608 * should you use this. Make sure that you don't pass strings such as comma
609 * separated lists of values, since the commas may be interpreted as a decimal
610 * point in some locales, causing unexpected results.
612 * Returns: the #gdouble value.
615 g_strtod (const gchar
*nptr
,
623 g_return_val_if_fail (nptr
!= NULL
, 0);
628 val_1
= strtod (nptr
, &fail_pos_1
);
630 if (fail_pos_1
&& fail_pos_1
[0] != 0)
631 val_2
= g_ascii_strtod (nptr
, &fail_pos_2
);
633 if (!fail_pos_1
|| fail_pos_1
[0] == 0 || fail_pos_1
>= fail_pos_2
)
636 *endptr
= fail_pos_1
;
642 *endptr
= fail_pos_2
;
649 * @nptr: the string to convert to a numeric value.
650 * @endptr: if non-%NULL, it returns the character after
651 * the last character used in the conversion.
653 * Converts a string to a #gdouble value.
655 * This function behaves like the standard strtod() function
656 * does in the C locale. It does this without actually changing
657 * the current locale, since that would not be thread-safe.
658 * A limitation of the implementation is that this function
659 * will still accept localized versions of infinities and NANs.
661 * This function is typically used when reading configuration
662 * files or other non-user input that should be locale independent.
663 * To handle input from the user you should normally use the
664 * locale-sensitive system strtod() function.
666 * To convert from a #gdouble to a string in a locale-insensitive
667 * way, use g_ascii_dtostr().
669 * If the correct value would cause overflow, plus or minus %HUGE_VAL
670 * is returned (according to the sign of the value), and %ERANGE is
671 * stored in %errno. If the correct value would cause underflow,
672 * zero is returned and %ERANGE is stored in %errno.
674 * This function resets %errno before calling strtod() so that
675 * you can reliably detect overflow and underflow.
677 * Returns: the #gdouble value.
680 g_ascii_strtod (const gchar
*nptr
,
685 g_return_val_if_fail (nptr
!= NULL
, 0);
689 return strtod_l (nptr
, endptr
, get_C_locale ());
696 struct lconv
*locale_data
;
698 const char *decimal_point
;
699 int decimal_point_len
;
700 const char *p
, *decimal_point_pos
;
701 const char *end
= NULL
; /* Silence gcc */
704 g_return_val_if_fail (nptr
!= NULL
, 0);
709 locale_data
= localeconv ();
710 decimal_point
= locale_data
->decimal_point
;
711 decimal_point_len
= strlen (decimal_point
);
714 decimal_point_len
= 1;
717 g_assert (decimal_point_len
!= 0);
719 decimal_point_pos
= NULL
;
722 if (decimal_point
[0] != '.' ||
723 decimal_point
[1] != 0)
726 /* Skip leading space */
727 while (g_ascii_isspace (*p
))
730 /* Skip leading optional sign */
731 if (*p
== '+' || *p
== '-')
735 (p
[1] == 'x' || p
[1] == 'X'))
738 /* HEX - find the (optional) decimal point */
740 while (g_ascii_isxdigit (*p
))
744 decimal_point_pos
= p
++;
746 while (g_ascii_isxdigit (*p
))
749 if (*p
== 'p' || *p
== 'P')
751 if (*p
== '+' || *p
== '-')
753 while (g_ascii_isdigit (*p
))
758 else if (g_ascii_isdigit (*p
) || *p
== '.')
760 while (g_ascii_isdigit (*p
))
764 decimal_point_pos
= p
++;
766 while (g_ascii_isdigit (*p
))
769 if (*p
== 'e' || *p
== 'E')
771 if (*p
== '+' || *p
== '-')
773 while (g_ascii_isdigit (*p
))
778 /* For the other cases, we need not convert the decimal point */
781 if (decimal_point_pos
)
785 /* We need to convert the '.' to the locale specific decimal point */
786 copy
= g_malloc (end
- nptr
+ 1 + decimal_point_len
);
789 memcpy (c
, nptr
, decimal_point_pos
- nptr
);
790 c
+= decimal_point_pos
- nptr
;
791 memcpy (c
, decimal_point
, decimal_point_len
);
792 c
+= decimal_point_len
;
793 memcpy (c
, decimal_point_pos
+ 1, end
- (decimal_point_pos
+ 1));
794 c
+= end
- (decimal_point_pos
+ 1);
798 val
= strtod (copy
, &fail_pos
);
799 strtod_errno
= errno
;
803 if (fail_pos
- copy
> decimal_point_pos
- nptr
)
804 fail_pos
= (char *)nptr
+ (fail_pos
- copy
) - (decimal_point_len
- 1);
806 fail_pos
= (char *)nptr
+ (fail_pos
- copy
);
816 copy
= g_malloc (end
- (char *)nptr
+ 1);
817 memcpy (copy
, nptr
, end
- nptr
);
818 *(copy
+ (end
- (char *)nptr
)) = 0;
821 val
= strtod (copy
, &fail_pos
);
822 strtod_errno
= errno
;
826 fail_pos
= (char *)nptr
+ (fail_pos
- copy
);
834 val
= strtod (nptr
, &fail_pos
);
835 strtod_errno
= errno
;
841 errno
= strtod_errno
;
850 * @buffer: A buffer to place the resulting string in
851 * @buf_len: The length of the buffer.
852 * @d: The #gdouble to convert
854 * Converts a #gdouble to a string, using the '.' as
857 * This function generates enough precision that converting
858 * the string back using g_ascii_strtod() gives the same machine-number
859 * (on machines with IEEE compatible 64bit doubles). It is
860 * guaranteed that the size of the resulting string will never
861 * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating
862 * nul character, which is always added.
864 * Returns: The pointer to the buffer with the converted string.
867 g_ascii_dtostr (gchar
*buffer
,
871 return g_ascii_formatd (buffer
, buf_len
, "%.17g", d
);
874 #pragma GCC diagnostic push
875 #pragma GCC diagnostic ignored "-Wformat-nonliteral"
879 * @buffer: A buffer to place the resulting string in
880 * @buf_len: The length of the buffer.
881 * @format: The printf()-style format to use for the
882 * code to use for converting.
883 * @d: The #gdouble to convert
885 * Converts a #gdouble to a string, using the '.' as
886 * decimal point. To format the number you pass in
887 * a printf()-style format string. Allowed conversion
888 * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
890 * The returned buffer is guaranteed to be nul-terminated.
892 * If you just want to want to serialize the value into a
893 * string, use g_ascii_dtostr().
895 * Returns: The pointer to the buffer with the converted string.
898 g_ascii_formatd (gchar
*buffer
,
906 old_locale
= uselocale (get_C_locale ());
907 _g_snprintf (buffer
, buf_len
, format
, d
);
908 uselocale (old_locale
);
913 struct lconv
*locale_data
;
915 const char *decimal_point
;
916 int decimal_point_len
;
921 g_return_val_if_fail (buffer
!= NULL
, NULL
);
922 g_return_val_if_fail (format
[0] == '%', NULL
);
923 g_return_val_if_fail (strpbrk (format
+ 1, "'l%") == NULL
, NULL
);
925 format_char
= format
[strlen (format
) - 1];
927 g_return_val_if_fail (format_char
== 'e' || format_char
== 'E' ||
928 format_char
== 'f' || format_char
== 'F' ||
929 format_char
== 'g' || format_char
== 'G',
932 if (format
[0] != '%')
935 if (strpbrk (format
+ 1, "'l%"))
938 if (!(format_char
== 'e' || format_char
== 'E' ||
939 format_char
== 'f' || format_char
== 'F' ||
940 format_char
== 'g' || format_char
== 'G'))
943 _g_snprintf (buffer
, buf_len
, format
, d
);
946 locale_data
= localeconv ();
947 decimal_point
= locale_data
->decimal_point
;
948 decimal_point_len
= strlen (decimal_point
);
951 decimal_point_len
= 1;
954 g_assert (decimal_point_len
!= 0);
956 if (decimal_point
[0] != '.' ||
957 decimal_point
[1] != 0)
961 while (g_ascii_isspace (*p
))
964 if (*p
== '+' || *p
== '-')
967 while (isdigit ((guchar
)*p
))
970 if (strncmp (p
, decimal_point
, decimal_point_len
) == 0)
974 if (decimal_point_len
> 1)
976 rest_len
= strlen (p
+ (decimal_point_len
-1));
977 memmove (p
, p
+ (decimal_point_len
-1), rest_len
);
986 #pragma GCC diagnostic pop
988 #define ISSPACE(c) ((c) == ' ' || (c) == '\f' || (c) == '\n' || \
989 (c) == '\r' || (c) == '\t' || (c) == '\v')
990 #define ISUPPER(c) ((c) >= 'A' && (c) <= 'Z')
991 #define ISLOWER(c) ((c) >= 'a' && (c) <= 'z')
992 #define ISALPHA(c) (ISUPPER (c) || ISLOWER (c))
993 #define TOUPPER(c) (ISLOWER (c) ? (c) - 'a' + 'A' : (c))
994 #define TOLOWER(c) (ISUPPER (c) ? (c) - 'A' + 'a' : (c))
999 g_parse_long_long (const gchar
*nptr
,
1000 const gchar
**endptr
,
1004 /* this code is based on on the strtol(3) code from GNU libc released under
1005 * the GNU Lesser General Public License.
1007 * Copyright (C) 1991,92,94,95,96,97,98,99,2000,01,02
1008 * Free Software Foundation, Inc.
1014 const gchar
*s
, *save
;
1017 g_return_val_if_fail (nptr
!= NULL
, 0);
1020 if (base
== 1 || base
> 36)
1030 /* Skip white space. */
1031 while (ISSPACE (*s
))
1034 if (G_UNLIKELY (!*s
))
1037 /* Check for a sign. */
1046 /* Recognize number prefix and if BASE is zero, figure it out ourselves. */
1049 if ((base
== 0 || base
== 16) && TOUPPER (s
[1]) == 'X')
1060 /* Save the pointer so we can check later if anything happened. */
1062 cutoff
= G_MAXUINT64
/ base
;
1063 cutlim
= G_MAXUINT64
% base
;
1070 if (c
>= '0' && c
<= '9')
1072 else if (ISALPHA (c
))
1073 c
= TOUPPER (c
) - 'A' + 10;
1078 /* Check for overflow. */
1079 if (ui64
> cutoff
|| (ui64
== cutoff
&& c
> cutlim
))
1088 /* Check if anything actually happened. */
1092 /* Store in ENDPTR the address of one character
1093 past the last character we converted. */
1097 if (G_UNLIKELY (overflow
))
1106 /* We must handle a special case here: the base is 0 or 16 and the
1107 first two characters are '0' and 'x', but the rest are no
1108 hexadecimal digits. This is no error case. We return 0 and
1109 ENDPTR points to the `x`. */
1112 if (save
- nptr
>= 2 && TOUPPER (save
[-1]) == 'X'
1114 *endptr
= &save
[-1];
1116 /* There was no number to convert. */
1121 #endif /* !USE_XLOCALE */
1125 * @nptr: the string to convert to a numeric value.
1126 * @endptr: if non-%NULL, it returns the character after
1127 * the last character used in the conversion.
1128 * @base: to be used for the conversion, 2..36 or 0
1130 * Converts a string to a #guint64 value.
1131 * This function behaves like the standard strtoull() function
1132 * does in the C locale. It does this without actually
1133 * changing the current locale, since that would not be
1136 * This function is typically used when reading configuration
1137 * files or other non-user input that should be locale independent.
1138 * To handle input from the user you should normally use the
1139 * locale-sensitive system strtoull() function.
1141 * If the correct value would cause overflow, %G_MAXUINT64
1142 * is returned, and `ERANGE` is stored in `errno`.
1143 * If the base is outside the valid range, zero is returned, and
1144 * `EINVAL` is stored in `errno`.
1145 * If the string conversion fails, zero is returned, and @endptr returns
1146 * @nptr (if @endptr is non-%NULL).
1148 * Returns: the #guint64 value or zero on error.
1153 g_ascii_strtoull (const gchar
*nptr
,
1158 return strtoull_l (nptr
, endptr
, base
, get_C_locale ());
1163 result
= g_parse_long_long (nptr
, (const gchar
**) endptr
, base
, &negative
);
1165 /* Return the result of the appropriate sign. */
1166 return negative
? -result
: result
;
1172 * @nptr: the string to convert to a numeric value.
1173 * @endptr: if non-%NULL, it returns the character after
1174 * the last character used in the conversion.
1175 * @base: to be used for the conversion, 2..36 or 0
1177 * Converts a string to a #gint64 value.
1178 * This function behaves like the standard strtoll() function
1179 * does in the C locale. It does this without actually
1180 * changing the current locale, since that would not be
1183 * This function is typically used when reading configuration
1184 * files or other non-user input that should be locale independent.
1185 * To handle input from the user you should normally use the
1186 * locale-sensitive system strtoll() function.
1188 * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
1189 * is returned, and `ERANGE` is stored in `errno`.
1190 * If the base is outside the valid range, zero is returned, and
1191 * `EINVAL` is stored in `errno`. If the
1192 * string conversion fails, zero is returned, and @endptr returns @nptr
1193 * (if @endptr is non-%NULL).
1195 * Returns: the #gint64 value or zero on error.
1200 g_ascii_strtoll (const gchar
*nptr
,
1205 return strtoll_l (nptr
, endptr
, base
, get_C_locale ());
1210 result
= g_parse_long_long (nptr
, (const gchar
**) endptr
, base
, &negative
);
1212 if (negative
&& result
> (guint64
) G_MININT64
)
1217 else if (!negative
&& result
> (guint64
) G_MAXINT64
)
1223 return - (gint64
) result
;
1225 return (gint64
) result
;
1231 * @errnum: the system error number. See the standard C %errno
1234 * Returns a string corresponding to the given error code, e.g.
1235 * "no such process". You should use this function in preference to
1236 * strerror(), because it returns a string in UTF-8 encoding, and since
1237 * not all platforms support the strerror() function.
1239 * Returns: a UTF-8 string describing the error code. If the error code
1240 * is unknown, it returns "unknown error (<code>)".
1243 g_strerror (gint errnum
)
1246 gchar
*tofree
= NULL
;
1248 gint saved_errno
= errno
;
1250 msg
= strerror (errnum
);
1251 if (!g_get_charset (NULL
))
1252 msg
= tofree
= g_locale_to_utf8 (msg
, -1, NULL
, NULL
, NULL
);
1254 ret
= g_intern_string (msg
);
1256 errno
= saved_errno
;
1262 * @signum: the signal number. See the `signal` documentation
1264 * Returns a string describing the given signal, e.g. "Segmentation fault".
1265 * You should use this function in preference to strsignal(), because it
1266 * returns a string in UTF-8 encoding, and since not all platforms support
1267 * the strsignal() function.
1269 * Returns: a UTF-8 string describing the signal. If the signal is unknown,
1270 * it returns "unknown signal (<signum>)".
1273 g_strsignal (gint signum
)
1279 msg
= tofree
= NULL
;
1281 #ifdef HAVE_STRSIGNAL
1282 msg
= strsignal (signum
);
1283 if (!g_get_charset (NULL
))
1284 msg
= tofree
= g_locale_to_utf8 (msg
, -1, NULL
, NULL
, NULL
);
1288 msg
= tofree
= g_strdup_printf ("unknown signal (%d)", signum
);
1289 ret
= g_intern_string (msg
);
1295 /* Functions g_strlcpy and g_strlcat were originally developed by
1296 * Todd C. Miller <Todd.Miller@courtesan.com> to simplify writing secure code.
1297 * See http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
1298 * for more information.
1302 /* Use the native ones, if available; they might be implemented in assembly */
1304 g_strlcpy (gchar
*dest
,
1308 g_return_val_if_fail (dest
!= NULL
, 0);
1309 g_return_val_if_fail (src
!= NULL
, 0);
1311 return strlcpy (dest
, src
, dest_size
);
1315 g_strlcat (gchar
*dest
,
1319 g_return_val_if_fail (dest
!= NULL
, 0);
1320 g_return_val_if_fail (src
!= NULL
, 0);
1322 return strlcat (dest
, src
, dest_size
);
1325 #else /* ! HAVE_STRLCPY */
1328 * @dest: destination buffer
1329 * @src: source buffer
1330 * @dest_size: length of @dest in bytes
1332 * Portability wrapper that calls strlcpy() on systems which have it,
1333 * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
1334 * guaranteed to be nul-terminated; @src must be nul-terminated;
1335 * @dest_size is the buffer size, not the number of bytes to copy.
1337 * At most @dest_size - 1 characters will be copied. Always nul-terminates
1338 * (unless @dest_size is 0). This function does not allocate memory. Unlike
1339 * strncpy(), this function doesn't pad @dest (so it's often faster). It
1340 * returns the size of the attempted result, strlen (src), so if
1341 * @retval >= @dest_size, truncation occurred.
1343 * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
1344 * but if you really want to avoid screwups, g_strdup() is an even better
1347 * Returns: length of @src
1350 g_strlcpy (gchar
*dest
,
1355 const gchar
*s
= src
;
1356 gsize n
= dest_size
;
1358 g_return_val_if_fail (dest
!= NULL
, 0);
1359 g_return_val_if_fail (src
!= NULL
, 0);
1361 /* Copy as many bytes as will fit */
1362 if (n
!= 0 && --n
!= 0)
1373 /* If not enough room in dest, add NUL and traverse rest of src */
1382 return s
- src
- 1; /* count does not include NUL */
1387 * @dest: destination buffer, already containing one nul-terminated string
1388 * @src: source buffer
1389 * @dest_size: length of @dest buffer in bytes (not length of existing string
1392 * Portability wrapper that calls strlcat() on systems which have it,
1393 * and emulates it otherwise. Appends nul-terminated @src string to @dest,
1394 * guaranteeing nul-termination for @dest. The total size of @dest won't
1395 * exceed @dest_size.
1397 * At most @dest_size - 1 characters will be copied. Unlike strncat(),
1398 * @dest_size is the full size of dest, not the space left over. This
1399 * function does not allocate memory. It always nul-terminates (unless
1400 * @dest_size == 0 or there were no nul characters in the @dest_size
1401 * characters of dest to start with).
1403 * Caveat: this is supposedly a more secure alternative to strcat() or
1404 * strncat(), but for real security g_strconcat() is harder to mess up.
1406 * Returns: size of attempted result, which is MIN (dest_size, strlen
1407 * (original dest)) + strlen (src), so if retval >= dest_size,
1408 * truncation occurred.
1411 g_strlcat (gchar
*dest
,
1416 const gchar
*s
= src
;
1417 gsize bytes_left
= dest_size
;
1418 gsize dlength
; /* Logically, MIN (strlen (d), dest_size) */
1420 g_return_val_if_fail (dest
!= NULL
, 0);
1421 g_return_val_if_fail (src
!= NULL
, 0);
1423 /* Find the end of dst and adjust bytes left but don't go past end */
1424 while (*d
!= 0 && bytes_left
-- != 0)
1427 bytes_left
= dest_size
- dlength
;
1429 if (bytes_left
== 0)
1430 return dlength
+ strlen (s
);
1434 if (bytes_left
!= 1)
1443 return dlength
+ (s
- src
); /* count does not include NUL */
1445 #endif /* ! HAVE_STRLCPY */
1450 * @len: length of @str in bytes, or -1 if @str is nul-terminated
1452 * Converts all upper case ASCII letters to lower case ASCII letters.
1454 * Returns: a newly-allocated string, with all the upper case
1455 * characters in @str converted to lower case, with semantics that
1456 * exactly match g_ascii_tolower(). (Note that this is unlike the
1457 * old g_strdown(), which modified the string in place.)
1460 g_ascii_strdown (const gchar
*str
,
1465 g_return_val_if_fail (str
!= NULL
, NULL
);
1470 result
= g_strndup (str
, len
);
1471 for (s
= result
; *s
; s
++)
1472 *s
= g_ascii_tolower (*s
);
1480 * @len: length of @str in bytes, or -1 if @str is nul-terminated
1482 * Converts all lower case ASCII letters to upper case ASCII letters.
1484 * Returns: a newly allocated string, with all the lower case
1485 * characters in @str converted to upper case, with semantics that
1486 * exactly match g_ascii_toupper(). (Note that this is unlike the
1487 * old g_strup(), which modified the string in place.)
1490 g_ascii_strup (const gchar
*str
,
1495 g_return_val_if_fail (str
!= NULL
, NULL
);
1500 result
= g_strndup (str
, len
);
1501 for (s
= result
; *s
; s
++)
1502 *s
= g_ascii_toupper (*s
);
1511 * Determines if a string is pure ASCII. A string is pure ASCII if it
1512 * contains no bytes with the high bit set.
1514 * Returns: %TRUE if @str is ASCII
1519 g_str_is_ascii (const gchar
*str
)
1523 for (i
= 0; str
[i
]; i
++)
1532 * @string: the string to convert.
1534 * Converts a string to lower case.
1536 * Returns: the string
1538 * Deprecated:2.2: This function is totally broken for the reasons discussed
1539 * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
1543 g_strdown (gchar
*string
)
1547 g_return_val_if_fail (string
!= NULL
, NULL
);
1549 s
= (guchar
*) string
;
1558 return (gchar
*) string
;
1563 * @string: the string to convert
1565 * Converts a string to upper case.
1567 * Returns: the string
1569 * Deprecated:2.2: This function is totally broken for the reasons
1570 * discussed in the g_strncasecmp() docs - use g_ascii_strup()
1571 * or g_utf8_strup() instead.
1574 g_strup (gchar
*string
)
1578 g_return_val_if_fail (string
!= NULL
, NULL
);
1580 s
= (guchar
*) string
;
1589 return (gchar
*) string
;
1594 * @string: the string to reverse
1596 * Reverses all of the bytes in a string. For example,
1597 * `g_strreverse ("abcdef")` will result in "fedcba".
1599 * Note that g_strreverse() doesn't work on UTF-8 strings
1600 * containing multibyte characters. For that purpose, use
1601 * g_utf8_strreverse().
1603 * Returns: the same pointer passed in as @string
1606 g_strreverse (gchar
*string
)
1608 g_return_val_if_fail (string
!= NULL
, NULL
);
1615 t
= string
+ strlen (string
) - 1;
1636 * Convert a character to ASCII lower case.
1638 * Unlike the standard C library tolower() function, this only
1639 * recognizes standard ASCII letters and ignores the locale, returning
1640 * all non-ASCII characters unchanged, even if they are lower case
1641 * letters in a particular character set. Also unlike the standard
1642 * library function, this takes and returns a char, not an int, so
1643 * don't call it on %EOF but no need to worry about casting to #guchar
1644 * before passing a possibly non-ASCII character in.
1646 * Returns: the result of converting @c to lower case. If @c is
1647 * not an ASCII upper case letter, @c is returned unchanged.
1650 g_ascii_tolower (gchar c
)
1652 return g_ascii_isupper (c
) ? c
- 'A' + 'a' : c
;
1659 * Convert a character to ASCII upper case.
1661 * Unlike the standard C library toupper() function, this only
1662 * recognizes standard ASCII letters and ignores the locale, returning
1663 * all non-ASCII characters unchanged, even if they are upper 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 %EOF but no need to worry about casting to #guchar
1667 * before passing a possibly non-ASCII character in.
1669 * Returns: the result of converting @c to upper case. If @c is not
1670 * an ASCII lower case letter, @c is returned unchanged.
1673 g_ascii_toupper (gchar c
)
1675 return g_ascii_islower (c
) ? c
- 'a' + 'A' : c
;
1679 * g_ascii_digit_value:
1680 * @c: an ASCII character
1682 * Determines the numeric value of a character as a decimal digit.
1683 * Differs from g_unichar_digit_value() because it takes a char, so
1684 * there's no worry about sign extension if characters are signed.
1686 * Returns: If @c is a decimal digit (according to g_ascii_isdigit()),
1687 * its numeric value. Otherwise, -1.
1690 g_ascii_digit_value (gchar c
)
1692 if (g_ascii_isdigit (c
))
1698 * g_ascii_xdigit_value:
1699 * @c: an ASCII character.
1701 * Determines the numeric value of a character as a hexidecimal
1702 * digit. Differs from g_unichar_xdigit_value() because it takes
1703 * a char, so there's no worry about sign extension if characters
1706 * Returns: If @c is a hex digit (according to g_ascii_isxdigit()),
1707 * its numeric value. Otherwise, -1.
1710 g_ascii_xdigit_value (gchar c
)
1712 if (c
>= 'A' && c
<= 'F')
1713 return c
- 'A' + 10;
1714 if (c
>= 'a' && c
<= 'f')
1715 return c
- 'a' + 10;
1716 return g_ascii_digit_value (c
);
1720 * g_ascii_strcasecmp:
1721 * @s1: string to compare with @s2
1722 * @s2: string to compare with @s1
1724 * Compare two strings, ignoring the case of ASCII characters.
1726 * Unlike the BSD strcasecmp() function, this only recognizes standard
1727 * ASCII letters and ignores the locale, treating all non-ASCII
1728 * bytes as if they are not letters.
1730 * This function should be used only on strings that are known to be
1731 * in encodings where the bytes corresponding to ASCII letters always
1732 * represent themselves. This includes UTF-8 and the ISO-8859-*
1733 * charsets, but not for instance double-byte encodings like the
1734 * Windows Codepage 932, where the trailing bytes of double-byte
1735 * characters include all ASCII letters. If you compare two CP932
1736 * strings using this function, you will get false matches.
1738 * Both @s1 and @s2 must be non-%NULL.
1740 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1741 * or a positive value if @s1 > @s2.
1744 g_ascii_strcasecmp (const gchar
*s1
,
1749 g_return_val_if_fail (s1
!= NULL
, 0);
1750 g_return_val_if_fail (s2
!= NULL
, 0);
1754 c1
= (gint
)(guchar
) TOLOWER (*s1
);
1755 c2
= (gint
)(guchar
) TOLOWER (*s2
);
1761 return (((gint
)(guchar
) *s1
) - ((gint
)(guchar
) *s2
));
1765 * g_ascii_strncasecmp:
1766 * @s1: string to compare with @s2
1767 * @s2: string to compare with @s1
1768 * @n: number of characters to compare
1770 * Compare @s1 and @s2, ignoring the case of ASCII characters and any
1771 * characters after the first @n in each string.
1773 * Unlike the BSD strcasecmp() function, this only recognizes standard
1774 * ASCII letters and ignores the locale, treating all non-ASCII
1775 * characters as if they are not letters.
1777 * The same warning as in g_ascii_strcasecmp() applies: Use this
1778 * function only on strings known to be in encodings where bytes
1779 * corresponding to ASCII letters always represent themselves.
1781 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1782 * or a positive value if @s1 > @s2.
1785 g_ascii_strncasecmp (const gchar
*s1
,
1791 g_return_val_if_fail (s1
!= NULL
, 0);
1792 g_return_val_if_fail (s2
!= NULL
, 0);
1794 while (n
&& *s1
&& *s2
)
1797 c1
= (gint
)(guchar
) TOLOWER (*s1
);
1798 c2
= (gint
)(guchar
) TOLOWER (*s2
);
1805 return (((gint
) (guchar
) *s1
) - ((gint
) (guchar
) *s2
));
1813 * @s2: a string to compare with @s1
1815 * A case-insensitive string comparison, corresponding to the standard
1816 * strcasecmp() function on platforms which support it.
1818 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1819 * or a positive value if @s1 > @s2.
1821 * Deprecated:2.2: See g_strncasecmp() for a discussion of why this
1822 * function is deprecated and how to replace it.
1825 g_strcasecmp (const gchar
*s1
,
1828 #ifdef HAVE_STRCASECMP
1829 g_return_val_if_fail (s1
!= NULL
, 0);
1830 g_return_val_if_fail (s2
!= NULL
, 0);
1832 return strcasecmp (s1
, s2
);
1836 g_return_val_if_fail (s1
!= NULL
, 0);
1837 g_return_val_if_fail (s2
!= NULL
, 0);
1841 /* According to A. Cox, some platforms have islower's that
1842 * don't work right on non-uppercase
1844 c1
= isupper ((guchar
)*s1
) ? tolower ((guchar
)*s1
) : *s1
;
1845 c2
= isupper ((guchar
)*s2
) ? tolower ((guchar
)*s2
) : *s2
;
1851 return (((gint
)(guchar
) *s1
) - ((gint
)(guchar
) *s2
));
1858 * @s2: a string to compare with @s1
1859 * @n: the maximum number of characters to compare
1861 * A case-insensitive string comparison, corresponding to the standard
1862 * strncasecmp() function on platforms which support it. It is similar
1863 * to g_strcasecmp() except it only compares the first @n characters of
1866 * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1867 * or a positive value if @s1 > @s2.
1869 * Deprecated:2.2: The problem with g_strncasecmp() is that it does
1870 * the comparison by calling toupper()/tolower(). These functions
1871 * are locale-specific and operate on single bytes. However, it is
1872 * impossible to handle things correctly from an internationalization
1873 * standpoint by operating on bytes, since characters may be multibyte.
1874 * Thus g_strncasecmp() is broken if your string is guaranteed to be
1875 * ASCII, since it is locale-sensitive, and it's broken if your string
1876 * is localized, since it doesn't work on many encodings at all,
1877 * including UTF-8, EUC-JP, etc.
1879 * There are therefore two replacement techniques: g_ascii_strncasecmp(),
1880 * which only works on ASCII and is not locale-sensitive, and
1881 * g_utf8_casefold() followed by strcmp() on the resulting strings,
1882 * which is good for case-insensitive sorting of UTF-8.
1885 g_strncasecmp (const gchar
*s1
,
1889 #ifdef HAVE_STRNCASECMP
1890 return strncasecmp (s1
, s2
, n
);
1894 g_return_val_if_fail (s1
!= NULL
, 0);
1895 g_return_val_if_fail (s2
!= NULL
, 0);
1897 while (n
&& *s1
&& *s2
)
1900 /* According to A. Cox, some platforms have islower's that
1901 * don't work right on non-uppercase
1903 c1
= isupper ((guchar
)*s1
) ? tolower ((guchar
)*s1
) : *s1
;
1904 c2
= isupper ((guchar
)*s2
) ? tolower ((guchar
)*s2
) : *s2
;
1911 return (((gint
) (guchar
) *s1
) - ((gint
) (guchar
) *s2
));
1919 * @string: the string to convert
1920 * @delimiters: (allow-none): a string containing the current delimiters,
1921 * or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS
1922 * @new_delimiter: the new delimiter character
1924 * Converts any delimiter characters in @string to @new_delimiter.
1925 * Any characters in @string which are found in @delimiters are
1926 * changed to the @new_delimiter character. Modifies @string in place,
1927 * and returns @string itself, not a copy. The return value is to
1928 * allow nesting such as
1929 * |[<!-- language="C" -->
1930 * g_ascii_strup (g_strdelimit (str, "abc", '?'))
1936 g_strdelimit (gchar
*string
,
1937 const gchar
*delimiters
,
1942 g_return_val_if_fail (string
!= NULL
, NULL
);
1945 delimiters
= G_STR_DELIMITERS
;
1947 for (c
= string
; *c
; c
++)
1949 if (strchr (delimiters
, *c
))
1958 * @string: a nul-terminated array of bytes
1959 * @valid_chars: bytes permitted in @string
1960 * @substitutor: replacement character for disallowed bytes
1962 * For each character in @string, if the character is not in @valid_chars,
1963 * replaces the character with @substitutor. Modifies @string in place,
1964 * and return @string itself, not a copy. The return value is to allow
1966 * |[<!-- language="C" -->
1967 * g_ascii_strup (g_strcanon (str, "abc", '?'))
1973 g_strcanon (gchar
*string
,
1974 const gchar
*valid_chars
,
1979 g_return_val_if_fail (string
!= NULL
, NULL
);
1980 g_return_val_if_fail (valid_chars
!= NULL
, NULL
);
1982 for (c
= string
; *c
; c
++)
1984 if (!strchr (valid_chars
, *c
))
1993 * @source: a string to compress
1995 * Replaces all escaped characters with their one byte equivalent.
1997 * This function does the reverse conversion of g_strescape().
1999 * Returns: a newly-allocated copy of @source with all escaped
2000 * character compressed
2003 g_strcompress (const gchar
*source
)
2005 const gchar
*p
= source
, *octal
;
2009 g_return_val_if_fail (source
!= NULL
, NULL
);
2011 dest
= g_malloc (strlen (source
) + 1);
2022 g_warning ("g_strcompress: trailing \\");
2024 case '0': case '1': case '2': case '3': case '4':
2025 case '5': case '6': case '7':
2028 while ((p
< octal
+ 3) && (*p
>= '0') && (*p
<= '7'))
2030 *q
= (*q
* 8) + (*p
- '0');
2054 default: /* Also handles \" and \\ */
2071 * @source: a string to escape
2072 * @exceptions: a string of characters not to escape in @source
2074 * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
2075 * and '"' in the string @source by inserting a '\' before
2076 * them. Additionally all characters in the range 0x01-0x1F (everything
2077 * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
2078 * replaced with a '\' followed by their octal representation.
2079 * Characters supplied in @exceptions are not escaped.
2081 * g_strcompress() does the reverse conversion.
2083 * Returns: a newly-allocated copy of @source with certain
2084 * characters escaped. See above.
2087 g_strescape (const gchar
*source
,
2088 const gchar
*exceptions
)
2095 g_return_val_if_fail (source
!= NULL
, NULL
);
2097 p
= (guchar
*) source
;
2098 /* Each source byte needs maximally four destination chars (\777) */
2099 q
= dest
= g_malloc (strlen (source
) * 4 + 1);
2101 memset (excmap
, 0, 256);
2104 guchar
*e
= (guchar
*) exceptions
;
2154 if ((*p
< ' ') || (*p
>= 0177))
2157 *q
++ = '0' + (((*p
) >> 6) & 07);
2158 *q
++ = '0' + (((*p
) >> 3) & 07);
2159 *q
++ = '0' + ((*p
) & 07);
2174 * @string: a string to remove the leading whitespace from
2176 * Removes leading whitespace from a string, by moving the rest
2177 * of the characters forward.
2179 * This function doesn't allocate or reallocate any memory;
2180 * it modifies @string in place. Therefore, it cannot be used on
2181 * statically allocated strings.
2183 * The pointer to @string is returned to allow the nesting of functions.
2185 * Also see g_strchomp() and g_strstrip().
2190 g_strchug (gchar
*string
)
2194 g_return_val_if_fail (string
!= NULL
, NULL
);
2196 for (start
= (guchar
*) string
; *start
&& g_ascii_isspace (*start
); start
++)
2199 memmove (string
, start
, strlen ((gchar
*) start
) + 1);
2206 * @string: a string to remove the trailing whitespace from
2208 * Removes trailing whitespace from a string.
2210 * This function doesn't allocate or reallocate any memory;
2211 * it modifies @string in place. Therefore, it cannot be used
2212 * on statically allocated strings.
2214 * The pointer to @string is returned to allow the nesting of functions.
2216 * Also see g_strchug() and g_strstrip().
2221 g_strchomp (gchar
*string
)
2225 g_return_val_if_fail (string
!= NULL
, NULL
);
2227 len
= strlen (string
);
2230 if (g_ascii_isspace ((guchar
) string
[len
]))
2241 * @string: a string to split
2242 * @delimiter: a string which specifies the places at which to split
2243 * the string. The delimiter is not included in any of the resulting
2244 * strings, unless @max_tokens is reached.
2245 * @max_tokens: the maximum number of pieces to split @string into.
2246 * If this is less than 1, the string is split completely.
2248 * Splits a string into a maximum of @max_tokens pieces, using the given
2249 * @delimiter. If @max_tokens is reached, the remainder of @string is
2250 * appended to the last token.
2252 * As an example, the result of g_strsplit (":a:bc::d:", ":", -1) is a
2253 * %NULL-terminated vector containing the six strings "", "a", "bc", "", "d"
2256 * As a special case, the result of splitting the empty string "" is an empty
2257 * vector, not a vector containing a single string. The reason for this
2258 * special case is that being able to represent a empty vector is typically
2259 * more useful than consistent handling of empty elements. If you do need
2260 * to represent empty elements, you'll need to check for the empty string
2261 * before calling g_strsplit().
2263 * Returns: a newly-allocated %NULL-terminated array of strings. Use
2264 * g_strfreev() to free it.
2267 g_strsplit (const gchar
*string
,
2268 const gchar
*delimiter
,
2271 GSList
*string_list
= NULL
, *slist
;
2272 gchar
**str_array
, *s
;
2274 const gchar
*remainder
;
2276 g_return_val_if_fail (string
!= NULL
, NULL
);
2277 g_return_val_if_fail (delimiter
!= NULL
, NULL
);
2278 g_return_val_if_fail (delimiter
[0] != '\0', NULL
);
2281 max_tokens
= G_MAXINT
;
2284 s
= strstr (remainder
, delimiter
);
2287 gsize delimiter_len
= strlen (delimiter
);
2289 while (--max_tokens
&& s
)
2293 len
= s
- remainder
;
2294 string_list
= g_slist_prepend (string_list
,
2295 g_strndup (remainder
, len
));
2297 remainder
= s
+ delimiter_len
;
2298 s
= strstr (remainder
, delimiter
);
2304 string_list
= g_slist_prepend (string_list
, g_strdup (remainder
));
2307 str_array
= g_new (gchar
*, n
+ 1);
2309 str_array
[n
--] = NULL
;
2310 for (slist
= string_list
; slist
; slist
= slist
->next
)
2311 str_array
[n
--] = slist
->data
;
2313 g_slist_free (string_list
);
2320 * @string: The string to be tokenized
2321 * @delimiters: A nul-terminated string containing bytes that are used
2322 * to split the string.
2323 * @max_tokens: The maximum number of tokens to split @string into.
2324 * If this is less than 1, the string is split completely
2326 * Splits @string into a number of tokens not containing any of the characters
2327 * in @delimiter. A token is the (possibly empty) longest string that does not
2328 * contain any of the characters in @delimiters. If @max_tokens is reached, the
2329 * remainder is appended to the last token.
2331 * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
2332 * %NULL-terminated vector containing the three strings "abc", "def",
2335 * The result of g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
2336 * vector containing the four strings "", "def", "ghi", and "".
2338 * As a special case, the result of splitting the empty string "" is an empty
2339 * vector, not a vector containing a single string. The reason for this
2340 * special case is that being able to represent a empty vector is typically
2341 * more useful than consistent handling of empty elements. If you do need
2342 * to represent empty elements, you'll need to check for the empty string
2343 * before calling g_strsplit_set().
2345 * Note that this function works on bytes not characters, so it can't be used
2346 * to delimit UTF-8 strings for anything but ASCII characters.
2348 * Returns: a newly-allocated %NULL-terminated array of strings. Use
2349 * g_strfreev() to free it.
2354 g_strsplit_set (const gchar
*string
,
2355 const gchar
*delimiters
,
2358 gboolean delim_table
[256];
2359 GSList
*tokens
, *list
;
2362 const gchar
*current
;
2366 g_return_val_if_fail (string
!= NULL
, NULL
);
2367 g_return_val_if_fail (delimiters
!= NULL
, NULL
);
2370 max_tokens
= G_MAXINT
;
2372 if (*string
== '\0')
2374 result
= g_new (char *, 1);
2379 memset (delim_table
, FALSE
, sizeof (delim_table
));
2380 for (s
= delimiters
; *s
!= '\0'; ++s
)
2381 delim_table
[*(guchar
*)s
] = TRUE
;
2386 s
= current
= string
;
2389 if (delim_table
[*(guchar
*)s
] && n_tokens
+ 1 < max_tokens
)
2391 token
= g_strndup (current
, s
- current
);
2392 tokens
= g_slist_prepend (tokens
, token
);
2401 token
= g_strndup (current
, s
- current
);
2402 tokens
= g_slist_prepend (tokens
, token
);
2405 result
= g_new (gchar
*, n_tokens
+ 1);
2407 result
[n_tokens
] = NULL
;
2408 for (list
= tokens
; list
!= NULL
; list
= list
->next
)
2409 result
[--n_tokens
] = list
->data
;
2411 g_slist_free (tokens
);
2418 * @str_array: a %NULL-terminated array of strings to free
2420 * Frees a %NULL-terminated array of strings, as well as each
2421 * string it contains.
2423 * If @str_array is %NULL, this function simply returns.
2426 g_strfreev (gchar
**str_array
)
2432 for (i
= 0; str_array
[i
] != NULL
; i
++)
2433 g_free (str_array
[i
]);
2441 * @str_array: a %NULL-terminated array of strings
2443 * Copies %NULL-terminated array of strings. The copy is a deep copy;
2444 * the new array should be freed by first freeing each string, then
2445 * the array itself. g_strfreev() does this for you. If called
2446 * on a %NULL value, g_strdupv() simply returns %NULL.
2448 * Returns: a new %NULL-terminated array of strings.
2451 g_strdupv (gchar
**str_array
)
2459 while (str_array
[i
])
2462 retval
= g_new (gchar
*, i
+ 1);
2465 while (str_array
[i
])
2467 retval
[i
] = g_strdup (str_array
[i
]);
2480 * @separator: (allow-none): a string to insert between each of the
2482 * @str_array: a %NULL-terminated array of strings to join
2484 * Joins a number of strings together to form one long string, with the
2485 * optional @separator inserted between each of them. The returned string
2486 * should be freed with g_free().
2488 * Returns: a newly-allocated string containing all of the strings joined
2489 * together, with @separator between them
2492 g_strjoinv (const gchar
*separator
,
2498 g_return_val_if_fail (str_array
!= NULL
, NULL
);
2500 if (separator
== NULL
)
2507 gsize separator_len
;
2509 separator_len
= strlen (separator
);
2510 /* First part, getting length */
2511 len
= 1 + strlen (str_array
[0]);
2512 for (i
= 1; str_array
[i
] != NULL
; i
++)
2513 len
+= strlen (str_array
[i
]);
2514 len
+= separator_len
* (i
- 1);
2516 /* Second part, building string */
2517 string
= g_new (gchar
, len
);
2518 ptr
= g_stpcpy (string
, *str_array
);
2519 for (i
= 1; str_array
[i
] != NULL
; i
++)
2521 ptr
= g_stpcpy (ptr
, separator
);
2522 ptr
= g_stpcpy (ptr
, str_array
[i
]);
2526 string
= g_strdup ("");
2533 * @separator: (allow-none): a string to insert between each of the
2535 * @...: a %NULL-terminated list of strings to join
2537 * Joins a number of strings together to form one long string, with the
2538 * optional @separator inserted between each of them. The returned string
2539 * should be freed with g_free().
2541 * Returns: a newly-allocated string containing all of the strings joined
2542 * together, with @separator between them
2545 g_strjoin (const gchar
*separator
,
2551 gsize separator_len
;
2554 if (separator
== NULL
)
2557 separator_len
= strlen (separator
);
2559 va_start (args
, separator
);
2561 s
= va_arg (args
, gchar
*);
2565 /* First part, getting length */
2566 len
= 1 + strlen (s
);
2568 s
= va_arg (args
, gchar
*);
2571 len
+= separator_len
+ strlen (s
);
2572 s
= va_arg (args
, gchar
*);
2576 /* Second part, building string */
2577 string
= g_new (gchar
, len
);
2579 va_start (args
, separator
);
2581 s
= va_arg (args
, gchar
*);
2582 ptr
= g_stpcpy (string
, s
);
2584 s
= va_arg (args
, gchar
*);
2587 ptr
= g_stpcpy (ptr
, separator
);
2588 ptr
= g_stpcpy (ptr
, s
);
2589 s
= va_arg (args
, gchar
*);
2593 string
= g_strdup ("");
2603 * @haystack: a string
2604 * @haystack_len: the maximum length of @haystack. Note that -1 is
2605 * a valid length, if @haystack is nul-terminated, meaning it will
2606 * search through the whole string.
2607 * @needle: the string to search for
2609 * Searches the string @haystack for the first occurrence
2610 * of the string @needle, limiting the length of the search
2613 * Returns: a pointer to the found occurrence, or
2614 * %NULL if not found.
2617 g_strstr_len (const gchar
*haystack
,
2618 gssize haystack_len
,
2619 const gchar
*needle
)
2621 g_return_val_if_fail (haystack
!= NULL
, NULL
);
2622 g_return_val_if_fail (needle
!= NULL
, NULL
);
2624 if (haystack_len
< 0)
2625 return strstr (haystack
, needle
);
2628 const gchar
*p
= haystack
;
2629 gsize needle_len
= strlen (needle
);
2633 if (needle_len
== 0)
2634 return (gchar
*)haystack
;
2636 if (haystack_len
< needle_len
)
2639 end
= haystack
+ haystack_len
- needle_len
;
2641 while (p
<= end
&& *p
)
2643 for (i
= 0; i
< needle_len
; i
++)
2644 if (p
[i
] != needle
[i
])
2659 * @haystack: a nul-terminated string
2660 * @needle: the nul-terminated string to search for
2662 * Searches the string @haystack for the last occurrence
2663 * of the string @needle.
2665 * Returns: a pointer to the found occurrence, or
2666 * %NULL if not found.
2669 g_strrstr (const gchar
*haystack
,
2670 const gchar
*needle
)
2677 g_return_val_if_fail (haystack
!= NULL
, NULL
);
2678 g_return_val_if_fail (needle
!= NULL
, NULL
);
2680 needle_len
= strlen (needle
);
2681 haystack_len
= strlen (haystack
);
2683 if (needle_len
== 0)
2684 return (gchar
*)haystack
;
2686 if (haystack_len
< needle_len
)
2689 p
= haystack
+ haystack_len
- needle_len
;
2691 while (p
>= haystack
)
2693 for (i
= 0; i
< needle_len
; i
++)
2694 if (p
[i
] != needle
[i
])
2708 * @haystack: a nul-terminated string
2709 * @haystack_len: the maximum length of @haystack
2710 * @needle: the nul-terminated string to search for
2712 * Searches the string @haystack for the last occurrence
2713 * of the string @needle, limiting the length of the search
2716 * Returns: a pointer to the found occurrence, or
2717 * %NULL if not found.
2720 g_strrstr_len (const gchar
*haystack
,
2721 gssize haystack_len
,
2722 const gchar
*needle
)
2724 g_return_val_if_fail (haystack
!= NULL
, NULL
);
2725 g_return_val_if_fail (needle
!= NULL
, NULL
);
2727 if (haystack_len
< 0)
2728 return g_strrstr (haystack
, needle
);
2731 gsize needle_len
= strlen (needle
);
2732 const gchar
*haystack_max
= haystack
+ haystack_len
;
2733 const gchar
*p
= haystack
;
2736 while (p
< haystack_max
&& *p
)
2739 if (p
< haystack
+ needle_len
)
2744 while (p
>= haystack
)
2746 for (i
= 0; i
< needle_len
; i
++)
2747 if (p
[i
] != needle
[i
])
2763 * @str: a nul-terminated string
2764 * @suffix: the nul-terminated suffix to look for
2766 * Looks whether the string @str ends with @suffix.
2768 * Returns: %TRUE if @str end with @suffix, %FALSE otherwise.
2773 g_str_has_suffix (const gchar
*str
,
2774 const gchar
*suffix
)
2779 g_return_val_if_fail (str
!= NULL
, FALSE
);
2780 g_return_val_if_fail (suffix
!= NULL
, FALSE
);
2782 str_len
= strlen (str
);
2783 suffix_len
= strlen (suffix
);
2785 if (str_len
< suffix_len
)
2788 return strcmp (str
+ str_len
- suffix_len
, suffix
) == 0;
2793 * @str: a nul-terminated string
2794 * @prefix: the nul-terminated prefix to look for
2796 * Looks whether the string @str begins with @prefix.
2798 * Returns: %TRUE if @str begins with @prefix, %FALSE otherwise.
2803 g_str_has_prefix (const gchar
*str
,
2804 const gchar
*prefix
)
2806 g_return_val_if_fail (str
!= NULL
, FALSE
);
2807 g_return_val_if_fail (prefix
!= NULL
, FALSE
);
2809 return strncmp (str
, prefix
, strlen (prefix
)) == 0;
2814 * @str_array: a %NULL-terminated array of strings
2816 * Returns the length of the given %NULL-terminated
2817 * string array @str_array.
2819 * Returns: length of @str_array.
2824 g_strv_length (gchar
**str_array
)
2828 g_return_val_if_fail (str_array
!= NULL
, 0);
2830 while (str_array
[i
])
2837 index_add_folded (GPtrArray
*array
,
2843 normal
= g_utf8_normalize (start
, end
- start
, G_NORMALIZE_ALL_COMPOSE
);
2845 /* TODO: Invent time machine. Converse with Mustafa Ataturk... */
2846 if (strstr (normal
, "ı") || strstr (normal
, "İ"))
2851 tmp
= g_string_new (NULL
);
2857 i
= strstr (s
, "ı");
2858 I
= strstr (s
, "İ");
2871 g_string_append_len (tmp
, s
, e
- s
);
2872 g_string_append_c (tmp
, 'i');
2873 s
= g_utf8_next_char (e
);
2876 g_string_append (tmp
, s
);
2878 normal
= g_string_free (tmp
, FALSE
);
2881 g_ptr_array_add (array
, g_utf8_casefold (normal
, -1));
2886 split_words (const gchar
*value
)
2888 const gchar
*start
= NULL
;
2892 result
= g_ptr_array_new ();
2894 for (s
= value
; *s
; s
= g_utf8_next_char (s
))
2896 gunichar c
= g_utf8_get_char (s
);
2900 if (g_unichar_isalnum (c
) || g_unichar_ismark (c
))
2905 if (!g_unichar_isalnum (c
) && !g_unichar_ismark (c
))
2907 index_add_folded (result
, start
, s
);
2914 index_add_folded (result
, start
, s
);
2916 g_ptr_array_add (result
, NULL
);
2918 return (gchar
**) g_ptr_array_free (result
, FALSE
);
2922 * g_str_tokenize_and_fold:
2924 * @translit_locale: (allow-none): the language code (like 'de' or
2925 * 'en_GB') from which @string originates
2926 * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a
2927 * return location for ASCII alternates
2929 * Tokenises @string and performs folding on each token.
2931 * A token is a non-empty sequence of alphanumeric characters in the
2932 * source string, separated by non-alphanumeric characters. An
2933 * "alphanumeric" character for this purpose is one that matches
2934 * g_unichar_isalnum() or g_unichar_ismark().
2936 * Each token is then (Unicode) normalised and case-folded. If
2937 * @ascii_alternates is non-%NULL and some of the returned tokens
2938 * contain non-ASCII characters, ASCII alternatives will be generated.
2940 * The number of ASCII alternatives that are generated and the method
2941 * for doing so is unspecified, but @translit_locale (if specified) may
2942 * improve the transliteration if the language of the source string is
2945 * Returns: (transfer full) (array zero-terminated=1): the folded tokens
2950 g_str_tokenize_and_fold (const gchar
*string
,
2951 const gchar
*translit_locale
,
2952 gchar
***ascii_alternates
)
2956 g_return_val_if_fail (string
!= NULL
, NULL
);
2958 if (ascii_alternates
&& g_str_is_ascii (string
))
2960 *ascii_alternates
= g_new0 (gchar
*, 0 + 1);
2961 ascii_alternates
= NULL
;
2964 result
= split_words (string
);
2966 if (ascii_alternates
)
2970 n
= g_strv_length (result
);
2971 *ascii_alternates
= g_new (gchar
*, n
+ 1);
2974 for (i
= 0; i
< n
; i
++)
2976 if (!g_str_is_ascii (result
[i
]))
2982 composed
= g_utf8_normalize (result
[i
], -1, G_NORMALIZE_ALL_COMPOSE
);
2984 ascii
= g_str_to_ascii (composed
, translit_locale
);
2986 /* Only accept strings that are now entirely alnums */
2987 for (k
= 0; ascii
[k
]; k
++)
2988 if (!g_ascii_isalnum (ascii
[k
]))
2991 if (ascii
[k
] == '\0')
2992 /* Made it to the end... */
2993 (*ascii_alternates
)[j
++] = ascii
;
3001 (*ascii_alternates
)[j
] = NULL
;
3008 * g_str_match_string:
3009 * @search_term: the search term from the user
3010 * @potential_hit: the text that may be a hit
3011 * @accept_alternates: %TRUE to accept ASCII alternates
3013 * Checks if a search conducted for @search_term should match
3016 * This function calls g_str_tokenize_and_fold() on both
3017 * @search_term and @potential_hit. ASCII alternates are never taken
3018 * for @search_term but will be taken for @potential_hit according to
3019 * the value of @accept_alternates.
3021 * A hit occurs when each folded token in @search_term is a prefix of a
3022 * folded token from @potential_hit.
3024 * Depending on how you're performing the search, it will typically be
3025 * faster to call g_str_tokenize_and_fold() on each string in
3026 * your corpus and build an index on the returned folded tokens, then
3027 * call g_str_tokenize_and_fold() on the search term and
3028 * perform lookups into that index.
3030 * As some examples, searching for "fred" would match the potential hit
3031 * "Smith, Fred" and also "Frédéric". Searching for "Fréd" would match
3032 * "Frédéric" but not "Frederic" (due to the one-directional nature of
3033 * accent matching). Searching "fo" would match "Foo" and "Bar Foo
3034 * Baz", but not "SFO" (because no word as "fo" as a prefix).
3036 * Returns: %TRUE if @potential_hit is a hit
3041 g_str_match_string (const gchar
*search_term
,
3042 const gchar
*potential_hit
,
3043 gboolean accept_alternates
)
3045 gchar
**alternates
= NULL
;
3046 gchar
**term_tokens
;
3051 g_return_val_if_fail (search_term
!= NULL
, FALSE
);
3052 g_return_val_if_fail (potential_hit
!= NULL
, FALSE
);
3054 term_tokens
= g_str_tokenize_and_fold (search_term
, NULL
, NULL
);
3055 hit_tokens
= g_str_tokenize_and_fold (potential_hit
, NULL
, accept_alternates
? &alternates
: NULL
);
3059 for (i
= 0; term_tokens
[i
]; i
++)
3061 for (j
= 0; hit_tokens
[j
]; j
++)
3062 if (g_str_has_prefix (hit_tokens
[j
], term_tokens
[i
]))
3065 if (accept_alternates
)
3066 for (j
= 0; alternates
[j
]; j
++)
3067 if (g_str_has_prefix (alternates
[j
], term_tokens
[i
]))
3077 g_strfreev (term_tokens
);
3078 g_strfreev (hit_tokens
);
3079 g_strfreev (alternates
);
3086 * @strv: a %NULL-terminated array of strings
3089 * Checks if @strv contains @str. @strv must not be %NULL.
3091 * Returns: %TRUE if @str is an element of @strv, according to g_str_equal().
3096 g_strv_contains (const gchar
* const *strv
,
3099 g_return_val_if_fail (strv
!= NULL
, FALSE
);
3100 g_return_val_if_fail (str
!= NULL
, FALSE
);
3102 for (; *strv
!= NULL
; strv
++)
3104 if (g_str_equal (str
, *strv
))