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