docs/reference/glib/tmpl/string_utils.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 String Utility Functions
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 various string-related functions.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 This section describes a number of utility functions for creating,
  10 duplicating, and manipulating strings.
  11 </para>
  12
  13 <!-- ##### SECTION See_Also ##### -->
  14 <para>
  15
  16 </para>
  17
  18 <!-- ##### FUNCTION g_strdup ##### -->
  19 <para>
  20 Duplicates a string.
  21 The returned string should be freed when no longer needed.
  22 </para>
  23
  24 @str: the string to duplicate.
  25 @Returns: a newly-allocated copy of @str.
  26
  27
  28 <!-- ##### FUNCTION g_strndup ##### -->
  29 <para>
  30 Duplicates the first @n characters of a string, returning a newly-allocated
  31 buffer @n + 1 characters long which will always be nul-terminated.
  32 If @str is less than @n characters long the buffer is padded with nuls.
  33 The returned value should be freed when no longer needed.
  34 </para>
  35
  36 @str: the string to duplicate part of.
  37 @n: the maximum number of characters to copy from @str.
  38 @Returns: a newly-allocated buffer containing the first @n characters of @str,
  39 nul-terminated.
  40
  41
  42 <!-- ##### FUNCTION g_strdupv ##### -->
  43 <para>
  44 Copies a %NULL-terminated array of strings. The result consists of a
  45 %NULL-terminated array, with one malloc block holding the array of strings, and
  46 each string itself allocated. The simplest way to free the result is with
  47 g_strfreev() which frees each string in a vector, then the vector itself.
  48 </para>
  49
  50 @str_array: array to copy
  51 @Returns: a new array
  52
  53
  54 <!-- ##### FUNCTION g_strnfill ##### -->
  55 <para>
  56 Creates a new string @length characters long filled with @fill_char.
  57 The returned string should be freed when no longer needed.
  58 </para>
  59
  60 @length: the length of the new string.
  61 @fill_char: the character to fill the string with.
  62 @Returns: a newly-allocated string filled the @fill_char.
  63
  64
  65 <!-- ##### FUNCTION g_stpcpy ##### -->
  66 <para>
  67
  68 </para>
  69
  70 @dest:
  71 @src:
  72 @Returns:
  73
  74
  75 <!-- ##### FUNCTION g_strstr_len ##### -->
  76 <para>
  77
  78 </para>
  79
  80 @haystack:
  81 @haystack_len:
  82 @needle:
  83 @Returns:
  84
  85
  86 <!-- ##### FUNCTION g_strrstr ##### -->
  87 <para>
  88
  89 </para>
  90
  91 @haystack:
  92 @needle:
  93 @Returns:
  94
  95
  96 <!-- ##### FUNCTION g_strrstr_len ##### -->
  97 <para>
  98
  99 </para>
 100
 101 @haystack:
 102 @haystack_len:
 103 @needle:
 104 @Returns:
 105
 106
 107 <!-- ##### FUNCTION g_strlcpy ##### -->
 108 <para>
 109 Portability wrapper that calls strlcpy() on systems which have it, and emulates
 110 strlcpy() otherwise. Copies @src to @dest; @dest is guaranteed to be
 111 nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not
 112 the number of chars to copy. Caveat: strlcpy() is supposedly more secure than
 113 strcpy() or strncpy(), but if you really want to avoid screwups, g_strdup() is
 114 an even better idea.
 115 </para>
 116
 117 @dest: destination buffer
 118 @src: source buffer
 119 @dest_size: length of @dest in bytes
 120 @Returns: length of @src
 121
 122
 123 <!-- ##### FUNCTION g_strlcat ##### -->
 124 <para>
 125 Portability wrapper that calls <function>strlcat()</function> on systems which have it, and emulates it otherwise. Appends nul-terminated @src string to @dest, guaranteeing
 126 nul-termination for @dest. The total size of @dest won't exceed
 127 @dest_size. Caveat: this is supposedly a more secure alternative to <function>strcat()</function> or
 128 <function>strncat()</function>, but for real security g_strconcat() is harder to mess up.
 129 </para>
 130
 131 @dest: destination buffer, already containing one nul-terminated string
 132 @src: source buffer
 133 @dest_size: length of @dest buffer in bytes (not length of existing string inside @dest)
 134 @Returns: length of @src plus initial length of string in @dest
 135
 136
 137 <!-- ##### FUNCTION g_strdup_printf ##### -->
 138 <para>
 139 Similar to the standard C <function>sprintf()</function> function
 140 but safer, since it calculates the maximum space required and allocates
 141 memory to hold the result.
 142 The returned string should be freed when no longer needed.
 143 </para>
 144
 145 @format: the standard <function>sprintf()</function> format string.
 146 @Varargs: the parameters to insert into the format string.
 147 @Returns: a newly-allocated string holding the result.
 148
 149
 150 <!-- ##### FUNCTION g_strdup_vprintf ##### -->
 151 <para>
 152 Similar to the standard C <function>vsprintf()</function> function
 153 but safer, since it calculates the maximum space required and allocates
 154 memory to hold the result.
 155 The returned string should be freed when no longer needed.
 156 </para>
 157
 158 @format: the standard <function>sprintf()</function> format string.
 159 @args: the list of parameters to insert into the format string.
 160 @Returns: a newly-allocated string holding the result.
 161
 162
 163 <!-- ##### FUNCTION g_snprintf ##### -->
 164 <para>
 165 A safer form of the standard <function>sprintf()</function> function.
 166 The output is guaranteed to not exceed @n characters (including the
 167 terminating nul character), so it is easy to ensure that a buffer overflow
 168 cannot occur.
 169 </para>
 170 <para>
 171 See also g_strdup_printf().
 172 </para>
 173 <note>
 174 <para>
 175 In versions of GLib prior to 1.2.3, this function may return -1 if the output
 176 was truncated, and the truncated string may not be nul-terminated.
 177 In versions prior to 1.3.12, this function returns the length of the output
 178 string.
 179 </para>
 180 </note>
 181 <note>
 182 <para>
 183 The return value of g_snprintf() conforms to the <function>snprintf()</function>
 184 function as standardized in ISO C99. Note that this is different from
 185 traditional <function>snprintf()</function>, which returns the length of
 186 the output string.
 187 </para>
 188 </note>
 189
 190 @string: the buffer to hold the output.
 191 @n: the maximum number of characters to produce (including the terminating nul
 192 character).
 193 @format: the format string. See the <function>sprintf()</function>.
 194 documentation.
 195 @Varargs: the arguments to insert in the output.
 196 @Returns: the number of characters which would be produced if the buffer was
 197 large enough.
 198
 199
 200 <!-- ##### FUNCTION g_vsnprintf ##### -->
 201 <para>
 202 A safer form of the standard <function>vsprintf()</function> function.
 203 The output is guaranteed to not exceed @n characters (including the
 204 terminating nul character), so it is easy to ensure that a buffer overflow
 205 cannot occur.
 206 </para>
 207 <para>
 208 See also g_strdup_vprintf().
 209 </para>
 210 <note>
 211 <para>
 212 In versions of GLib prior to 1.2.3, this function may return -1 if the output
 213 was truncated, and the truncated string may not be nul-terminated.
 214 In versions prior to 1.3.12, this function returns the length of the output
 215 string.
 216 </para>
 217 </note>
 218 <note>
 219 <para>
 220 The return value of g_vsnprintf() conforms to the <function>vsnprintf()</function>
 221 function as standardized in ISO C99. Note that this is different from
 222 traditional <function>vsnprintf()</function>, which returns the length of
 223 the output string.
 224 </para>
 225 </note>
 226
 227 @string: the buffer to hold the output.
 228 @n: the maximum number of characters to produce (including the terminating nul
 229 character).
 230 @format: the format string. See the <function>sprintf()</function>
 231 documentation.
 232 @args: the list of arguments to insert in the output.
 233 @Returns: the number of characters which would be produced if the buffer was
 234 large enough.
 235
 236
 237 <!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
 238 <para>
 239 Calculates the maximum space needed to store the output of the
 240 <function>sprintf()</function> function.
 241 </para>
 242
 243 @format: the format string. See the <function>printf()</function>
 244 documentation.
 245 @args: the parameters to be inserted into the format string.
 246 @Returns: the maximum space needed to store the formatted string.
 247
 248
 249 <!-- ##### FUNCTION g_ascii_isalnum ##### -->
 250 <para>
 251 Determines whether a character is alphanumeric.
 252 </para>
 253 <para>
 254 Unlike the standard C library <function>isalnum()</function> function, this only
 255 recognizes standard ASCII letters and ignores the locale, returning
 256 %FALSE for all non-ASCII characters. Also unlike the standard
 257 library function, this takes a <type>char</type>, not an <type>int</type>,
 258 so don't call it on %EOF but no need to cast to #guchar before passing a
 259 possibly non-ASCII character in.
 260 </para>
 261
 262 @c: any character
 263 @Returns: %TRUE if @c is an ASCII alphanumeric character
 264
 265
 266 <!-- ##### FUNCTION g_ascii_isalpha ##### -->
 267 <para>
 268 Determines whether a character is alphabetic (i.e. a letter).
 269 </para>
 270 <para>
 271 Unlike the standard C library <function>isalpha()</function> function, this only
 272 recognizes standard ASCII letters and ignores the locale, returning
 273 %FALSE for all non-ASCII characters. Also unlike the standard
 274 library function, this takes a <type>char</type>, not an <type>int</type>,
 275 so don't call it on %EOF but no need to cast to #guchar before passing a
 276 possibly non-ASCII character in.
 277 </para>
 278
 279 @c: any character
 280 @Returns: %TRUE if @c is an ASCII alphabetic character
 281
 282
 283 <!-- ##### FUNCTION g_ascii_iscntrl ##### -->
 284 <para>
 285 Determines whether a character is a control character.
 286 </para>
 287 <para>
 288 Unlike the standard C library <function>iscntrl()</function> function, this only
 289 recognizes standard ASCII control characters and ignores the locale,
 290 returning %FALSE for all non-ASCII characters. Also unlike the standard
 291 library function, this takes a <type>char</type>, not an <type>int</type>,
 292 so don't call it on %EOF but no need to cast to #guchar before passing a
 293 possibly non-ASCII character in.
 294 </para>
 295
 296 @c: any character
 297 @Returns: %TRUE if @c is an ASCII control character.
 298
 299
 300 <!-- ##### FUNCTION g_ascii_isdigit ##### -->
 301 <para>
 302 Determines whether a character is digit (0-9).
 303 </para>
 304 <para>
 305 Unlike the standard C library <function>isdigit()</function> function,
 306 this takes a <type>char</type>, not an <type>int</type>, so don't call it
 307 on %EOF but no need to cast to #guchar before passing a possibly
 308 non-ASCII character in.
 309 </para>
 310
 311 @c: any character
 312 @Returns: %TRUE if @c is an ASCII digit.
 313
 314
 315 <!-- ##### FUNCTION g_ascii_isgraph ##### -->
 316 <para>
 317 Determines whether a character is a printing character and not a space.
 318 </para>
 319 <para>
 320 Unlike the standard C library <function>isgraph()</function> function,
 321 this only recognizes standard ASCII characters and ignores the locale,
 322 returning %FALSE for all non-ASCII characters. Also unlike the standard
 323 library function, this takes a <type>char</type>, not an <type>int</type>,
 324 so don't call it on %EOF but no need to cast to #guchar before passing a
 325 possibly non-ASCII character in.
 326 </para>
 327
 328 @c: any character
 329 @Returns: %TRUE if @c is an ASCII printing character other than space.
 330
 331
 332 <!-- ##### FUNCTION g_ascii_islower ##### -->
 333 <para>
 334 Determines whether a character is an ASCII lower case letter.
 335 </para>
 336 <para>
 337 Unlike the standard C library <function>islower()</function> function,
 338 this only recognizes standard ASCII letters and ignores the locale,
 339 returning %FALSE for all non-ASCII characters. Also unlike the standard
 340 library function, this takes a <type>char</type>, not an <type>int</type>,
 341 so don't call it on %EOF but no need to worry about casting to #guchar
 342 before passing a possibly non-ASCII character in.
 343 </para>
 344
 345 @c: any character
 346 @Returns: %TRUE if @c is an ASCII lower case letter
 347
 348
 349 <!-- ##### FUNCTION g_ascii_isprint ##### -->
 350 <para>
 351 Determines whether a character is a printing character.
 352 </para>
 353 <para>
 354 Unlike the standard C library <function>isprint()</function> function,
 355 this only recognizes standard ASCII characters and ignores the locale,
 356 returning %FALSE for all non-ASCII characters. Also unlike the standard
 357 library function, this takes a <type>char</type>, not an <type>int</type>,
 358 so don't call it on %EOF but no need to cast to #guchar before passing a
 359 possibly non-ASCII character in.
 360 </para>
 361
 362 @c: any character
 363 @Returns: %TRUE if @c is an ASCII printing character.
 364
 365
 366 <!-- ##### FUNCTION g_ascii_ispunct ##### -->
 367 <para>
 368 Determines whether a character is a punctuation character.
 369 </para>
 370 <para>
 371 Unlike the standard C library <function>ispunct()</function> function,
 372 this only recognizes standard ASCII letters and ignores the locale,
 373 returning %FALSE for all non-ASCII characters. Also unlike the standard
 374 library function, this takes a <type>char</type>, not an <type>int</type>,
 375 so don't call it on %EOF but no need to cast to #guchar before passing a
 376 possibly non-ASCII character in.
 377 </para>
 378
 379 @c: any character
 380 @Returns: %TRUE if @c is an ASCII punctuation character.
 381
 382
 383 <!-- ##### FUNCTION g_ascii_isspace ##### -->
 384 <para>
 385 Determines whether a character is a white-space character.
 386 </para>
 387 <para>
 388 Unlike the standard C library <function>isspace()</function> function,
 389 this only recognizes standard ASCII white-space and ignores the locale,
 390 returning %FALSE for all non-ASCII characters. Also unlike the standard
 391 library function, this takes a <type>char</type>, not an <type>int</type>,
 392 so don't call it on %EOF but no need to cast to #guchar before passing a
 393 possibly non-ASCII character in.
 394 </para>
 395
 396 @c: any character
 397 @Returns: %TRUE if @c is an ASCII white-space character
 398
 399
 400 <!-- ##### FUNCTION g_ascii_isupper ##### -->
 401 <para>
 402 Determines whether a character is an ASCII upper case letter.
 403 </para>
 404 <para>
 405 Unlike the standard C library <function>isupper()</function> function,
 406 this only recognizes standard ASCII letters and ignores the locale,
 407 returning %FALSE for all non-ASCII characters. Also unlike the standard
 408 library function, this takes a <type>char</type>, not an <type>int</type>,
 409 so don't call it on %EOF but no need to worry about casting to #guchar
 410 before passing a possibly non-ASCII character in.
 411 </para>
 412
 413 @c: any character
 414 @Returns: %TRUE if @c is an ASCII upper case letter
 415
 416
 417 <!-- ##### FUNCTION g_ascii_isxdigit ##### -->
 418 <para>
 419 Determines whether a character is a hexadecimal-digit character.
 420 </para>
 421 <para>
 422 Unlike the standard C library <function>isxdigit()</function> function,
 423 this takes a <type>char</type>, not an <type>int</type>, so
 424 don't call it on %EOF but no need to cast to #guchar before passing a
 425 possibly non-ASCII character in.
 426 </para>
 427
 428 @c: any character
 429 @Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
 430
 431
 432 <!-- ##### FUNCTION g_ascii_digit_value ##### -->
 433 <para>
 434
 435 </para>
 436
 437 @c:
 438 @Returns:
 439
 440
 441 <!-- ##### FUNCTION g_ascii_xdigit_value ##### -->
 442 <para>
 443
 444 </para>
 445
 446 @c:
 447 @Returns:
 448
 449
 450 <!-- ##### FUNCTION g_ascii_strcasecmp ##### -->
 451 <para>
 452
 453 </para>
 454
 455 @s1:
 456 @s2:
 457 @Returns:
 458
 459
 460 <!-- ##### FUNCTION g_ascii_strncasecmp ##### -->
 461 <para>
 462
 463 </para>
 464
 465 @s1:
 466 @s2:
 467 @n:
 468 @Returns:
 469
 470
 471 <!-- ##### FUNCTION g_ascii_strup ##### -->
 472 <para>
 473
 474 </para>
 475
 476 @str:
 477 @len:
 478 @Returns:
 479 <!-- # Unused Parameters # -->
 480 @string:
 481
 482
 483 <!-- ##### FUNCTION g_ascii_strdown ##### -->
 484 <para>
 485
 486 </para>
 487
 488 @str:
 489 @len:
 490 @Returns:
 491 <!-- # Unused Parameters # -->
 492 @string:
 493
 494
 495 <!-- ##### FUNCTION g_ascii_tolower ##### -->
 496 <para>
 497
 498 </para>
 499
 500 @c:
 501 @Returns:
 502
 503
 504 <!-- ##### FUNCTION g_ascii_toupper ##### -->
 505 <para>
 506
 507 </para>
 508
 509 @c:
 510 @Returns:
 511
 512
 513 <!-- ##### FUNCTION g_string_ascii_up ##### -->
 514 <para>
 515
 516 </para>
 517
 518 @string:
 519 @Returns:
 520
 521
 522 <!-- ##### FUNCTION g_string_ascii_down ##### -->
 523 <para>
 524
 525 </para>
 526
 527 @string:
 528 @Returns:
 529
 530
 531 <!-- ##### FUNCTION g_strup ##### -->
 532 <para>
 533 Converts a string to upper case. This function is totally broken
 534 for the reasons discussed in the g_strncasecmp() docs -
 535 use g_ascii_strup() or g_utf8_strup() instead.
 536 </para>
 537
 538 @string: the string to convert.
 539 @Returns:
 540
 541
 542 <!-- ##### FUNCTION g_strdown ##### -->
 543 <para>
 544 Converts a string to lower case.  This function is totally broken for
 545 the reasons discussed in the g_strncasecmp() docs - use
 546 g_ascii_strdown() or g_utf8_strdown() instead.
 547 </para>
 548
 549 @string: the string to convert.
 550 @Returns:
 551
 552
 553 <!-- ##### FUNCTION g_strcasecmp ##### -->
 554 <para>
 555 A case-insensitive string comparison, corresponding to the standard
 556 <function>strcasecmp()</function> function on platforms which support it.
 557 </para>
 558 <para>
 559 See g_strncasecmp() for a discussion of why this is deprecated and
 560 how to replace it.
 561 </para>
 562
 563 @s1: a string.
 564 @s2: a string to compare with @s1.
 565 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
 566 value if @s1 > @s2.
 567
 568
 569 <!-- ##### FUNCTION g_strncasecmp ##### -->
 570 <para>
 571 A case-insensitive string comparison, corresponding to the standard
 572 <function>strncasecmp()</function> function on platforms which support it.
 573 It is similar to g_strcasecmp() except it only compares the first @n characters
 574 of the strings.
 575 </para>
 576 <para>
 577 The problem with g_strncasecmp() is that it does the comparison by
 578 calling <function>toupper()</function>/<function>tolower()</function>
 579 on each byte. <function>toupper()</function>/<function>tolower()</function> are
 580 locale-specific and operate on single bytes. However, it is impossible
 581 to handle things correctly from an i18n standpoint by operating on
 582 bytes, since characters may be multibyte. Thus g_strncasecmp() is
 583 broken if your string is guaranteed to be ASCII, since it's
 584 locale-sensitive, and it's broken if your string is localized, since
 585 it doesn't work on many encodings at all, including UTF-8, EUC-JP,
 586 etc.
 587 </para>
 588 <para>
 589 There are therefore two replacement functions: g_ascii_strncasecmp(),
 590 which only works on ASCII and is not locale-sensitive, and
 591 g_utf8_casefold(), which is good for case-insensitive sorting of
 592 UTF-8.
 593 </para>
 594
 595 @s1: a string.
 596 @s2: a string to compare with @s1.
 597 @n: the maximum number of characters to compare.
 598 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
 599 value if @s1 > @s2.
 600
 601
 602 <!-- ##### FUNCTION g_strreverse ##### -->
 603 <para>
 604 Reverses all of the characters in a string.
 605 For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
 606 </para>
 607
 608 @string: the string to reverse.
 609 @Returns: the same pointer passed in as @string.
 610
 611
 612 <!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
 613 <para>
 614 A good size for a buffer to be passed into g_ascii_dtostr().
 615 It is guaranteed to be enough for all output of that function on systems with
 616  64bit IEEE-compatible doubles.
 617 </para>
 618 <para>
 619 The typical usage would be something like:
 620 <informalexample><programlisting>
 621   char buf[G_ASCII_DTOSTR_BUF_SIZE];
 622
 623   fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
 624 </programlisting></informalexample>
 625 </para>
 626
 627
 628
 629 <!-- ##### FUNCTION g_ascii_strtod ##### -->
 630 <para>
 631
 632 </para>
 633
 634 @nptr:
 635 @endptr:
 636 @Returns:
 637
 638
 639 <!-- ##### FUNCTION g_ascii_dtostr ##### -->
 640 <para>
 641
 642 </para>
 643
 644 @buffer:
 645 @buf_len:
 646 @d:
 647 @Returns:
 648 <!-- # Unused Parameters # -->
 649 @format:
 650
 651
 652 <!-- ##### FUNCTION g_ascii_formatd ##### -->
 653 <para>
 654
 655 </para>
 656
 657 @buffer:
 658 @buf_len:
 659 @format:
 660 @d:
 661 @Returns:
 662
 663
 664 <!-- ##### FUNCTION g_strtod ##### -->
 665 <para>
 666
 667 </para>
 668
 669 @nptr:
 670 @endptr:
 671 @Returns:
 672
 673
 674 <!-- ##### FUNCTION g_strchug ##### -->
 675 <para>
 676 Removes leading whitespace from a string, by moving the rest of the
 677 characters forward.
 678 </para>
 679
 680 @string: a string to remove the leading whitespace from.
 681 @Returns: @string.
 682
 683
 684 <!-- ##### FUNCTION g_strchomp ##### -->
 685 <para>
 686 Removes trailing whitespace from a string.
 687 </para>
 688
 689 @string: a string to remove the trailing whitespace from.
 690 @Returns: @string.
 691
 692
 693 <!-- ##### MACRO g_strstrip ##### -->
 694 <para>
 695 Removes leading and trailing whitespace from a string.
 696 </para>
 697
 698 @string: a string to remove the leading and trailing whitespace from.
 699
 700
 701 <!-- ##### FUNCTION g_strdelimit ##### -->
 702 <para>
 703 Converts any delimiter characters in @string to @new_delimiter.
 704 Any characters in @string which are found in @delimiters are changed
 705 to the @new_delimiter character.
 706 </para>
 707
 708 @string: the string to convert.
 709 @delimiters: a string containing the current delimiters, or %NULL to use the
 710 standard delimiters defined in #G_STR_DELIMITERS.
 711 @new_delimiter: the new delimiter character.
 712 @Returns:
 713
 714
 715 <!-- ##### MACRO G_STR_DELIMITERS ##### -->
 716 <para>
 717 The standard delimiters, used in g_strdelimit().
 718 </para>
 719
 720
 721
 722 <!-- ##### FUNCTION g_strescape ##### -->
 723 <para>
 724 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
 725 '&quot;' in the string @source by inserting a '\' before
 726 them. Additionally all characters in the range 0x01-0x1F (everything
 727 below SPACE) and in the range 0x80-0xFF (all non-ASCII chars) are
 728 replaced with a '\' followed by their octal representation. Characters
 729 supplied in @exceptions are not escaped.
 730 </para>
 731
 732 <para>
 733 g_strcompress() does the reverse conversion.
 734 </para>
 735
 736 @source: a string to escape.
 737 @exceptions: a string of characters not to escape in @source.
 738 @Returns: a newly-allocated copy of @source with certain
 739 characters escaped. See above.
 740
 741
 742 <!-- ##### FUNCTION g_strcompress ##### -->
 743 <para>
 744 Replaces all escaped characters with their one byte equivalent. It
 745 does the reverse conversion of g_strescape().
 746 </para>
 747
 748 @source: a string to compress.
 749 @Returns: a newly-allocated copy of @source with all escaped
 750 character compressed.
 751
 752
 753 <!-- ##### FUNCTION g_strcanon ##### -->
 754 <para>
 755 For each character in @string, if the character is not in @valid_chars,
 756 replaces the character with @substitutor. Modifies @string in place,
 757 and return @string itself, not a copy. The return value is to allow
 758 nesting such as <literal>g_ascii_strup (g_strcanon (str, "abc", '?'))</literal>.
 759 </para>
 760
 761 @string: a nul-terminated array of bytes.
 762 @valid_chars: bytes permitted in @string.
 763 @substitutor: replacement character for disallowed bytes.
 764 @Returns: @string.
 765
 766
 767 <!-- ##### FUNCTION g_strsplit ##### -->
 768 <para>
 769 </para>
 770
 771 @string:
 772 @delimiter:
 773 @max_tokens:
 774 @Returns:
 775
 776
 777 <!-- ##### FUNCTION g_strfreev ##### -->
 778 <para>
 779 Frees a %NULL-terminated array of strings, and the array itself.
 780 </para>
 781
 782 @str_array: a %NULL-terminated array of strings to free.
 783
 784
 785 <!-- ##### FUNCTION g_strconcat ##### -->
 786 <para>
 787 Concatenates all of the given strings into one long string.  The returned string
 788 should be freed when no longer needed.  WARNING: THE VARIABLE ARGUMENT LIST MUST
 789 END WITH %NULL. If you forget the %NULL, g_strconcat() will start appending
 790 random memory junk to your string.
 791 </para>
 792
 793 @string1: The first string to add, which must not be %NULL.
 794 @Varargs: a %NULL-terminated list of strings to append to the string.
 795 @Returns: a newly-allocated string containing all the string arguments.
 796
 797
 798 <!-- ##### FUNCTION g_strjoin ##### -->
 799 <para>
 800 Joins a number of strings together to form one long string, with the optional
 801 @separator inserted between each of them.
 802 </para>
 803
 804 @separator: a string to insert between each of the strings, or %NULL.
 805 @Varargs: a %NULL-terminated list of strings to join.
 806 @Returns: a newly-allocated string containing all of the strings joined
 807 together, with @separator between them.
 808
 809
 810 <!-- ##### FUNCTION g_strjoinv ##### -->
 811 <para>
 812 Joins a number of strings together to form one long string, with the optional
 813 @separator inserted between each of them.
 814 </para>
 815
 816 @separator: a string to insert between each of the strings, or %NULL.
 817 @str_array: a %NULL-terminated array of strings to join.
 818 @Returns: a newly-allocated string containing all of the strings joined
 819 together, with @separator between them.
 820
 821
 822 <!-- ##### FUNCTION g_strerror ##### -->
 823 <para>
 824 Returns a string corresponding to the given error code, e.g. "no such process".
 825 This function is included since not all platforms support the
 826 <function>strerror()</function> function.
 827 </para>
 828
 829 @errnum: the system error number. See the standard C %errno
 830 documentation.
 831 @Returns: a string describing the error code.
 832 If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
 833 The string can only be used until the next call to g_strerror.
 834
 835
 836 <!-- ##### FUNCTION g_strsignal ##### -->
 837 <para>
 838 Returns a string describing the given signal, e.g. "Segmentation fault".
 839 This function is included since not all platforms support the
 840 <function>strsignal()</function> function.
 841 </para>
 842
 843 @signum: the signal number. See the <literal>signal</literal>
 844 documentation.
 845 @Returns: a string describing the signal.
 846 If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
 847 The string can only be used until the next call to g_strsignal.
 848
 849