glib/gstrfuncs.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   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.
   8  *
   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.
  13  *
  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/>.
  16  */
  17
  18 /*
  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/.
  23  */
  24
  25 /*
  26  * MT safe
  27  */
  28
  29 #include "config.h"
  30
  31 #include <stdarg.h>
  32 #include <stdio.h>
  33 #include <stdlib.h>
  34 #include <locale.h>
  35 #include <string.h>
  36 #include <locale.h>
  37 #include <errno.h>
  38 #include <ctype.h>              /* For tolower() */
  39
  40 #ifdef HAVE_XLOCALE_H
  41 /* Needed on BSD/OS X for e.g. strtod_l */
  42 #include <xlocale.h>
  43 #endif
  44
  45 #ifdef G_OS_WIN32
  46 #include <windows.h>
  47 #endif
  48
  49 /* do not include <unistd.h> here, it may interfere with g_strsignal() */
  50
  51 #include "gstrfuncs.h"
  52
  53 #include "gprintf.h"
  54 #include "gprintfint.h"
  55 #include "glibintl.h"
  56
  57
  58 /**
  59  * SECTION:string_utils
  60  * @title: String Utility Functions
  61  * @short_description: various string-related functions
  62  *
  63  * This section describes a number of utility functions for creating,
  64  * duplicating, and manipulating strings.
  65  *
  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
  71  * printf() functions.
  72  *
  73  * ## String precision pitfalls # {#string-precision}
  74  *
  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())
  86  * into account.
  87  */
  88
  89 /**
  90  * g_ascii_isalnum:
  91  * @c: any character
  92  *
  93  * Determines whether a character is alphanumeric.
  94  *
  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.
 101  *
 102  * Returns: %TRUE if @c is an ASCII alphanumeric character
 103  */
 104
 105 /**
 106  * g_ascii_isalpha:
 107  * @c: any character
 108  *
 109  * Determines whether a character is alphabetic (i.e. a letter).
 110  *
 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.
 117  *
 118  * Returns: %TRUE if @c is an ASCII alphabetic character
 119  */
 120
 121 /**
 122  * g_ascii_iscntrl:
 123  * @c: any character
 124  *
 125  * Determines whether a character is a control character.
 126  *
 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.
 133  *
 134  * Returns: %TRUE if @c is an ASCII control character.
 135  */
 136
 137 /**
 138  * g_ascii_isdigit:
 139  * @c: any character
 140  *
 141  * Determines whether a character is digit (0-9).
 142  *
 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.
 146  *
 147  * Returns: %TRUE if @c is an ASCII digit.
 148  */
 149
 150 /**
 151  * g_ascii_isgraph:
 152  * @c: any character
 153  *
 154  * Determines whether a character is a printing character and not a space.
 155  *
 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.
 162  *
 163  * Returns: %TRUE if @c is an ASCII printing character other than space.
 164  */
 165
 166 /**
 167  * g_ascii_islower:
 168  * @c: any character
 169  *
 170  * Determines whether a character is an ASCII lower case letter.
 171  *
 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.
 178  *
 179  * Returns: %TRUE if @c is an ASCII lower case letter
 180  */
 181
 182 /**
 183  * g_ascii_isprint:
 184  * @c: any character
 185  *
 186  * Determines whether a character is a printing character.
 187  *
 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.
 194  *
 195  * Returns: %TRUE if @c is an ASCII printing character.
 196  */
 197
 198 /**
 199  * g_ascii_ispunct:
 200  * @c: any character
 201  *
 202  * Determines whether a character is a punctuation character.
 203  *
 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.
 210  *
 211  * Returns: %TRUE if @c is an ASCII punctuation character.
 212  */
 213
 214 /**
 215  * g_ascii_isspace:
 216  * @c: any character
 217  *
 218  * Determines whether a character is a white-space character.
 219  *
 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.
 226  *
 227  * Returns: %TRUE if @c is an ASCII white-space character
 228  */
 229
 230 /**
 231  * g_ascii_isupper:
 232  * @c: any character
 233  *
 234  * Determines whether a character is an ASCII upper case letter.
 235  *
 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.
 242  *
 243  * Returns: %TRUE if @c is an ASCII upper case letter
 244  */
 245
 246 /**
 247  * g_ascii_isxdigit:
 248  * @c: any character
 249  *
 250  * Determines whether a character is a hexadecimal-digit character.
 251  *
 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.
 255  *
 256  * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
 257  */
 258
 259 /**
 260  * G_ASCII_DTOSTR_BUF_SIZE:
 261  *
 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.
 265  *
 266  * The typical usage would be something like:
 267  * |[<!-- language="C" -->
 268  *   char buf[G_ASCII_DTOSTR_BUF_SIZE];
 269  *
 270  *   fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
 271  * ]|
 272  */
 273
 274 /**
 275  * g_strstrip:
 276  * @string: a string to remove the leading and trailing whitespace from
 277  *
 278  * Removes leading and trailing whitespace from a string.
 279  * See g_strchomp() and g_strchug().
 280  *
 281  * Returns: @string
 282  */
 283
 284 /**
 285  * G_STR_DELIMITERS:
 286  *
 287  * The standard delimiters, used in g_strdelimit().
 288  */
 289
 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 */
 308 };
 309
 310 const guint16 * const g_ascii_table = ascii_table_data;
 311
 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
 318 #endif
 319
 320 #ifdef USE_XLOCALE
 321 static locale_t
 322 get_C_locale (void)
 323 {
 324   static gsize initialized = FALSE;
 325   static locale_t C_locale = NULL;
 326
 327   if (g_once_init_enter (&initialized))
 328     {
 329       C_locale = newlocale (LC_ALL_MASK, "C", NULL);
 330       g_once_init_leave (&initialized, TRUE);
 331     }
 332
 333   return C_locale;
 334 }
 335 #endif
 336
 337 /**
 338  * g_strdup:
 339  * @str: the string to duplicate
 340  *
 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.
 344  *
 345  * Returns: a newly-allocated copy of @str
 346  */
 347 gchar*
 348 g_strdup (const gchar *str)
 349 {
 350   gchar *new_str;
 351   gsize length;
 352
 353   if (str)
 354     {
 355       length = strlen (str) + 1;
 356       new_str = g_new (char, length);
 357       memcpy (new_str, str, length);
 358     }
 359   else
 360     new_str = NULL;
 361
 362   return new_str;
 363 }
 364
 365 /**
 366  * g_memdup:
 367  * @mem: the memory to copy.
 368  * @byte_size: the number of bytes to copy.
 369  *
 370  * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
 371  * from @mem. If @mem is %NULL it returns %NULL.
 372  *
 373  * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
 374  *  is %NULL.
 375  */
 376 gpointer
 377 g_memdup (gconstpointer mem,
 378           guint         byte_size)
 379 {
 380   gpointer new_mem;
 381
 382   if (mem)
 383     {
 384       new_mem = g_malloc (byte_size);
 385       memcpy (new_mem, mem, byte_size);
 386     }
 387   else
 388     new_mem = NULL;
 389
 390   return new_mem;
 391 }
 392
 393 /**
 394  * g_strndup:
 395  * @str: the string to duplicate
 396  * @n: the maximum number of bytes to copy from @str
 397  *
 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
 402  * needed.
 403  *
 404  * To copy a number of characters from a UTF-8 encoded string,
 405  * use g_utf8_strncpy() instead.
 406  *
 407  * Returns: a newly-allocated buffer containing the first @n bytes
 408  *     of @str, nul-terminated
 409  */
 410 gchar*
 411 g_strndup (const gchar *str,
 412            gsize        n)
 413 {
 414   gchar *new_str;
 415
 416   if (str)
 417     {
 418       new_str = g_new (gchar, n + 1);
 419       strncpy (new_str, str, n);
 420       new_str[n] = '\0';
 421     }
 422   else
 423     new_str = NULL;
 424
 425   return new_str;
 426 }
 427
 428 /**
 429  * g_strnfill:
 430  * @length: the length of the new string
 431  * @fill_char: the byte to fill the string with
 432  *
 433  * Creates a new string @length bytes long filled with @fill_char.
 434  * The returned string should be freed when no longer needed.
 435  *
 436  * Returns: a newly-allocated string filled the @fill_char
 437  */
 438 gchar*
 439 g_strnfill (gsize length,
 440             gchar fill_char)
 441 {
 442   gchar *str;
 443
 444   str = g_new (gchar, length + 1);
 445   memset (str, (guchar)fill_char, length);
 446   str[length] = '\0';
 447
 448   return str;
 449 }
 450
 451 /**
 452  * g_stpcpy:
 453  * @dest: destination buffer.
 454  * @src: source string.
 455  *
 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.
 460  *
 461  * Returns: a pointer to trailing nul byte.
 462  **/
 463 gchar *
 464 g_stpcpy (gchar       *dest,
 465           const gchar *src)
 466 {
 467 #ifdef HAVE_STPCPY
 468   g_return_val_if_fail (dest != NULL, NULL);
 469   g_return_val_if_fail (src != NULL, NULL);
 470   return stpcpy (dest, src);
 471 #else
 472   register gchar *d = dest;
 473   register const gchar *s = src;
 474
 475   g_return_val_if_fail (dest != NULL, NULL);
 476   g_return_val_if_fail (src != NULL, NULL);
 477   do
 478     *d++ = *s;
 479   while (*s++ != '\0');
 480
 481   return d - 1;
 482 #endif
 483 }
 484
 485 /**
 486  * g_strdup_vprintf:
 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
 490  *
 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
 494  * no longer needed.
 495  *
 496  * See also g_vasprintf(), which offers the same functionality, but
 497  * additionally returns the length of the allocated string.
 498  *
 499  * Returns: a newly-allocated string holding the result
 500  */
 501 gchar*
 502 g_strdup_vprintf (const gchar *format,
 503                   va_list      args)
 504 {
 505   gchar *string = NULL;
 506
 507   g_vasprintf (&string, format, args);
 508
 509   return string;
 510 }
 511
 512 /**
 513  * g_strdup_printf:
 514  * @format: a standard printf() format string, but notice
 515  *     [string precision pitfalls][string-precision]
 516  * @...: the parameters to insert into the format string
 517  *
 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
 521  * longer needed.
 522  *
 523  * Returns: a newly-allocated string holding the result
 524  */
 525 gchar*
 526 g_strdup_printf (const gchar *format,
 527                  ...)
 528 {
 529   gchar *buffer;
 530   va_list args;
 531
 532   va_start (args, format);
 533   buffer = g_strdup_vprintf (format, args);
 534   va_end (args);
 535
 536   return buffer;
 537 }
 538
 539 /**
 540  * g_strconcat:
 541  * @string1: the first string to add, which must not be %NULL
 542  * @...: a %NULL-terminated list of strings to append to the string
 543  *
 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.
 546  *
 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.
 549  *
 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.
 553  *
 554  * Returns: a newly-allocated string containing all the string arguments
 555  */
 556 gchar*
 557 g_strconcat (const gchar *string1, ...)
 558 {
 559   gsize   l;
 560   va_list args;
 561   gchar   *s;
 562   gchar   *concat;
 563   gchar   *ptr;
 564
 565   if (!string1)
 566     return NULL;
 567
 568   l = 1 + strlen (string1);
 569   va_start (args, string1);
 570   s = va_arg (args, gchar*);
 571   while (s)
 572     {
 573       l += strlen (s);
 574       s = va_arg (args, gchar*);
 575     }
 576   va_end (args);
 577
 578   concat = g_new (gchar, l);
 579   ptr = concat;
 580
 581   ptr = g_stpcpy (ptr, string1);
 582   va_start (args, string1);
 583   s = va_arg (args, gchar*);
 584   while (s)
 585     {
 586       ptr = g_stpcpy (ptr, s);
 587       s = va_arg (args, gchar*);
 588     }
 589   va_end (args);
 590
 591   return concat;
 592 }
 593
 594 /**
 595  * g_strtod:
 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.
 599  *
 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.
 604  *
 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.
 611  *
 612  * Returns: the #gdouble value.
 613  **/
 614 gdouble
 615 g_strtod (const gchar *nptr,
 616           gchar      **endptr)
 617 {
 618   gchar *fail_pos_1;
 619   gchar *fail_pos_2;
 620   gdouble val_1;
 621   gdouble val_2 = 0;
 622
 623   g_return_val_if_fail (nptr != NULL, 0);
 624
 625   fail_pos_1 = NULL;
 626   fail_pos_2 = NULL;
 627
 628   val_1 = strtod (nptr, &fail_pos_1);
 629
 630   if (fail_pos_1 && fail_pos_1[0] != 0)
 631     val_2 = g_ascii_strtod (nptr, &fail_pos_2);
 632
 633   if (!fail_pos_1 || fail_pos_1[0] == 0 || fail_pos_1 >= fail_pos_2)
 634     {
 635       if (endptr)
 636         *endptr = fail_pos_1;
 637       return val_1;
 638     }
 639   else
 640     {
 641       if (endptr)
 642         *endptr = fail_pos_2;
 643       return val_2;
 644     }
 645 }
 646
 647 /**
 648  * g_ascii_strtod:
 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.
 652  *
 653  * Converts a string to a #gdouble value.
 654  *
 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.
 660  *
 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.
 665  *
 666  * To convert from a #gdouble to a string in a locale-insensitive
 667  * way, use g_ascii_dtostr().
 668  *
 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.
 673  *
 674  * This function resets %errno before calling strtod() so that
 675  * you can reliably detect overflow and underflow.
 676  *
 677  * Returns: the #gdouble value.
 678  */
 679 gdouble
 680 g_ascii_strtod (const gchar *nptr,
 681                 gchar      **endptr)
 682 {
 683 #ifdef USE_XLOCALE
 684
 685   g_return_val_if_fail (nptr != NULL, 0);
 686
 687   errno = 0;
 688
 689   return strtod_l (nptr, endptr, get_C_locale ());
 690
 691 #else
 692
 693   gchar *fail_pos;
 694   gdouble val;
 695 #ifndef __BIONIC__
 696   struct lconv *locale_data;
 697 #endif
 698   const char *decimal_point;
 699   int decimal_point_len;
 700   const char *p, *decimal_point_pos;
 701   const char *end = NULL; /* Silence gcc */
 702   int strtod_errno;
 703
 704   g_return_val_if_fail (nptr != NULL, 0);
 705
 706   fail_pos = NULL;
 707
 708 #ifndef __BIONIC__
 709   locale_data = localeconv ();
 710   decimal_point = locale_data->decimal_point;
 711   decimal_point_len = strlen (decimal_point);
 712 #else
 713   decimal_point = ".";
 714   decimal_point_len = 1;
 715 #endif
 716
 717   g_assert (decimal_point_len != 0);
 718
 719   decimal_point_pos = NULL;
 720   end = NULL;
 721
 722   if (decimal_point[0] != '.' ||
 723       decimal_point[1] != 0)
 724     {
 725       p = nptr;
 726       /* Skip leading space */
 727       while (g_ascii_isspace (*p))
 728         p++;
 729
 730       /* Skip leading optional sign */
 731       if (*p == '+' || *p == '-')
 732         p++;
 733
 734       if (p[0] == '0' &&
 735           (p[1] == 'x' || p[1] == 'X'))
 736         {
 737           p += 2;
 738           /* HEX - find the (optional) decimal point */
 739
 740           while (g_ascii_isxdigit (*p))
 741             p++;
 742
 743           if (*p == '.')
 744             decimal_point_pos = p++;
 745
 746           while (g_ascii_isxdigit (*p))
 747             p++;
 748
 749           if (*p == 'p' || *p == 'P')
 750             p++;
 751           if (*p == '+' || *p == '-')
 752             p++;
 753           while (g_ascii_isdigit (*p))
 754             p++;
 755
 756           end = p;
 757         }
 758       else if (g_ascii_isdigit (*p) || *p == '.')
 759         {
 760           while (g_ascii_isdigit (*p))
 761             p++;
 762
 763           if (*p == '.')
 764             decimal_point_pos = p++;
 765
 766           while (g_ascii_isdigit (*p))
 767             p++;
 768
 769           if (*p == 'e' || *p == 'E')
 770             p++;
 771           if (*p == '+' || *p == '-')
 772             p++;
 773           while (g_ascii_isdigit (*p))
 774             p++;
 775
 776           end = p;
 777         }
 778       /* For the other cases, we need not convert the decimal point */
 779     }
 780
 781   if (decimal_point_pos)
 782     {
 783       char *copy, *c;
 784
 785       /* We need to convert the '.' to the locale specific decimal point */
 786       copy = g_malloc (end - nptr + 1 + decimal_point_len);
 787
 788       c = copy;
 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);
 795       *c = 0;
 796
 797       errno = 0;
 798       val = strtod (copy, &fail_pos);
 799       strtod_errno = errno;
 800
 801       if (fail_pos)
 802         {
 803           if (fail_pos - copy > decimal_point_pos - nptr)
 804             fail_pos = (char *)nptr + (fail_pos - copy) - (decimal_point_len - 1);
 805           else
 806             fail_pos = (char *)nptr + (fail_pos - copy);
 807         }
 808
 809       g_free (copy);
 810
 811     }
 812   else if (end)
 813     {
 814       char *copy;
 815
 816       copy = g_malloc (end - (char *)nptr + 1);
 817       memcpy (copy, nptr, end - nptr);
 818       *(copy + (end - (char *)nptr)) = 0;
 819
 820       errno = 0;
 821       val = strtod (copy, &fail_pos);
 822       strtod_errno = errno;
 823
 824       if (fail_pos)
 825         {
 826           fail_pos = (char *)nptr + (fail_pos - copy);
 827         }
 828
 829       g_free (copy);
 830     }
 831   else
 832     {
 833       errno = 0;
 834       val = strtod (nptr, &fail_pos);
 835       strtod_errno = errno;
 836     }
 837
 838   if (endptr)
 839     *endptr = fail_pos;
 840
 841   errno = strtod_errno;
 842
 843   return val;
 844 #endif
 845 }
 846
 847
 848 /**
 849  * g_ascii_dtostr:
 850  * @buffer: A buffer to place the resulting string in
 851  * @buf_len: The length of the buffer.
 852  * @d: The #gdouble to convert
 853  *
 854  * Converts a #gdouble to a string, using the '.' as
 855  * decimal point.
 856  *
 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.
 862  *
 863  * Returns: The pointer to the buffer with the converted string.
 864  **/
 865 gchar *
 866 g_ascii_dtostr (gchar       *buffer,
 867                 gint         buf_len,
 868                 gdouble      d)
 869 {
 870   return g_ascii_formatd (buffer, buf_len, "%.17g", d);
 871 }
 872
 873 #pragma GCC diagnostic push
 874 #pragma GCC diagnostic ignored "-Wformat-nonliteral"
 875
 876 /**
 877  * g_ascii_formatd:
 878  * @buffer: A buffer to place the resulting string in
 879  * @buf_len: The length of the buffer.
 880  * @format: The printf()-style format to use for the
 881  *          code to use for converting.
 882  * @d: The #gdouble to convert
 883  *
 884  * Converts a #gdouble to a string, using the '.' as
 885  * decimal point. To format the number you pass in
 886  * a printf()-style format string. Allowed conversion
 887  * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
 888  *
 889  * If you just want to want to serialize the value into a
 890  * string, use g_ascii_dtostr().
 891  *
 892  * Returns: The pointer to the buffer with the converted string.
 893  */
 894 gchar *
 895 g_ascii_formatd (gchar       *buffer,
 896                  gint         buf_len,
 897                  const gchar *format,
 898                  gdouble      d)
 899 {
 900 #ifdef USE_XLOCALE
 901   locale_t old_locale;
 902
 903   old_locale = uselocale (get_C_locale ());
 904    _g_snprintf (buffer, buf_len, format, d);
 905   uselocale (old_locale);
 906
 907   return buffer;
 908 #else
 909 #ifndef __BIONIC__
 910   struct lconv *locale_data;
 911 #endif
 912   const char *decimal_point;
 913   int decimal_point_len;
 914   gchar *p;
 915   int rest_len;
 916   gchar format_char;
 917
 918   g_return_val_if_fail (buffer != NULL, NULL);
 919   g_return_val_if_fail (format[0] == '%', NULL);
 920   g_return_val_if_fail (strpbrk (format + 1, "'l%") == NULL, NULL);
 921
 922   format_char = format[strlen (format) - 1];
 923
 924   g_return_val_if_fail (format_char == 'e' || format_char == 'E' ||
 925                         format_char == 'f' || format_char == 'F' ||
 926                         format_char == 'g' || format_char == 'G',
 927                         NULL);
 928
 929   if (format[0] != '%')
 930     return NULL;
 931
 932   if (strpbrk (format + 1, "'l%"))
 933     return NULL;
 934
 935   if (!(format_char == 'e' || format_char == 'E' ||
 936         format_char == 'f' || format_char == 'F' ||
 937         format_char == 'g' || format_char == 'G'))
 938     return NULL;
 939
 940   _g_snprintf (buffer, buf_len, format, d);
 941
 942 #ifndef __BIONIC__
 943   locale_data = localeconv ();
 944   decimal_point = locale_data->decimal_point;
 945   decimal_point_len = strlen (decimal_point);
 946 #else
 947   decimal_point = ".";
 948   decimal_point_len = 1;
 949 #endif
 950
 951   g_assert (decimal_point_len != 0);
 952
 953   if (decimal_point[0] != '.' ||
 954       decimal_point[1] != 0)
 955     {
 956       p = buffer;
 957
 958       while (g_ascii_isspace (*p))
 959         p++;
 960
 961       if (*p == '+' || *p == '-')
 962         p++;
 963
 964       while (isdigit ((guchar)*p))
 965         p++;
 966
 967       if (strncmp (p, decimal_point, decimal_point_len) == 0)
 968         {
 969           *p = '.';
 970           p++;
 971           if (decimal_point_len > 1)
 972             {
 973               rest_len = strlen (p + (decimal_point_len-1));
 974               memmove (p, p + (decimal_point_len-1), rest_len);
 975               p[rest_len] = 0;
 976             }
 977         }
 978     }
 979
 980   return buffer;
 981 #endif
 982 }
 983 #pragma GCC diagnostic pop
 984
 985 #define ISSPACE(c)              ((c) == ' ' || (c) == '\f' || (c) == '\n' || \
 986                                  (c) == '\r' || (c) == '\t' || (c) == '\v')
 987 #define ISUPPER(c)              ((c) >= 'A' && (c) <= 'Z')
 988 #define ISLOWER(c)              ((c) >= 'a' && (c) <= 'z')
 989 #define ISALPHA(c)              (ISUPPER (c) || ISLOWER (c))
 990 #define TOUPPER(c)              (ISLOWER (c) ? (c) - 'a' + 'A' : (c))
 991 #define TOLOWER(c)              (ISUPPER (c) ? (c) - 'A' + 'a' : (c))
 992
 993 #ifndef USE_XLOCALE
 994
 995 static guint64
 996 g_parse_long_long (const gchar  *nptr,
 997                    const gchar **endptr,
 998                    guint         base,
 999                    gboolean     *negative)
1000 {
1001   /* this code is based on on the strtol(3) code from GNU libc released under
1002    * the GNU Lesser General Public License.
1003    *
1004    * Copyright (C) 1991,92,94,95,96,97,98,99,2000,01,02
1005    *        Free Software Foundation, Inc.
1006    */
1007   gboolean overflow;
1008   guint64 cutoff;
1009   guint64 cutlim;
1010   guint64 ui64;
1011   const gchar *s, *save;
1012   guchar c;
1013
1014   g_return_val_if_fail (nptr != NULL, 0);
1015
1016   *negative = FALSE;
1017   if (base == 1 || base > 36)
1018     {
1019       errno = EINVAL;
1020       if (endptr)
1021         *endptr = nptr;
1022       return 0;
1023     }
1024
1025   save = s = nptr;
1026
1027   /* Skip white space.  */
1028   while (ISSPACE (*s))
1029     ++s;
1030
1031   if (G_UNLIKELY (!*s))
1032     goto noconv;
1033
1034   /* Check for a sign.  */
1035   if (*s == '-')
1036     {
1037       *negative = TRUE;
1038       ++s;
1039     }
1040   else if (*s == '+')
1041     ++s;
1042
1043   /* Recognize number prefix and if BASE is zero, figure it out ourselves.  */
1044   if (*s == '0')
1045     {
1046       if ((base == 0 || base == 16) && TOUPPER (s[1]) == 'X')
1047         {
1048           s += 2;
1049           base = 16;
1050         }
1051       else if (base == 0)
1052         base = 8;
1053     }
1054   else if (base == 0)
1055     base = 10;
1056
1057   /* Save the pointer so we can check later if anything happened.  */
1058   save = s;
1059   cutoff = G_MAXUINT64 / base;
1060   cutlim = G_MAXUINT64 % base;
1061
1062   overflow = FALSE;
1063   ui64 = 0;
1064   c = *s;
1065   for (; c; c = *++s)
1066     {
1067       if (c >= '0' && c <= '9')
1068         c -= '0';
1069       else if (ISALPHA (c))
1070         c = TOUPPER (c) - 'A' + 10;
1071       else
1072         break;
1073       if (c >= base)
1074         break;
1075       /* Check for overflow.  */
1076       if (ui64 > cutoff || (ui64 == cutoff && c > cutlim))
1077         overflow = TRUE;
1078       else
1079         {
1080           ui64 *= base;
1081           ui64 += c;
1082         }
1083     }
1084
1085   /* Check if anything actually happened.  */
1086   if (s == save)
1087     goto noconv;
1088
1089   /* Store in ENDPTR the address of one character
1090      past the last character we converted.  */
1091   if (endptr)
1092     *endptr = s;
1093
1094   if (G_UNLIKELY (overflow))
1095     {
1096       errno = ERANGE;
1097       return G_MAXUINT64;
1098     }
1099
1100   return ui64;
1101
1102  noconv:
1103   /* We must handle a special case here: the base is 0 or 16 and the
1104      first two characters are '0' and 'x', but the rest are no
1105      hexadecimal digits.  This is no error case.  We return 0 and
1106      ENDPTR points to the `x`.  */
1107   if (endptr)
1108     {
1109       if (save - nptr >= 2 && TOUPPER (save[-1]) == 'X'
1110           && save[-2] == '0')
1111         *endptr = &save[-1];
1112       else
1113         /*  There was no number to convert.  */
1114         *endptr = nptr;
1115     }
1116   return 0;
1117 }
1118 #endif /* !USE_XLOCALE */
1119
1120 /**
1121  * g_ascii_strtoull:
1122  * @nptr:    the string to convert to a numeric value.
1123  * @endptr:  if non-%NULL, it returns the character after
1124  *           the last character used in the conversion.
1125  * @base:    to be used for the conversion, 2..36 or 0
1126  *
1127  * Converts a string to a #guint64 value.
1128  * This function behaves like the standard strtoull() function
1129  * does in the C locale. It does this without actually
1130  * changing the current locale, since that would not be
1131  * thread-safe.
1132  *
1133  * This function is typically used when reading configuration
1134  * files or other non-user input that should be locale independent.
1135  * To handle input from the user you should normally use the
1136  * locale-sensitive system strtoull() function.
1137  *
1138  * If the correct value would cause overflow, %G_MAXUINT64
1139  * is returned, and `ERANGE` is stored in `errno`.
1140  * If the base is outside the valid range, zero is returned, and
1141  * `EINVAL` is stored in `errno`.
1142  * If the string conversion fails, zero is returned, and @endptr returns
1143  * @nptr (if @endptr is non-%NULL).
1144  *
1145  * Returns: the #guint64 value or zero on error.
1146  *
1147  * Since: 2.2
1148  */
1149 guint64
1150 g_ascii_strtoull (const gchar *nptr,
1151                   gchar      **endptr,
1152                   guint        base)
1153 {
1154 #ifdef USE_XLOCALE
1155   return strtoull_l (nptr, endptr, base, get_C_locale ());
1156 #else
1157   gboolean negative;
1158   guint64 result;
1159
1160   result = g_parse_long_long (nptr, (const gchar **) endptr, base, &negative);
1161
1162   /* Return the result of the appropriate sign.  */
1163   return negative ? -result : result;
1164 #endif
1165 }
1166
1167 /**
1168  * g_ascii_strtoll:
1169  * @nptr:    the string to convert to a numeric value.
1170  * @endptr:  if non-%NULL, it returns the character after
1171  *           the last character used in the conversion.
1172  * @base:    to be used for the conversion, 2..36 or 0
1173  *
1174  * Converts a string to a #gint64 value.
1175  * This function behaves like the standard strtoll() function
1176  * does in the C locale. It does this without actually
1177  * changing the current locale, since that would not be
1178  * thread-safe.
1179  *
1180  * This function is typically used when reading configuration
1181  * files or other non-user input that should be locale independent.
1182  * To handle input from the user you should normally use the
1183  * locale-sensitive system strtoll() function.
1184  *
1185  * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
1186  * is returned, and `ERANGE` is stored in `errno`.
1187  * If the base is outside the valid range, zero is returned, and
1188  * `EINVAL` is stored in `errno`. If the
1189  * string conversion fails, zero is returned, and @endptr returns @nptr
1190  * (if @endptr is non-%NULL).
1191  *
1192  * Returns: the #gint64 value or zero on error.
1193  *
1194  * Since: 2.12
1195  */
1196 gint64
1197 g_ascii_strtoll (const gchar *nptr,
1198                  gchar      **endptr,
1199                  guint        base)
1200 {
1201 #ifdef USE_XLOCALE
1202   return strtoll_l (nptr, endptr, base, get_C_locale ());
1203 #else
1204   gboolean negative;
1205   guint64 result;
1206
1207   result = g_parse_long_long (nptr, (const gchar **) endptr, base, &negative);
1208
1209   if (negative && result > (guint64) G_MININT64)
1210     {
1211       errno = ERANGE;
1212       return G_MININT64;
1213     }
1214   else if (!negative && result > (guint64) G_MAXINT64)
1215     {
1216       errno = ERANGE;
1217       return G_MAXINT64;
1218     }
1219   else if (negative)
1220     return - (gint64) result;
1221   else
1222     return (gint64) result;
1223 #endif
1224 }
1225
1226 /**
1227  * g_strerror:
1228  * @errnum: the system error number. See the standard C %errno
1229  *     documentation
1230  *
1231  * Returns a string corresponding to the given error code, e.g.
1232  * "no such process". You should use this function in preference to
1233  * strerror(), because it returns a string in UTF-8 encoding, and since
1234  * not all platforms support the strerror() function.
1235  *
1236  * Returns: a UTF-8 string describing the error code. If the error code
1237  *     is unknown, it returns "unknown error (<code>)".
1238  */
1239 const gchar *
1240 g_strerror (gint errnum)
1241 {
1242   gchar *msg;
1243   gchar *tofree = NULL;
1244   const gchar *ret;
1245   gint saved_errno = errno;
1246
1247   msg = strerror (errnum);
1248   if (!g_get_charset (NULL))
1249     msg = tofree = g_locale_to_utf8 (msg, -1, NULL, NULL, NULL);
1250
1251   ret = g_intern_string (msg);
1252   g_free (tofree);
1253   errno = saved_errno;
1254   return ret;
1255 }
1256
1257 /**
1258  * g_strsignal:
1259  * @signum: the signal number. See the `signal` documentation
1260  *
1261  * Returns a string describing the given signal, e.g. "Segmentation fault".
1262  * You should use this function in preference to strsignal(), because it
1263  * returns a string in UTF-8 encoding, and since not all platforms support
1264  * the strsignal() function.
1265  *
1266  * Returns: a UTF-8 string describing the signal. If the signal is unknown,
1267  *     it returns "unknown signal (<signum>)".
1268  */
1269 const gchar *
1270 g_strsignal (gint signum)
1271 {
1272   gchar *msg;
1273   gchar *tofree;
1274   const gchar *ret;
1275
1276   msg = tofree = NULL;
1277
1278 #ifdef HAVE_STRSIGNAL
1279   msg = strsignal (signum);
1280   if (!g_get_charset (NULL))
1281     msg = tofree = g_locale_to_utf8 (msg, -1, NULL, NULL, NULL);
1282 #endif
1283
1284   if (!msg)
1285     msg = tofree = g_strdup_printf ("unknown signal (%d)", signum);
1286   ret = g_intern_string (msg);
1287   g_free (tofree);
1288
1289   return ret;
1290 }
1291
1292 /* Functions g_strlcpy and g_strlcat were originally developed by
1293  * Todd C. Miller <Todd.Miller@courtesan.com> to simplify writing secure code.
1294  * See http://www.openbsd.org/cgi-bin/man.cgi?query=strlcpy
1295  * for more information.
1296  */
1297
1298 #ifdef HAVE_STRLCPY
1299 /* Use the native ones, if available; they might be implemented in assembly */
1300 gsize
1301 g_strlcpy (gchar       *dest,
1302            const gchar *src,
1303            gsize        dest_size)
1304 {
1305   g_return_val_if_fail (dest != NULL, 0);
1306   g_return_val_if_fail (src  != NULL, 0);
1307
1308   return strlcpy (dest, src, dest_size);
1309 }
1310
1311 gsize
1312 g_strlcat (gchar       *dest,
1313            const gchar *src,
1314            gsize        dest_size)
1315 {
1316   g_return_val_if_fail (dest != NULL, 0);
1317   g_return_val_if_fail (src  != NULL, 0);
1318
1319   return strlcat (dest, src, dest_size);
1320 }
1321
1322 #else /* ! HAVE_STRLCPY */
1323 /**
1324  * g_strlcpy:
1325  * @dest: destination buffer
1326  * @src: source buffer
1327  * @dest_size: length of @dest in bytes
1328  *
1329  * Portability wrapper that calls strlcpy() on systems which have it,
1330  * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
1331  * guaranteed to be nul-terminated; @src must be nul-terminated;
1332  * @dest_size is the buffer size, not the number of bytes to copy.
1333  *
1334  * At most @dest_size - 1 characters will be copied. Always nul-terminates
1335  * (unless @dest_size is 0). This function does not allocate memory. Unlike
1336  * strncpy(), this function doesn't pad @dest (so it's often faster). It
1337  * returns the size of the attempted result, strlen (src), so if
1338  * @retval >= @dest_size, truncation occurred.
1339  *
1340  * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
1341  * but if you really want to avoid screwups, g_strdup() is an even better
1342  * idea.
1343  *
1344  * Returns: length of @src
1345  */
1346 gsize
1347 g_strlcpy (gchar       *dest,
1348            const gchar *src,
1349            gsize        dest_size)
1350 {
1351   register gchar *d = dest;
1352   register const gchar *s = src;
1353   register gsize n = dest_size;
1354
1355   g_return_val_if_fail (dest != NULL, 0);
1356   g_return_val_if_fail (src  != NULL, 0);
1357
1358   /* Copy as many bytes as will fit */
1359   if (n != 0 && --n != 0)
1360     do
1361       {
1362         register gchar c = *s++;
1363
1364         *d++ = c;
1365         if (c == 0)
1366           break;
1367       }
1368     while (--n != 0);
1369
1370   /* If not enough room in dest, add NUL and traverse rest of src */
1371   if (n == 0)
1372     {
1373       if (dest_size != 0)
1374         *d = 0;
1375       while (*s++)
1376         ;
1377     }
1378
1379   return s - src - 1;  /* count does not include NUL */
1380 }
1381
1382 /**
1383  * g_strlcat:
1384  * @dest: destination buffer, already containing one nul-terminated string
1385  * @src: source buffer
1386  * @dest_size: length of @dest buffer in bytes (not length of existing string
1387  *     inside @dest)
1388  *
1389  * Portability wrapper that calls strlcat() on systems which have it,
1390  * and emulates it otherwise. Appends nul-terminated @src string to @dest,
1391  * guaranteeing nul-termination for @dest. The total size of @dest won't
1392  * exceed @dest_size.
1393  *
1394  * At most @dest_size - 1 characters will be copied. Unlike strncat(),
1395  * @dest_size is the full size of dest, not the space left over. This
1396  * function does not allocate memory. It always nul-terminates (unless
1397  * @dest_size == 0 or there were no nul characters in the @dest_size
1398  * characters of dest to start with).
1399  *
1400  * Caveat: this is supposedly a more secure alternative to strcat() or
1401  * strncat(), but for real security g_strconcat() is harder to mess up.
1402  *
1403  * Returns: size of attempted result, which is MIN (dest_size, strlen
1404  *     (original dest)) + strlen (src), so if retval >= dest_size,
1405  *     truncation occurred.
1406  */
1407 gsize
1408 g_strlcat (gchar       *dest,
1409            const gchar *src,
1410            gsize        dest_size)
1411 {
1412   register gchar *d = dest;
1413   register const gchar *s = src;
1414   register gsize bytes_left = dest_size;
1415   gsize dlength;  /* Logically, MIN (strlen (d), dest_size) */
1416
1417   g_return_val_if_fail (dest != NULL, 0);
1418   g_return_val_if_fail (src  != NULL, 0);
1419
1420   /* Find the end of dst and adjust bytes left but don't go past end */
1421   while (*d != 0 && bytes_left-- != 0)
1422     d++;
1423   dlength = d - dest;
1424   bytes_left = dest_size - dlength;
1425
1426   if (bytes_left == 0)
1427     return dlength + strlen (s);
1428
1429   while (*s != 0)
1430     {
1431       if (bytes_left != 1)
1432         {
1433           *d++ = *s;
1434           bytes_left--;
1435         }
1436       s++;
1437     }
1438   *d = 0;
1439
1440   return dlength + (s - src);  /* count does not include NUL */
1441 }
1442 #endif /* ! HAVE_STRLCPY */
1443
1444 /**
1445  * g_ascii_strdown:
1446  * @str: a string
1447  * @len: length of @str in bytes, or -1 if @str is nul-terminated
1448  *
1449  * Converts all upper case ASCII letters to lower case ASCII letters.
1450  *
1451  * Returns: a newly-allocated string, with all the upper case
1452  *     characters in @str converted to lower case, with semantics that
1453  *     exactly match g_ascii_tolower(). (Note that this is unlike the
1454  *     old g_strdown(), which modified the string in place.)
1455  */
1456 gchar*
1457 g_ascii_strdown (const gchar *str,
1458                  gssize       len)
1459 {
1460   gchar *result, *s;
1461
1462   g_return_val_if_fail (str != NULL, NULL);
1463
1464   if (len < 0)
1465     len = strlen (str);
1466
1467   result = g_strndup (str, len);
1468   for (s = result; *s; s++)
1469     *s = g_ascii_tolower (*s);
1470
1471   return result;
1472 }
1473
1474 /**
1475  * g_ascii_strup:
1476  * @str: a string
1477  * @len: length of @str in bytes, or -1 if @str is nul-terminated
1478  *
1479  * Converts all lower case ASCII letters to upper case ASCII letters.
1480  *
1481  * Returns: a newly allocated string, with all the lower case
1482  *     characters in @str converted to upper case, with semantics that
1483  *     exactly match g_ascii_toupper(). (Note that this is unlike the
1484  *     old g_strup(), which modified the string in place.)
1485  */
1486 gchar*
1487 g_ascii_strup (const gchar *str,
1488                gssize       len)
1489 {
1490   gchar *result, *s;
1491
1492   g_return_val_if_fail (str != NULL, NULL);
1493
1494   if (len < 0)
1495     len = strlen (str);
1496
1497   result = g_strndup (str, len);
1498   for (s = result; *s; s++)
1499     *s = g_ascii_toupper (*s);
1500
1501   return result;
1502 }
1503
1504 /**
1505  * g_str_is_ascii:
1506  * @str: a string
1507  *
1508  * Determines if a string is pure ASCII. A string is pure ASCII if it
1509  * contains no bytes with the high bit set.
1510  *
1511  * Returns: %TRUE if @str is ASCII
1512  *
1513  * Since: 2.40
1514  */
1515 gboolean
1516 g_str_is_ascii (const gchar *str)
1517 {
1518   gint i;
1519
1520   for (i = 0; str[i]; i++)
1521     if (str[i] & 0x80)
1522       return FALSE;
1523
1524   return TRUE;
1525 }
1526
1527 /**
1528  * g_strdown:
1529  * @string: the string to convert.
1530  *
1531  * Converts a string to lower case.
1532  *
1533  * Returns: the string
1534  *
1535  * Deprecated:2.2: This function is totally broken for the reasons discussed
1536  * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
1537  * instead.
1538  **/
1539 gchar*
1540 g_strdown (gchar *string)
1541 {
1542   register guchar *s;
1543
1544   g_return_val_if_fail (string != NULL, NULL);
1545
1546   s = (guchar *) string;
1547
1548   while (*s)
1549     {
1550       if (isupper (*s))
1551         *s = tolower (*s);
1552       s++;
1553     }
1554
1555   return (gchar *) string;
1556 }
1557
1558 /**
1559  * g_strup:
1560  * @string: the string to convert
1561  *
1562  * Converts a string to upper case.
1563  *
1564  * Returns: the string
1565  *
1566  * Deprecated:2.2: This function is totally broken for the reasons
1567  *     discussed in the g_strncasecmp() docs - use g_ascii_strup()
1568  *     or g_utf8_strup() instead.
1569  */
1570 gchar*
1571 g_strup (gchar *string)
1572 {
1573   register guchar *s;
1574
1575   g_return_val_if_fail (string != NULL, NULL);
1576
1577   s = (guchar *) string;
1578
1579   while (*s)
1580     {
1581       if (islower (*s))
1582         *s = toupper (*s);
1583       s++;
1584     }
1585
1586   return (gchar *) string;
1587 }
1588
1589 /**
1590  * g_strreverse:
1591  * @string: the string to reverse
1592  *
1593  * Reverses all of the bytes in a string. For example,
1594  * `g_strreverse ("abcdef")` will result in "fedcba".
1595  *
1596  * Note that g_strreverse() doesn't work on UTF-8 strings
1597  * containing multibyte characters. For that purpose, use
1598  * g_utf8_strreverse().
1599  *
1600  * Returns: the same pointer passed in as @string
1601  */
1602 gchar*
1603 g_strreverse (gchar *string)
1604 {
1605   g_return_val_if_fail (string != NULL, NULL);
1606
1607   if (*string)
1608     {
1609       register gchar *h, *t;
1610
1611       h = string;
1612       t = string + strlen (string) - 1;
1613
1614       while (h < t)
1615         {
1616           register gchar c;
1617
1618           c = *h;
1619           *h = *t;
1620           h++;
1621           *t = c;
1622           t--;
1623         }
1624     }
1625
1626   return string;
1627 }
1628
1629 /**
1630  * g_ascii_tolower:
1631  * @c: any character
1632  *
1633  * Convert a character to ASCII lower case.
1634  *
1635  * Unlike the standard C library tolower() function, this only
1636  * recognizes standard ASCII letters and ignores the locale, returning
1637  * all non-ASCII characters unchanged, even if they are lower case
1638  * letters in a particular character set. Also unlike the standard
1639  * library function, this takes and returns a char, not an int, so
1640  * don't call it on %EOF but no need to worry about casting to #guchar
1641  * before passing a possibly non-ASCII character in.
1642  *
1643  * Returns: the result of converting @c to lower case. If @c is
1644  *     not an ASCII upper case letter, @c is returned unchanged.
1645  */
1646 gchar
1647 g_ascii_tolower (gchar c)
1648 {
1649   return g_ascii_isupper (c) ? c - 'A' + 'a' : c;
1650 }
1651
1652 /**
1653  * g_ascii_toupper:
1654  * @c: any character
1655  *
1656  * Convert a character to ASCII upper case.
1657  *
1658  * Unlike the standard C library toupper() function, this only
1659  * recognizes standard ASCII letters and ignores the locale, returning
1660  * all non-ASCII characters unchanged, even if they are upper case
1661  * letters in a particular character set. Also unlike the standard
1662  * library function, this takes and returns a char, not an int, so
1663  * don't call it on %EOF but no need to worry about casting to #guchar
1664  * before passing a possibly non-ASCII character in.
1665  *
1666  * Returns: the result of converting @c to upper case. If @c is not
1667  *    an ASCII lower case letter, @c is returned unchanged.
1668  */
1669 gchar
1670 g_ascii_toupper (gchar c)
1671 {
1672   return g_ascii_islower (c) ? c - 'a' + 'A' : c;
1673 }
1674
1675 /**
1676  * g_ascii_digit_value:
1677  * @c: an ASCII character
1678  *
1679  * Determines the numeric value of a character as a decimal digit.
1680  * Differs from g_unichar_digit_value() because it takes a char, so
1681  * there's no worry about sign extension if characters are signed.
1682  *
1683  * Returns: If @c is a decimal digit (according to g_ascii_isdigit()),
1684  *    its numeric value. Otherwise, -1.
1685  */
1686 int
1687 g_ascii_digit_value (gchar c)
1688 {
1689   if (g_ascii_isdigit (c))
1690     return c - '0';
1691   return -1;
1692 }
1693
1694 /**
1695  * g_ascii_xdigit_value:
1696  * @c: an ASCII character.
1697  *
1698  * Determines the numeric value of a character as a hexidecimal
1699  * digit. Differs from g_unichar_xdigit_value() because it takes
1700  * a char, so there's no worry about sign extension if characters
1701  * are signed.
1702  *
1703  * Returns: If @c is a hex digit (according to g_ascii_isxdigit()),
1704  *     its numeric value. Otherwise, -1.
1705  */
1706 int
1707 g_ascii_xdigit_value (gchar c)
1708 {
1709   if (c >= 'A' && c <= 'F')
1710     return c - 'A' + 10;
1711   if (c >= 'a' && c <= 'f')
1712     return c - 'a' + 10;
1713   return g_ascii_digit_value (c);
1714 }
1715
1716 /**
1717  * g_ascii_strcasecmp:
1718  * @s1: string to compare with @s2
1719  * @s2: string to compare with @s1
1720  *
1721  * Compare two strings, ignoring the case of ASCII characters.
1722  *
1723  * Unlike the BSD strcasecmp() function, this only recognizes standard
1724  * ASCII letters and ignores the locale, treating all non-ASCII
1725  * bytes as if they are not letters.
1726  *
1727  * This function should be used only on strings that are known to be
1728  * in encodings where the bytes corresponding to ASCII letters always
1729  * represent themselves. This includes UTF-8 and the ISO-8859-*
1730  * charsets, but not for instance double-byte encodings like the
1731  * Windows Codepage 932, where the trailing bytes of double-byte
1732  * characters include all ASCII letters. If you compare two CP932
1733  * strings using this function, you will get false matches.
1734  *
1735  * Both @s1 and @s2 must be non-%NULL.
1736  *
1737  * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1738  *     or a positive value if @s1 > @s2.
1739  */
1740 gint
1741 g_ascii_strcasecmp (const gchar *s1,
1742                     const gchar *s2)
1743 {
1744   gint c1, c2;
1745
1746   g_return_val_if_fail (s1 != NULL, 0);
1747   g_return_val_if_fail (s2 != NULL, 0);
1748
1749   while (*s1 && *s2)
1750     {
1751       c1 = (gint)(guchar) TOLOWER (*s1);
1752       c2 = (gint)(guchar) TOLOWER (*s2);
1753       if (c1 != c2)
1754         return (c1 - c2);
1755       s1++; s2++;
1756     }
1757
1758   return (((gint)(guchar) *s1) - ((gint)(guchar) *s2));
1759 }
1760
1761 /**
1762  * g_ascii_strncasecmp:
1763  * @s1: string to compare with @s2
1764  * @s2: string to compare with @s1
1765  * @n: number of characters to compare
1766  *
1767  * Compare @s1 and @s2, ignoring the case of ASCII characters and any
1768  * characters after the first @n in each string.
1769  *
1770  * Unlike the BSD strcasecmp() function, this only recognizes standard
1771  * ASCII letters and ignores the locale, treating all non-ASCII
1772  * characters as if they are not letters.
1773  *
1774  * The same warning as in g_ascii_strcasecmp() applies: Use this
1775  * function only on strings known to be in encodings where bytes
1776  * corresponding to ASCII letters always represent themselves.
1777  *
1778  * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1779  *     or a positive value if @s1 > @s2.
1780  */
1781 gint
1782 g_ascii_strncasecmp (const gchar *s1,
1783                      const gchar *s2,
1784                      gsize        n)
1785 {
1786   gint c1, c2;
1787
1788   g_return_val_if_fail (s1 != NULL, 0);
1789   g_return_val_if_fail (s2 != NULL, 0);
1790
1791   while (n && *s1 && *s2)
1792     {
1793       n -= 1;
1794       c1 = (gint)(guchar) TOLOWER (*s1);
1795       c2 = (gint)(guchar) TOLOWER (*s2);
1796       if (c1 != c2)
1797         return (c1 - c2);
1798       s1++; s2++;
1799     }
1800
1801   if (n)
1802     return (((gint) (guchar) *s1) - ((gint) (guchar) *s2));
1803   else
1804     return 0;
1805 }
1806
1807 /**
1808  * g_strcasecmp:
1809  * @s1: a string
1810  * @s2: a string to compare with @s1
1811  *
1812  * A case-insensitive string comparison, corresponding to the standard
1813  * strcasecmp() function on platforms which support it.
1814  *
1815  * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1816  *     or a positive value if @s1 > @s2.
1817  *
1818  * Deprecated:2.2: See g_strncasecmp() for a discussion of why this
1819  *     function is deprecated and how to replace it.
1820  */
1821 gint
1822 g_strcasecmp (const gchar *s1,
1823               const gchar *s2)
1824 {
1825 #ifdef HAVE_STRCASECMP
1826   g_return_val_if_fail (s1 != NULL, 0);
1827   g_return_val_if_fail (s2 != NULL, 0);
1828
1829   return strcasecmp (s1, s2);
1830 #else
1831   gint c1, c2;
1832
1833   g_return_val_if_fail (s1 != NULL, 0);
1834   g_return_val_if_fail (s2 != NULL, 0);
1835
1836   while (*s1 && *s2)
1837     {
1838       /* According to A. Cox, some platforms have islower's that
1839        * don't work right on non-uppercase
1840        */
1841       c1 = isupper ((guchar)*s1) ? tolower ((guchar)*s1) : *s1;
1842       c2 = isupper ((guchar)*s2) ? tolower ((guchar)*s2) : *s2;
1843       if (c1 != c2)
1844         return (c1 - c2);
1845       s1++; s2++;
1846     }
1847
1848   return (((gint)(guchar) *s1) - ((gint)(guchar) *s2));
1849 #endif
1850 }
1851
1852 /**
1853  * g_strncasecmp:
1854  * @s1: a string
1855  * @s2: a string to compare with @s1
1856  * @n: the maximum number of characters to compare
1857  *
1858  * A case-insensitive string comparison, corresponding to the standard
1859  * strncasecmp() function on platforms which support it. It is similar
1860  * to g_strcasecmp() except it only compares the first @n characters of
1861  * the strings.
1862  *
1863  * Returns: 0 if the strings match, a negative value if @s1 < @s2,
1864  *     or a positive value if @s1 > @s2.
1865  *
1866  * Deprecated:2.2: The problem with g_strncasecmp() is that it does
1867  *     the comparison by calling toupper()/tolower(). These functions
1868  *     are locale-specific and operate on single bytes. However, it is
1869  *     impossible to handle things correctly from an internationalization
1870  *     standpoint by operating on bytes, since characters may be multibyte.
1871  *     Thus g_strncasecmp() is broken if your string is guaranteed to be
1872  *     ASCII, since it is locale-sensitive, and it's broken if your string
1873  *     is localized, since it doesn't work on many encodings at all,
1874  *     including UTF-8, EUC-JP, etc.
1875  *
1876  *     There are therefore two replacement techniques: g_ascii_strncasecmp(),
1877  *     which only works on ASCII and is not locale-sensitive, and
1878  *     g_utf8_casefold() followed by strcmp() on the resulting strings,
1879  *     which is good for case-insensitive sorting of UTF-8.
1880  */
1881 gint
1882 g_strncasecmp (const gchar *s1,
1883                const gchar *s2,
1884                guint n)
1885 {
1886 #ifdef HAVE_STRNCASECMP
1887   return strncasecmp (s1, s2, n);
1888 #else
1889   gint c1, c2;
1890
1891   g_return_val_if_fail (s1 != NULL, 0);
1892   g_return_val_if_fail (s2 != NULL, 0);
1893
1894   while (n && *s1 && *s2)
1895     {
1896       n -= 1;
1897       /* According to A. Cox, some platforms have islower's that
1898        * don't work right on non-uppercase
1899        */
1900       c1 = isupper ((guchar)*s1) ? tolower ((guchar)*s1) : *s1;
1901       c2 = isupper ((guchar)*s2) ? tolower ((guchar)*s2) : *s2;
1902       if (c1 != c2)
1903         return (c1 - c2);
1904       s1++; s2++;
1905     }
1906
1907   if (n)
1908     return (((gint) (guchar) *s1) - ((gint) (guchar) *s2));
1909   else
1910     return 0;
1911 #endif
1912 }
1913
1914 /**
1915  * g_strdelimit:
1916  * @string: the string to convert
1917  * @delimiters: (allow-none): a string containing the current delimiters,
1918  *     or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS
1919  * @new_delimiter: the new delimiter character
1920  *
1921  * Converts any delimiter characters in @string to @new_delimiter.
1922  * Any characters in @string which are found in @delimiters are
1923  * changed to the @new_delimiter character. Modifies @string in place,
1924  * and returns @string itself, not a copy. The return value is to
1925  * allow nesting such as
1926  * |[<!-- language="C" -->
1927  *   g_ascii_strup (g_strdelimit (str, "abc", '?'))
1928  * ]|
1929  *
1930  * Returns: @string
1931  */
1932 gchar *
1933 g_strdelimit (gchar       *string,
1934               const gchar *delimiters,
1935               gchar        new_delim)
1936 {
1937   register gchar *c;
1938
1939   g_return_val_if_fail (string != NULL, NULL);
1940
1941   if (!delimiters)
1942     delimiters = G_STR_DELIMITERS;
1943
1944   for (c = string; *c; c++)
1945     {
1946       if (strchr (delimiters, *c))
1947         *c = new_delim;
1948     }
1949
1950   return string;
1951 }
1952
1953 /**
1954  * g_strcanon:
1955  * @string: a nul-terminated array of bytes
1956  * @valid_chars: bytes permitted in @string
1957  * @substitutor: replacement character for disallowed bytes
1958  *
1959  * For each character in @string, if the character is not in @valid_chars,
1960  * replaces the character with @substitutor. Modifies @string in place,
1961  * and return @string itself, not a copy. The return value is to allow
1962  * nesting such as
1963  * |[<!-- language="C" -->
1964  *   g_ascii_strup (g_strcanon (str, "abc", '?'))
1965  * ]|
1966  *
1967  * Returns: @string
1968  */
1969 gchar *
1970 g_strcanon (gchar       *string,
1971             const gchar *valid_chars,
1972             gchar        substitutor)
1973 {
1974   register gchar *c;
1975
1976   g_return_val_if_fail (string != NULL, NULL);
1977   g_return_val_if_fail (valid_chars != NULL, NULL);
1978
1979   for (c = string; *c; c++)
1980     {
1981       if (!strchr (valid_chars, *c))
1982         *c = substitutor;
1983     }
1984
1985   return string;
1986 }
1987
1988 /**
1989  * g_strcompress:
1990  * @source: a string to compress
1991  *
1992  * Replaces all escaped characters with their one byte equivalent.
1993  *
1994  * This function does the reverse conversion of g_strescape().
1995  *
1996  * Returns: a newly-allocated copy of @source with all escaped
1997  *     character compressed
1998  */
1999 gchar *
2000 g_strcompress (const gchar *source)
2001 {
2002   const gchar *p = source, *octal;
2003   gchar *dest;
2004   gchar *q;
2005
2006   g_return_val_if_fail (source != NULL, NULL);
2007
2008   dest = g_malloc (strlen (source) + 1);
2009   q = dest;
2010
2011   while (*p)
2012     {
2013       if (*p == '\\')
2014         {
2015           p++;
2016           switch (*p)
2017             {
2018             case '\0':
2019               g_warning ("g_strcompress: trailing \\");
2020               goto out;
2021             case '0':  case '1':  case '2':  case '3':  case '4':
2022             case '5':  case '6':  case '7':
2023               *q = 0;
2024               octal = p;
2025               while ((p < octal + 3) && (*p >= '0') && (*p <= '7'))
2026                 {
2027                   *q = (*q * 8) + (*p - '0');
2028                   p++;
2029                 }
2030               q++;
2031               p--;
2032               break;
2033             case 'b':
2034               *q++ = '\b';
2035               break;
2036             case 'f':
2037               *q++ = '\f';
2038               break;
2039             case 'n':
2040               *q++ = '\n';
2041               break;
2042             case 'r':
2043               *q++ = '\r';
2044               break;
2045             case 't':
2046               *q++ = '\t';
2047               break;
2048             case 'v':
2049               *q++ = '\v';
2050               break;
2051             default:            /* Also handles \" and \\ */
2052               *q++ = *p;
2053               break;
2054             }
2055         }
2056       else
2057         *q++ = *p;
2058       p++;
2059     }
2060 out:
2061   *q = 0;
2062
2063   return dest;
2064 }
2065
2066 /**
2067  * g_strescape:
2068  * @source: a string to escape
2069  * @exceptions: a string of characters not to escape in @source
2070  *
2071  * Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
2072  * and '&quot;' in the string @source by inserting a '\' before
2073  * them. Additionally all characters in the range 0x01-0x1F (everything
2074  * below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
2075  * replaced with a '\' followed by their octal representation.
2076  * Characters supplied in @exceptions are not escaped.
2077  *
2078  * g_strcompress() does the reverse conversion.
2079  *
2080  * Returns: a newly-allocated copy of @source with certain
2081  *     characters escaped. See above.
2082  */
2083 gchar *
2084 g_strescape (const gchar *source,
2085              const gchar *exceptions)
2086 {
2087   const guchar *p;
2088   gchar *dest;
2089   gchar *q;
2090   guchar excmap[256];
2091
2092   g_return_val_if_fail (source != NULL, NULL);
2093
2094   p = (guchar *) source;
2095   /* Each source byte needs maximally four destination chars (\777) */
2096   q = dest = g_malloc (strlen (source) * 4 + 1);
2097
2098   memset (excmap, 0, 256);
2099   if (exceptions)
2100     {
2101       guchar *e = (guchar *) exceptions;
2102
2103       while (*e)
2104         {
2105           excmap[*e] = 1;
2106           e++;
2107         }
2108     }
2109
2110   while (*p)
2111     {
2112       if (excmap[*p])
2113         *q++ = *p;
2114       else
2115         {
2116           switch (*p)
2117             {
2118             case '\b':
2119               *q++ = '\\';
2120               *q++ = 'b';
2121               break;
2122             case '\f':
2123               *q++ = '\\';
2124               *q++ = 'f';
2125               break;
2126             case '\n':
2127               *q++ = '\\';
2128               *q++ = 'n';
2129               break;
2130             case '\r':
2131               *q++ = '\\';
2132               *q++ = 'r';
2133               break;
2134             case '\t':
2135               *q++ = '\\';
2136               *q++ = 't';
2137               break;
2138             case '\v':
2139               *q++ = '\\';
2140               *q++ = 'v';
2141               break;
2142             case '\\':
2143               *q++ = '\\';
2144               *q++ = '\\';
2145               break;
2146             case '"':
2147               *q++ = '\\';
2148               *q++ = '"';
2149               break;
2150             default:
2151               if ((*p < ' ') || (*p >= 0177))
2152                 {
2153                   *q++ = '\\';
2154                   *q++ = '0' + (((*p) >> 6) & 07);
2155                   *q++ = '0' + (((*p) >> 3) & 07);
2156                   *q++ = '0' + ((*p) & 07);
2157                 }
2158               else
2159                 *q++ = *p;
2160               break;
2161             }
2162         }
2163       p++;
2164     }
2165   *q = 0;
2166   return dest;
2167 }
2168
2169 /**
2170  * g_strchug:
2171  * @string: a string to remove the leading whitespace from
2172  *
2173  * Removes leading whitespace from a string, by moving the rest
2174  * of the characters forward.
2175  *
2176  * This function doesn't allocate or reallocate any memory;
2177  * it modifies @string in place. Therefore, it cannot be used on
2178  * statically allocated strings.
2179  *
2180  * The pointer to @string is returned to allow the nesting of functions.
2181  *
2182  * Also see g_strchomp() and g_strstrip().
2183  *
2184  * Returns: @string
2185  */
2186 gchar *
2187 g_strchug (gchar *string)
2188 {
2189   guchar *start;
2190
2191   g_return_val_if_fail (string != NULL, NULL);
2192
2193   for (start = (guchar*) string; *start && g_ascii_isspace (*start); start++)
2194     ;
2195
2196   memmove (string, start, strlen ((gchar *) start) + 1);
2197
2198   return string;
2199 }
2200
2201 /**
2202  * g_strchomp:
2203  * @string: a string to remove the trailing whitespace from
2204  *
2205  * Removes trailing whitespace from a string.
2206  *
2207  * This function doesn't allocate or reallocate any memory;
2208  * it modifies @string in place. Therefore, it cannot be used
2209  * on statically allocated strings.
2210  *
2211  * The pointer to @string is returned to allow the nesting of functions.
2212  *
2213  * Also see g_strchug() and g_strstrip().
2214  *
2215  * Returns: @string
2216  */
2217 gchar *
2218 g_strchomp (gchar *string)
2219 {
2220   gsize len;
2221
2222   g_return_val_if_fail (string != NULL, NULL);
2223
2224   len = strlen (string);
2225   while (len--)
2226     {
2227       if (g_ascii_isspace ((guchar) string[len]))
2228         string[len] = '\0';
2229       else
2230         break;
2231     }
2232
2233   return string;
2234 }
2235
2236 /**
2237  * g_strsplit:
2238  * @string: a string to split
2239  * @delimiter: a string which specifies the places at which to split
2240  *     the string. The delimiter is not included in any of the resulting
2241  *     strings, unless @max_tokens is reached.
2242  * @max_tokens: the maximum number of pieces to split @string into.
2243  *     If this is less than 1, the string is split completely.
2244  *
2245  * Splits a string into a maximum of @max_tokens pieces, using the given
2246  * @delimiter. If @max_tokens is reached, the remainder of @string is
2247  * appended to the last token.
2248  *
2249  * As a special case, the result of splitting the empty string "" is an empty
2250  * vector, not a vector containing a single string. The reason for this
2251  * special case is that being able to represent a empty vector is typically
2252  * more useful than consistent handling of empty elements. If you do need
2253  * to represent empty elements, you'll need to check for the empty string
2254  * before calling g_strsplit().
2255  *
2256  * Returns: a newly-allocated %NULL-terminated array of strings. Use
2257  *    g_strfreev() to free it.
2258  */
2259 gchar**
2260 g_strsplit (const gchar *string,
2261             const gchar *delimiter,
2262             gint         max_tokens)
2263 {
2264   GSList *string_list = NULL, *slist;
2265   gchar **str_array, *s;
2266   guint n = 0;
2267   const gchar *remainder;
2268
2269   g_return_val_if_fail (string != NULL, NULL);
2270   g_return_val_if_fail (delimiter != NULL, NULL);
2271   g_return_val_if_fail (delimiter[0] != '\0', NULL);
2272
2273   if (max_tokens < 1)
2274     max_tokens = G_MAXINT;
2275
2276   remainder = string;
2277   s = strstr (remainder, delimiter);
2278   if (s)
2279     {
2280       gsize delimiter_len = strlen (delimiter);
2281
2282       while (--max_tokens && s)
2283         {
2284           gsize len;
2285
2286           len = s - remainder;
2287           string_list = g_slist_prepend (string_list,
2288                                          g_strndup (remainder, len));
2289           n++;
2290           remainder = s + delimiter_len;
2291           s = strstr (remainder, delimiter);
2292         }
2293     }
2294   if (*string)
2295     {
2296       n++;
2297       string_list = g_slist_prepend (string_list, g_strdup (remainder));
2298     }
2299
2300   str_array = g_new (gchar*, n + 1);
2301
2302   str_array[n--] = NULL;
2303   for (slist = string_list; slist; slist = slist->next)
2304     str_array[n--] = slist->data;
2305
2306   g_slist_free (string_list);
2307
2308   return str_array;
2309 }
2310
2311 /**
2312  * g_strsplit_set:
2313  * @string: The string to be tokenized
2314  * @delimiters: A nul-terminated string containing bytes that are used
2315  *     to split the string.
2316  * @max_tokens: The maximum number of tokens to split @string into.
2317  *     If this is less than 1, the string is split completely
2318  *
2319  * Splits @string into a number of tokens not containing any of the characters
2320  * in @delimiter. A token is the (possibly empty) longest string that does not
2321  * contain any of the characters in @delimiters. If @max_tokens is reached, the
2322  * remainder is appended to the last token.
2323  *
2324  * For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
2325  * %NULL-terminated vector containing the three strings "abc", "def",
2326  * and "ghi".
2327  *
2328  * The result if g_strsplit_set (":def/ghi:", ":/", -1) is a %NULL-terminated
2329  * vector containing the four strings "", "def", "ghi", and "".
2330  *
2331  * As a special case, the result of splitting the empty string "" is an empty
2332  * vector, not a vector containing a single string. The reason for this
2333  * special case is that being able to represent a empty vector is typically
2334  * more useful than consistent handling of empty elements. If you do need
2335  * to represent empty elements, you'll need to check for the empty string
2336  * before calling g_strsplit_set().
2337  *
2338  * Note that this function works on bytes not characters, so it can't be used
2339  * to delimit UTF-8 strings for anything but ASCII characters.
2340  *
2341  * Returns: a newly-allocated %NULL-terminated array of strings. Use
2342  *    g_strfreev() to free it.
2343  *
2344  * Since: 2.4
2345  **/
2346 gchar **
2347 g_strsplit_set (const gchar *string,
2348                 const gchar *delimiters,
2349                 gint         max_tokens)
2350 {
2351   gboolean delim_table[256];
2352   GSList *tokens, *list;
2353   gint n_tokens;
2354   const gchar *s;
2355   const gchar *current;
2356   gchar *token;
2357   gchar **result;
2358
2359   g_return_val_if_fail (string != NULL, NULL);
2360   g_return_val_if_fail (delimiters != NULL, NULL);
2361
2362   if (max_tokens < 1)
2363     max_tokens = G_MAXINT;
2364
2365   if (*string == '\0')
2366     {
2367       result = g_new (char *, 1);
2368       result[0] = NULL;
2369       return result;
2370     }
2371
2372   memset (delim_table, FALSE, sizeof (delim_table));
2373   for (s = delimiters; *s != '\0'; ++s)
2374     delim_table[*(guchar *)s] = TRUE;
2375
2376   tokens = NULL;
2377   n_tokens = 0;
2378
2379   s = current = string;
2380   while (*s != '\0')
2381     {
2382       if (delim_table[*(guchar *)s] && n_tokens + 1 < max_tokens)
2383         {
2384           token = g_strndup (current, s - current);
2385           tokens = g_slist_prepend (tokens, token);
2386           ++n_tokens;
2387
2388           current = s + 1;
2389         }
2390
2391       ++s;
2392     }
2393
2394   token = g_strndup (current, s - current);
2395   tokens = g_slist_prepend (tokens, token);
2396   ++n_tokens;
2397
2398   result = g_new (gchar *, n_tokens + 1);
2399
2400   result[n_tokens] = NULL;
2401   for (list = tokens; list != NULL; list = list->next)
2402     result[--n_tokens] = list->data;
2403
2404   g_slist_free (tokens);
2405
2406   return result;
2407 }
2408
2409 /**
2410  * g_strfreev:
2411  * @str_array: a %NULL-terminated array of strings to free
2412
2413  * Frees a %NULL-terminated array of strings, and the array itself.
2414  * If called on a %NULL value, g_strfreev() simply returns.
2415  */
2416 void
2417 g_strfreev (gchar **str_array)
2418 {
2419   if (str_array)
2420     {
2421       int i;
2422
2423       for (i = 0; str_array[i] != NULL; i++)
2424         g_free (str_array[i]);
2425
2426       g_free (str_array);
2427     }
2428 }
2429
2430 /**
2431  * g_strdupv:
2432  * @str_array: a %NULL-terminated array of strings
2433  *
2434  * Copies %NULL-terminated array of strings. The copy is a deep copy;
2435  * the new array should be freed by first freeing each string, then
2436  * the array itself. g_strfreev() does this for you. If called
2437  * on a %NULL value, g_strdupv() simply returns %NULL.
2438  *
2439  * Returns: a new %NULL-terminated array of strings.
2440  */
2441 gchar**
2442 g_strdupv (gchar **str_array)
2443 {
2444   if (str_array)
2445     {
2446       gint i;
2447       gchar **retval;
2448
2449       i = 0;
2450       while (str_array[i])
2451         ++i;
2452
2453       retval = g_new (gchar*, i + 1);
2454
2455       i = 0;
2456       while (str_array[i])
2457         {
2458           retval[i] = g_strdup (str_array[i]);
2459           ++i;
2460         }
2461       retval[i] = NULL;
2462
2463       return retval;
2464     }
2465   else
2466     return NULL;
2467 }
2468
2469 /**
2470  * g_strjoinv:
2471  * @separator: (allow-none): a string to insert between each of the
2472  *     strings, or %NULL
2473  * @str_array: a %NULL-terminated array of strings to join
2474  *
2475  * Joins a number of strings together to form one long string, with the
2476  * optional @separator inserted between each of them. The returned string
2477  * should be freed with g_free().
2478  *
2479  * Returns: a newly-allocated string containing all of the strings joined
2480  *     together, with @separator between them
2481  */
2482 gchar*
2483 g_strjoinv (const gchar  *separator,
2484             gchar       **str_array)
2485 {
2486   gchar *string;
2487   gchar *ptr;
2488
2489   g_return_val_if_fail (str_array != NULL, NULL);
2490
2491   if (separator == NULL)
2492     separator = "";
2493
2494   if (*str_array)
2495     {
2496       gint i;
2497       gsize len;
2498       gsize separator_len;
2499
2500       separator_len = strlen (separator);
2501       /* First part, getting length */
2502       len = 1 + strlen (str_array[0]);
2503       for (i = 1; str_array[i] != NULL; i++)
2504         len += strlen (str_array[i]);
2505       len += separator_len * (i - 1);
2506
2507       /* Second part, building string */
2508       string = g_new (gchar, len);
2509       ptr = g_stpcpy (string, *str_array);
2510       for (i = 1; str_array[i] != NULL; i++)
2511         {
2512           ptr = g_stpcpy (ptr, separator);
2513           ptr = g_stpcpy (ptr, str_array[i]);
2514         }
2515       }
2516   else
2517     string = g_strdup ("");
2518
2519   return string;
2520 }
2521
2522 /**
2523  * g_strjoin:
2524  * @separator: (allow-none): a string to insert between each of the
2525  *     strings, or %NULL
2526  * @...: a %NULL-terminated list of strings to join
2527  *
2528  * Joins a number of strings together to form one long string, with the
2529  * optional @separator inserted between each of them. The returned string
2530  * should be freed with g_free().
2531  *
2532  * Returns: a newly-allocated string containing all of the strings joined
2533  *     together, with @separator between them
2534  */
2535 gchar*
2536 g_strjoin (const gchar *separator,
2537            ...)
2538 {
2539   gchar *string, *s;
2540   va_list args;
2541   gsize len;
2542   gsize separator_len;
2543   gchar *ptr;
2544
2545   if (separator == NULL)
2546     separator = "";
2547
2548   separator_len = strlen (separator);
2549
2550   va_start (args, separator);
2551
2552   s = va_arg (args, gchar*);
2553
2554   if (s)
2555     {
2556       /* First part, getting length */
2557       len = 1 + strlen (s);
2558
2559       s = va_arg (args, gchar*);
2560       while (s)
2561         {
2562           len += separator_len + strlen (s);
2563           s = va_arg (args, gchar*);
2564         }
2565       va_end (args);
2566
2567       /* Second part, building string */
2568       string = g_new (gchar, len);
2569
2570       va_start (args, separator);
2571
2572       s = va_arg (args, gchar*);
2573       ptr = g_stpcpy (string, s);
2574
2575       s = va_arg (args, gchar*);
2576       while (s)
2577         {
2578           ptr = g_stpcpy (ptr, separator);
2579           ptr = g_stpcpy (ptr, s);
2580           s = va_arg (args, gchar*);
2581         }
2582     }
2583   else
2584     string = g_strdup ("");
2585
2586   va_end (args);
2587
2588   return string;
2589 }
2590
2591
2592 /**
2593  * g_strstr_len:
2594  * @haystack: a string
2595  * @haystack_len: the maximum length of @haystack. Note that -1 is
2596  *     a valid length, if @haystack is nul-terminated, meaning it will
2597  *     search through the whole string.
2598  * @needle: the string to search for
2599  *
2600  * Searches the string @haystack for the first occurrence
2601  * of the string @needle, limiting the length of the search
2602  * to @haystack_len.
2603  *
2604  * Returns: a pointer to the found occurrence, or
2605  *    %NULL if not found.
2606  */
2607 gchar *
2608 g_strstr_len (const gchar *haystack,
2609               gssize       haystack_len,
2610               const gchar *needle)
2611 {
2612   g_return_val_if_fail (haystack != NULL, NULL);
2613   g_return_val_if_fail (needle != NULL, NULL);
2614
2615   if (haystack_len < 0)
2616     return strstr (haystack, needle);
2617   else
2618     {
2619       const gchar *p = haystack;
2620       gsize needle_len = strlen (needle);
2621       const gchar *end;
2622       gsize i;
2623
2624       if (needle_len == 0)
2625         return (gchar *)haystack;
2626
2627       if (haystack_len < needle_len)
2628         return NULL;
2629
2630       end = haystack + haystack_len - needle_len;
2631
2632       while (p <= end && *p)
2633         {
2634           for (i = 0; i < needle_len; i++)
2635             if (p[i] != needle[i])
2636               goto next;
2637
2638           return (gchar *)p;
2639
2640         next:
2641           p++;
2642         }
2643
2644       return NULL;
2645     }
2646 }
2647
2648 /**
2649  * g_strrstr:
2650  * @haystack: a nul-terminated string
2651  * @needle: the nul-terminated string to search for
2652  *
2653  * Searches the string @haystack for the last occurrence
2654  * of the string @needle.
2655  *
2656  * Returns: a pointer to the found occurrence, or
2657  *    %NULL if not found.
2658  */
2659 gchar *
2660 g_strrstr (const gchar *haystack,
2661            const gchar *needle)
2662 {
2663   gsize i;
2664   gsize needle_len;
2665   gsize haystack_len;
2666   const gchar *p;
2667
2668   g_return_val_if_fail (haystack != NULL, NULL);
2669   g_return_val_if_fail (needle != NULL, NULL);
2670
2671   needle_len = strlen (needle);
2672   haystack_len = strlen (haystack);
2673
2674   if (needle_len == 0)
2675     return (gchar *)haystack;
2676
2677   if (haystack_len < needle_len)
2678     return NULL;
2679
2680   p = haystack + haystack_len - needle_len;
2681
2682   while (p >= haystack)
2683     {
2684       for (i = 0; i < needle_len; i++)
2685         if (p[i] != needle[i])
2686           goto next;
2687
2688       return (gchar *)p;
2689
2690     next:
2691       p--;
2692     }
2693
2694   return NULL;
2695 }
2696
2697 /**
2698  * g_strrstr_len:
2699  * @haystack: a nul-terminated string
2700  * @haystack_len: the maximum length of @haystack
2701  * @needle: the nul-terminated string to search for
2702  *
2703  * Searches the string @haystack for the last occurrence
2704  * of the string @needle, limiting the length of the search
2705  * to @haystack_len.
2706  *
2707  * Returns: a pointer to the found occurrence, or
2708  *    %NULL if not found.
2709  */
2710 gchar *
2711 g_strrstr_len (const gchar *haystack,
2712                gssize        haystack_len,
2713                const gchar *needle)
2714 {
2715   g_return_val_if_fail (haystack != NULL, NULL);
2716   g_return_val_if_fail (needle != NULL, NULL);
2717
2718   if (haystack_len < 0)
2719     return g_strrstr (haystack, needle);
2720   else
2721     {
2722       gsize needle_len = strlen (needle);
2723       const gchar *haystack_max = haystack + haystack_len;
2724       const gchar *p = haystack;
2725       gsize i;
2726
2727       while (p < haystack_max && *p)
2728         p++;
2729
2730       if (p < haystack + needle_len)
2731         return NULL;
2732
2733       p -= needle_len;
2734
2735       while (p >= haystack)
2736         {
2737           for (i = 0; i < needle_len; i++)
2738             if (p[i] != needle[i])
2739               goto next;
2740
2741           return (gchar *)p;
2742
2743         next:
2744           p--;
2745         }
2746
2747       return NULL;
2748     }
2749 }
2750
2751
2752 /**
2753  * g_str_has_suffix:
2754  * @str: a nul-terminated string
2755  * @suffix: the nul-terminated suffix to look for
2756  *
2757  * Looks whether the string @str ends with @suffix.
2758  *
2759  * Returns: %TRUE if @str end with @suffix, %FALSE otherwise.
2760  *
2761  * Since: 2.2
2762  */
2763 gboolean
2764 g_str_has_suffix (const gchar *str,
2765                   const gchar *suffix)
2766 {
2767   int str_len;
2768   int suffix_len;
2769
2770   g_return_val_if_fail (str != NULL, FALSE);
2771   g_return_val_if_fail (suffix != NULL, FALSE);
2772
2773   str_len = strlen (str);
2774   suffix_len = strlen (suffix);
2775
2776   if (str_len < suffix_len)
2777     return FALSE;
2778
2779   return strcmp (str + str_len - suffix_len, suffix) == 0;
2780 }
2781
2782 /**
2783  * g_str_has_prefix:
2784  * @str: a nul-terminated string
2785  * @prefix: the nul-terminated prefix to look for
2786  *
2787  * Looks whether the string @str begins with @prefix.
2788  *
2789  * Returns: %TRUE if @str begins with @prefix, %FALSE otherwise.
2790  *
2791  * Since: 2.2
2792  */
2793 gboolean
2794 g_str_has_prefix (const gchar *str,
2795                   const gchar *prefix)
2796 {
2797   g_return_val_if_fail (str != NULL, FALSE);
2798   g_return_val_if_fail (prefix != NULL, FALSE);
2799
2800   return strncmp (str, prefix, strlen (prefix)) == 0;
2801 }
2802
2803 /**
2804  * g_strv_length:
2805  * @str_array: a %NULL-terminated array of strings
2806  *
2807  * Returns the length of the given %NULL-terminated
2808  * string array @str_array.
2809  *
2810  * Returns: length of @str_array.
2811  *
2812  * Since: 2.6
2813  */
2814 guint
2815 g_strv_length (gchar **str_array)
2816 {
2817   guint i = 0;
2818
2819   g_return_val_if_fail (str_array != NULL, 0);
2820
2821   while (str_array[i])
2822     ++i;
2823
2824   return i;
2825 }
2826
2827 static void
2828 index_add_folded (GPtrArray   *array,
2829                   const gchar *start,
2830                   const gchar *end)
2831 {
2832   gchar *normal;
2833
2834   normal = g_utf8_normalize (start, end - start, G_NORMALIZE_ALL_COMPOSE);
2835
2836   /* TODO: Invent time machine.  Converse with Mustafa Ataturk... */
2837   if (strstr (normal, "ı") || strstr (normal, "İ"))
2838     {
2839       gchar *s = normal;
2840       GString *tmp;
2841
2842       tmp = g_string_new (NULL);
2843
2844       while (*s)
2845         {
2846           gchar *i, *I, *e;
2847
2848           i = strstr (s, "ı");
2849           I = strstr (s, "İ");
2850
2851           if (!i && !I)
2852             break;
2853           else if (i && !I)
2854             e = i;
2855           else if (I && !i)
2856             e = I;
2857           else if (i < I)
2858             e = i;
2859           else
2860             e = I;
2861
2862           g_string_append_len (tmp, s, e - s);
2863           g_string_append_c (tmp, 'i');
2864           s = g_utf8_next_char (e);
2865         }
2866
2867       g_string_append (tmp, s);
2868       g_free (normal);
2869       normal = g_string_free (tmp, FALSE);
2870     }
2871
2872   g_ptr_array_add (array, g_utf8_casefold (normal, -1));
2873   g_free (normal);
2874 }
2875
2876 static gchar **
2877 split_words (const gchar *value)
2878 {
2879   const gchar *start = NULL;
2880   GPtrArray *result;
2881   const gchar *s;
2882
2883   result = g_ptr_array_new ();
2884
2885   for (s = value; *s; s = g_utf8_next_char (s))
2886     {
2887       gunichar c = g_utf8_get_char (s);
2888
2889       if (start == NULL)
2890         {
2891           if (g_unichar_isalnum (c) || g_unichar_ismark (c))
2892             start = s;
2893         }
2894       else
2895         {
2896           if (!g_unichar_isalnum (c) && !g_unichar_ismark (c))
2897             {
2898               index_add_folded (result, start, s);
2899               start = NULL;
2900             }
2901         }
2902     }
2903
2904   if (start)
2905     index_add_folded (result, start, s);
2906
2907   g_ptr_array_add (result, NULL);
2908
2909   return (gchar **) g_ptr_array_free (result, FALSE);
2910 }
2911
2912 /**
2913  * g_str_tokenize_and_fold:
2914  * @string: a string
2915  * @translit_locale: (allow-none): the language code (like 'de' or
2916  *   'en_GB') from which @string originates
2917  * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a
2918  *   return location for ASCII alternates
2919  *
2920  * Tokenises @string and performs folding on each token.
2921  *
2922  * A token is a non-empty sequence of alphanumeric characters in the
2923  * source string, separated by non-alphanumeric characters.  An
2924  * "alphanumeric" character for this purpose is one that matches
2925  * g_unichar_isalnum() or g_unichar_ismark().
2926  *
2927  * Each token is then (Unicode) normalised and case-folded.  If
2928  * @ascii_alternates is non-%NULL and some of the returned tokens
2929  * contain non-ASCII characters, ASCII alternatives will be generated.
2930  *
2931  * The number of ASCII alternatives that are generated and the method
2932  * for doing so is unspecified, but @translit_locale (if specified) may
2933  * improve the transliteration if the language of the source string is
2934  * known.
2935  *
2936  * Returns: (transfer full) (array zero-terminated=1): the folded tokens
2937  *
2938  * Since: 2.40
2939  **/
2940 gchar **
2941 g_str_tokenize_and_fold (const gchar   *string,
2942                          const gchar   *translit_locale,
2943                          gchar       ***ascii_alternates)
2944 {
2945   gchar **result;
2946
2947   g_return_val_if_fail (string != NULL, NULL);
2948
2949   if (ascii_alternates && g_str_is_ascii (string))
2950     {
2951       *ascii_alternates = g_new0 (gchar *, 0 + 1);
2952       ascii_alternates = NULL;
2953     }
2954
2955   result = split_words (string);
2956
2957   if (ascii_alternates)
2958     {
2959       gint i, j, n;
2960
2961       n = g_strv_length (result);
2962       *ascii_alternates = g_new (gchar *, n + 1);
2963       j = 0;
2964
2965       for (i = 0; i < n; i++)
2966         {
2967           if (!g_str_is_ascii (result[i]))
2968             {
2969               gchar *composed;
2970               gchar *ascii;
2971               gint k;
2972
2973               composed = g_utf8_normalize (result[i], -1, G_NORMALIZE_ALL_COMPOSE);
2974
2975               ascii = g_str_to_ascii (composed, translit_locale);
2976
2977               /* Only accept strings that are now entirely alnums */
2978               for (k = 0; ascii[k]; k++)
2979                 if (!g_ascii_isalnum (ascii[k]))
2980                   break;
2981
2982               if (ascii[k] == '\0')
2983                 /* Made it to the end... */
2984                 (*ascii_alternates)[j++] = ascii;
2985               else
2986                 g_free (ascii);
2987
2988               g_free (composed);
2989             }
2990         }
2991
2992       (*ascii_alternates)[j] = NULL;
2993     }
2994
2995   return result;
2996 }
2997
2998 /**
2999  * g_str_match_string:
3000  * @search_term: the search term from the user
3001  * @potential_hit: the text that may be a hit
3002  * @accept_alternates: %TRUE to accept ASCII alternates
3003  *
3004  * Checks if a search conducted for @search_term should match
3005  * @potential_hit.
3006  *
3007  * This function calls g_str_tokenize_and_fold() on both
3008  * @search_term and @potential_hit.  ASCII alternates are never taken
3009  * for @search_term but will be taken for @potential_hit according to
3010  * the value of @accept_alternates.
3011  *
3012  * A hit occurs when each folded token in @search_term is a prefix of a
3013  * folded token from @potential_hit.
3014  *
3015  * Depending on how you're performing the search, it will typically be
3016  * faster to call g_str_tokenize_and_fold() on each string in
3017  * your corpus and build an index on the returned folded tokens, then
3018  * call g_str_tokenize_and_fold() on the search term and
3019  * perform lookups into that index.
3020  *
3021  * As some examples, searching for "fred" would match the potential hit
3022  * "Smith, Fred" and also "Frédéric".  Searching for "Fréd" would match
3023  * "Frédéric" but not "Frederic" (due to the one-directional nature of
3024  * accent matching).  Searching "fo" would match "Foo" and "Bar Foo
3025  * Baz", but not "SFO" (because no word as "fo" as a prefix).
3026  *
3027  * Returns: %TRUE if @potential_hit is a hit
3028  *
3029  * Since: 2.40
3030  **/
3031 gboolean
3032 g_str_match_string (const gchar *search_term,
3033                     const gchar *potential_hit,
3034                     gboolean     accept_alternates)
3035 {
3036   gchar **alternates = NULL;
3037   gchar **term_tokens;
3038   gchar **hit_tokens;
3039   gboolean matched;
3040   gint i, j;
3041
3042   g_return_val_if_fail (search_term != NULL, FALSE);
3043   g_return_val_if_fail (potential_hit != NULL, FALSE);
3044
3045   term_tokens = g_str_tokenize_and_fold (search_term, NULL, NULL);
3046   hit_tokens = g_str_tokenize_and_fold (potential_hit, NULL, accept_alternates ? &alternates : NULL);
3047
3048   matched = TRUE;
3049
3050   for (i = 0; term_tokens[i]; i++)
3051     {
3052       for (j = 0; hit_tokens[j]; j++)
3053         if (g_str_has_prefix (hit_tokens[j], term_tokens[i]))
3054           goto one_matched;
3055
3056       if (accept_alternates)
3057         for (j = 0; alternates[j]; j++)
3058           if (g_str_has_prefix (alternates[j], term_tokens[i]))
3059             goto one_matched;
3060
3061       matched = FALSE;
3062       break;
3063
3064 one_matched:
3065       continue;
3066     }
3067
3068   g_strfreev (term_tokens);
3069   g_strfreev (hit_tokens);
3070   g_strfreev (alternates);
3071
3072   return matched;
3073 }