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 strlcat() on systems which have it, and emulates
 126 strlcat() otherwise. Appends nul-terminated @src string to @dest, guaranteeing
 127 nul-termination for @dest. The total size of @dest won't exceed
 128 @dest_size. Caveat: this is supposedly a more secure alternative to strcat() or
 129 strncat(), but for real security g_strconcat() is harder to mess up.
 130 </para>
 131
 132 @dest: destination buffer, already containing one nul-terminated string
 133 @src: source buffer
 134 @dest_size: length of @dest buffer in bytes (not length of existing string inside @dest)
 135 @Returns: length of @src plus initial length of string in @dest
 136
 137
 138 <!-- ##### FUNCTION g_strdup_printf ##### -->
 139 <para>
 140 Similar to the standard C <function>sprintf()</function> function
 141 but safer, since it calculates the maximum space required and allocates
 142 memory to hold the result.
 143 The returned string should be freed when no longer needed.
 144 </para>
 145
 146 @format: the standard <function>sprintf()</function> format string.
 147 @Varargs: the parameters to insert into the format string.
 148 @Returns: a newly-allocated string holding the result.
 149
 150
 151 <!-- ##### FUNCTION g_strdup_vprintf ##### -->
 152 <para>
 153 Similar to the standard C <function>vsprintf()</function> function
 154 but safer, since it calculates the maximum space required and allocates
 155 memory to hold the result.
 156 The returned string should be freed when no longer needed.
 157 </para>
 158
 159 @format: the standard <function>sprintf()</function> format string.
 160 @args: the list of parameters to insert into the format string.
 161 @Returns: a newly-allocated string holding the result.
 162
 163
 164 <!-- ##### FUNCTION g_snprintf ##### -->
 165 <para>
 166 A safer form of the standard <function>sprintf()</function> function.
 167 The output is guaranteed to not exceed @n characters (including the
 168 terminating nul character), so it is easy to ensure that a buffer overflow
 169 cannot occur.
 170 </para>
 171 <para>
 172 See also g_strdup_printf().
 173 </para>
 174 <note>
 175 <para>
 176 In versions of GLib prior to 1.2.3, this function may return -1 if the output
 177 was truncated, and the truncated string may not be nul-terminated.
 178 </para>
 179 </note>
 180
 181 @string: the buffer to hold the output.
 182 @n: the maximum number of characters to produce (including the terminating null
 183 character).
 184 @format: the format string. See the <function>sprintf()</function>
 185 documentation.
 186 @Varargs: the arguments to insert in the output.
 187 @Returns: the length of the output string.
 188
 189
 190 <!-- ##### FUNCTION g_vsnprintf ##### -->
 191 <para>
 192 A safer form of the standard <function>vsprintf()</function> function.
 193 The output is guaranteed to not exceed @n characters (including the
 194 terminating nul character), so it is easy to ensure that a buffer overflow
 195 cannot occur.
 196 </para>
 197 <para>
 198 See also g_strdup_vprintf().
 199 </para>
 200 <note>
 201 <para>
 202 In versions of GLib prior to 1.2.3, this function may return -1 if the output
 203 was truncated, and the truncated string may not be nul-terminated.
 204 </para>
 205 </note>
 206
 207 @string: the buffer to hold the output.
 208 @n: the maximum number of characters to produce (including the terminating null
 209 character).
 210 @format: the format string. See the <function>sprintf()</function>
 211 documentation.
 212 @args: the list of arguments to insert in the output.
 213 @Returns: the length of the output string.
 214
 215
 216 <!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
 217 <para>
 218 Calculates the maximum space needed to store the output of the
 219 <function>sprintf()</function> function.
 220 </para>
 221
 222 @format: the format string. See the <function>printf()</function>
 223 documentation.
 224 @args: the parameters to be inserted into the format string.
 225 @Returns: the maximum space needed to store the formatted string.
 226
 227
 228 <!-- ##### FUNCTION g_ascii_isalnum ##### -->
 229 <para>
 230 Determines whether a character is alphanumeric.
 231 </para>
 232 <para>
 233 Unlike the standard C library isalnum function, this only
 234 recognizes standard ASCII letters and ignores the locale, returning
 235 %FALSE for all non-ASCII characters. Also unlike the standard
 236 library function, this takes a char, not an int, so don't call it
 237 on EOF but no need to cast to guchar before passing a possibly
 238 non-ASCII character in.
 239 </para>
 240
 241 @c: any character
 242 @Returns: %TRUE if @c is an ASCII alphanumeric character
 243
 244
 245 <!-- ##### FUNCTION g_ascii_isalpha ##### -->
 246 <para>
 247 Determines whether a character is alphabetic (i.e. a letter).
 248 </para>
 249 <para>
 250 Unlike the standard C library isalpha function, this only
 251 recognizes standard ASCII letters and ignores the locale, returning
 252 %FALSE for all non-ASCII characters. Also unlike the standard
 253 library function, this takes a char, not an int, so don't call it
 254 on EOF but no need to cast to guchar before passing a possibly
 255 non-ASCII character in.
 256 </para>
 257
 258 @c: any character
 259 @Returns: %TRUE if @c is an ASCII alphabetic character
 260
 261
 262 <!-- ##### FUNCTION g_ascii_iscntrl ##### -->
 263 <para>
 264 Determines whether a character is a control character.
 265 </para>
 266 <para>
 267 Unlike the standard C library iscntrl function, this only
 268 recognizes standard ASCII control characters and ignores the locale,
 269 returning%FALSE for all non-ASCII characters. Also unlike the standard
 270 library function, this takes a char, not an int, so don't call it
 271 on EOF but no need to cast to guchar before passing a possibly
 272 non-ASCII character in.
 273 </para>
 274
 275 @c: any character
 276 @Returns: %TRUE if @c is an ASCII control character.
 277
 278
 279 <!-- ##### FUNCTION g_ascii_isdigit ##### -->
 280 <para>
 281 Determines whether a character is digit (0-9).
 282 </para>
 283 <para>
 284 Unlike the standard C library isdigit function,
 285 this takes a char, not an int, so don't call it
 286 on EOF but no need to cast to guchar before passing a possibly
 287 non-ASCII character in.
 288 </para>
 289
 290 @c: any character
 291 @Returns: %TRUE if @c is an ASCII digit.
 292
 293
 294 <!-- ##### FUNCTION g_ascii_isgraph ##### -->
 295 <para>
 296 Determines whether a character is a printing character and not a space.
 297 </para>
 298 <para>
 299 Unlike the standard C library isgraph function, this only
 300 recognizes standard ASCII characters and ignores the locale, returning
 301 %FALSE for all non-ASCII characters. Also unlike the standard
 302 library function, this takes a char, not an int, so don't call it
 303 on EOF but no need to cast to guchar before passing a possibly
 304 non-ASCII character in.
 305 </para>
 306
 307 @c: any character
 308 @Returns: %TRUE if @c is an ASCII printing character other than space.
 309
 310
 311 <!-- ##### FUNCTION g_ascii_islower ##### -->
 312 <para>
 313 Determines whether a character is an ASCII lower case letter.
 314 </para>
 315 <para>
 316 Unlike the standard C library islower function, this only
 317 recognizes standard ASCII letters and ignores the locale, returning
 318 %FALSE for all non-ASCII characters. Also unlike the standard
 319 library function, this takes a char, not an int, so don't call it
 320 on EOF but no need to worry about casting to guchar before passing
 321 a possibly non-ASCII character in.
 322 </para>
 323
 324 @c: any character
 325 @Returns: %TRUE if @c is an ASCII lower case letter
 326
 327
 328 <!-- ##### FUNCTION g_ascii_isprint ##### -->
 329 <para>
 330 Determines whether a character is a printing character.
 331 </para>
 332 <para>
 333 Unlike the standard C library isprint function, this only
 334 recognizes standard ASCII characters and ignores the locale, returning
 335 %FALSE for all non-ASCII characters. Also unlike the standard
 336 library function, this takes a char, not an int, so don't call it
 337 on EOF but no need to cast to guchar before passing a possibly
 338 non-ASCII character in.
 339 </para>
 340
 341 @c: any character
 342 @Returns: %TRUE if @c is an ASCII printing character.
 343
 344
 345 <!-- ##### FUNCTION g_ascii_ispunct ##### -->
 346 <para>
 347 Determines whether a character is a punctuation character.
 348 </para>
 349 <para>
 350 Unlike the standard C library ispunct function, this only
 351 recognizes standard ASCII letters and ignores the locale, returning
 352 %FALSE for all non-ASCII characters. Also unlike the standard
 353 library function, this takes a char, not an int, so don't call it
 354 on EOF but no need to cast to guchar before passing a possibly
 355 non-ASCII character in.
 356 </para>
 357
 358 @c: any character
 359 @Returns: %TRUE if @c is an ASCII punctuation character.
 360
 361
 362 <!-- ##### FUNCTION g_ascii_isspace ##### -->
 363 <para>
 364 Determines whether a character is a white-space character.
 365 </para>
 366 <para>
 367 Unlike the standard C library isspace function, this only
 368 recognizes standard ASCII white-space and ignores the locale, returning
 369 %FALSE for all non-ASCII characters. Also unlike the standard
 370 library function, this takes a char, not an int, so don't call it
 371 on EOF but no need to cast to guchar before passing a possibly
 372 non-ASCII character in.
 373 </para>
 374
 375 @c: any character
 376 @Returns: %TRUE if @c is an ASCII white-space character
 377
 378
 379 <!-- ##### FUNCTION g_ascii_isupper ##### -->
 380 <para>
 381 Determines whether a character is an ASCII upper case letter.
 382 </para>
 383 <para>
 384 Unlike the standard C library isupper function, this only
 385 recognizes standard ASCII letters and ignores the locale, returning
 386 %FALSE for all non-ASCII characters. Also unlike the standard
 387 library function, this takes a char, not an int, so don't call it
 388 on EOF but no need to worry about casting to guchar before passing
 389 a possibly non-ASCII character in.
 390 </para>
 391
 392 @c: any character
 393 @Returns: %TRUE if @c is an ASCII upper case letter
 394
 395
 396 <!-- ##### FUNCTION g_ascii_isxdigit ##### -->
 397 <para>
 398 Determines whether a character is a hexadecimal-digit character.
 399 </para>
 400 <para>
 401 Unlike the standard C library isxdigit function,
 402 this takes a char, not an int, so
 403 don't call it on EOF but no need to cast to guchar before passing a
 404 possibly non-ASCII character in.
 405 </para>
 406
 407 @c: any character
 408 @Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
 409
 410
 411 <!-- ##### FUNCTION g_ascii_digit_value ##### -->
 412 <para>
 413
 414 </para>
 415
 416 @c:
 417 @Returns:
 418
 419
 420 <!-- ##### FUNCTION g_ascii_xdigit_value ##### -->
 421 <para>
 422
 423 </para>
 424
 425 @c:
 426 @Returns:
 427
 428
 429 <!-- ##### FUNCTION g_ascii_strcasecmp ##### -->
 430 <para>
 431
 432 </para>
 433
 434 @s1:
 435 @s2:
 436 @Returns:
 437
 438
 439 <!-- ##### FUNCTION g_ascii_strncasecmp ##### -->
 440 <para>
 441
 442 </para>
 443
 444 @s1:
 445 @s2:
 446 @n:
 447 @Returns:
 448
 449
 450 <!-- ##### FUNCTION g_ascii_strup ##### -->
 451 <para>
 452
 453 </para>
 454
 455 @str:
 456 @len:
 457 @Returns:
 458 <!-- # Unused Parameters # -->
 459 @string:
 460
 461
 462 <!-- ##### FUNCTION g_ascii_strdown ##### -->
 463 <para>
 464
 465 </para>
 466
 467 @str:
 468 @len:
 469 @Returns:
 470 <!-- # Unused Parameters # -->
 471 @string:
 472
 473
 474 <!-- ##### FUNCTION g_ascii_tolower ##### -->
 475 <para>
 476
 477 </para>
 478
 479 @c:
 480 @Returns:
 481
 482
 483 <!-- ##### FUNCTION g_ascii_toupper ##### -->
 484 <para>
 485
 486 </para>
 487
 488 @c:
 489 @Returns:
 490
 491
 492 <!-- ##### FUNCTION g_string_ascii_up ##### -->
 493 <para>
 494
 495 </para>
 496
 497 @string:
 498 @Returns:
 499
 500
 501 <!-- ##### FUNCTION g_string_ascii_down ##### -->
 502 <para>
 503
 504 </para>
 505
 506 @string:
 507 @Returns:
 508
 509
 510 <!-- ##### FUNCTION g_strup ##### -->
 511 <para>
 512 Converts a string to upper case.
 513 </para>
 514
 515 @string: the string to convert.
 516 @Returns:
 517
 518
 519 <!-- ##### FUNCTION g_strdown ##### -->
 520 <para>
 521 Converts a string to lower case.
 522 </para>
 523
 524 @string: the string to convert.
 525 @Returns:
 526
 527
 528 <!-- ##### FUNCTION g_strcasecmp ##### -->
 529 <para>
 530 A case-insensitive string comparison, corresponding to the standard
 531 <function>strcasecmp()</function> function on platforms which support it.
 532 </para>
 533
 534 @s1: a string.
 535 @s2: a string to compare with @s1.
 536 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
 537 value if @s1 > @s2.
 538
 539
 540 <!-- ##### FUNCTION g_strncasecmp ##### -->
 541 <para>
 542 A case-insensitive string comparison, corresponding to the standard
 543 <function>strncasecmp()</function> function on platforms which support it.
 544 It is similar to g_strcasecmp() except it only compares the first @n characters
 545 of the strings.
 546 </para>
 547
 548 @s1: a string.
 549 @s2: a string to compare with @s1.
 550 @n: the maximum number of characters to compare.
 551 @Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive
 552 value if @s1 > @s2.
 553
 554
 555 <!-- ##### FUNCTION g_strreverse ##### -->
 556 <para>
 557 Reverses all of the characters in a string.
 558 For example, g_strreverse ("abcdef") would be "fedcba".
 559 </para>
 560
 561 @string: the string to reverse.
 562 @Returns:
 563
 564
 565 <!-- ##### FUNCTION g_strtod ##### -->
 566 <para>
 567 Converts a string to a gdouble value.
 568 It calls the standard <function>strtod()</function> function
 569 to handle the conversion, but if the string is not completely converted
 570 it attempts the conversion again in the "C" locale, and returns the best
 571 match.
 572 </para>
 573
 574 @nptr: the string to convert to a numeric value.
 575 @endptr: if non-NULL, it returns the character after the last character used
 576 in the conversion.
 577 @Returns: the gdouble value.
 578
 579
 580 <!-- ##### FUNCTION g_strchug ##### -->
 581 <para>
 582 Removes leading whitespace from a string, by moving the rest of the
 583 characters forward.
 584 </para>
 585
 586 @string: a string to remove the leading whitespace from.
 587 @Returns: @string.
 588
 589
 590 <!-- ##### FUNCTION g_strchomp ##### -->
 591 <para>
 592 Removes trailing whitespace from a string.
 593 </para>
 594
 595 @string: a string to remove the trailing whitespace from.
 596 @Returns: @string.
 597
 598
 599 <!-- ##### MACRO g_strstrip ##### -->
 600 <para>
 601 Removes leading and trailing whitespace from a string.
 602 </para>
 603
 604 @string: a string to remove the leading and trailing whitespace from.
 605
 606
 607 <!-- ##### FUNCTION g_strdelimit ##### -->
 608 <para>
 609 Converts any delimiter characters in @string to @new_delimiter.
 610 Any characters in @string which are found in @delimiters are changed
 611 to the @new_delimiter character.
 612 </para>
 613
 614 @string: the string to convert.
 615 @delimiters: a string containing the current delimiters, or %NULL to use the
 616 standard delimiters defined in #G_STR_DELIMITERS.
 617 @new_delimiter: the new delimiter character.
 618 @Returns:
 619
 620
 621 <!-- ##### MACRO G_STR_DELIMITERS ##### -->
 622 <para>
 623 The standard delimiters, used in #g_strdelimit.
 624 </para>
 625
 626
 627
 628 <!-- ##### FUNCTION g_strescape ##### -->
 629 <para>
 630 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
 631 '&quot;' in the string @source by inserting a '\' before
 632 them. Additionally all characters in the range 0x01-0x1F (everything
 633 below SPACE) and in the range 0x80-0xFF (all non-ASCII chars) are
 634 replaced with a '\' followed by their octal representation. Characters
 635 supplied in @exceptions are not escaped.
 636 </para>
 637
 638 <para>
 639 g_strcompress() does the reverse conversion.
 640 </para>
 641
 642 @source: a string to escape.
 643 @exceptions: a string of characters not to escape in @source.
 644 @Returns: a newly-allocated copy of @source with certain
 645 characters escaped. See above.
 646
 647
 648 <!-- ##### FUNCTION g_strcompress ##### -->
 649 <para>
 650 Replaces all escaped characters with their one byte equivalent. It
 651 does the reverse conversion of g_strescape().
 652 </para>
 653
 654 @source: a string to compress.
 655 @Returns: a newly-allocated copy of @source with all escaped
 656 character compressed.
 657
 658
 659 <!-- ##### FUNCTION g_strcanon ##### -->
 660 <para>
 661 For each character in @string, if the character is not in @valid_chars,
 662 replaces the character with @substitutor. Modifies @string in place,
 663 and return @string itself, not a copy. The return value is to allow
 664 nesting such as <literal>g_strup (g_strcanon (str))</literal>.
 665 </para>
 666
 667 @string: a nul-terminated array of bytes.
 668 @valid_chars: bytes permitted in @string.
 669 @substitutor: replacement character for disallowed bytes.
 670 @Returns: @string.
 671
 672
 673 <!-- ##### FUNCTION g_strsplit ##### -->
 674 <para>
 675 </para>
 676
 677 @string:
 678 @delimiter:
 679 @max_tokens:
 680 @Returns:
 681
 682
 683 <!-- ##### FUNCTION g_strfreev ##### -->
 684 <para>
 685 Frees a %NULL-terminated array of strings, and the array itself.
 686 </para>
 687
 688 @str_array: a %NULL-terminated array of strings to free.
 689
 690
 691 <!-- ##### FUNCTION g_strconcat ##### -->
 692 <para>
 693 Concatenates all of the given strings into one long string.  The returned string
 694 should be freed when no longer needed.  WARNING: THE VARIABLE ARGUMENT LIST MUST
 695 END WITH %NULL. If you forget the %NULL, g_strconcat() will start appending
 696 random memory junk to your string.
 697 </para>
 698
 699 @string1: The first string to add, which must not be %NULL.
 700 @Varargs: a %NULL-terminated list of strings to append to the string.
 701 @Returns: a newly-allocated string containing all the string arguments.
 702
 703
 704 <!-- ##### FUNCTION g_strjoin ##### -->
 705 <para>
 706 Joins a number of strings together to form one long string, with the optional
 707 @separator inserted between each of them.
 708 </para>
 709
 710 @separator: a string to insert between each of the strings, or %NULL.
 711 @Varargs: a %NULL-terminated list of strings to join.
 712 @Returns: a newly-allocated string containing all of the strings joined
 713 together, with @separator between them.
 714
 715
 716 <!-- ##### FUNCTION g_strjoinv ##### -->
 717 <para>
 718 Joins a number of strings together to form one long string, with the optional
 719 @separator inserted between each of them.
 720 </para>
 721
 722 @separator: a string to insert between each of the strings, or %NULL.
 723 @str_array: a %NULL-terminated array of strings to join.
 724 @Returns: a newly-allocated string containing all of the strings joined
 725 together, with @separator between them.
 726
 727
 728 <!-- ##### FUNCTION g_strerror ##### -->
 729 <para>
 730 Returns a string corresponding to the given error code, e.g. "no such process".
 731 This function is included since not all platforms support the
 732 <function>strerror()</function> function.
 733 </para>
 734
 735 @errnum: the system error number. See the standard C %errno
 736 documentation.
 737 @Returns: a string describing the error code.
 738 If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
 739 The string can only be used until the next call to g_strerror.
 740
 741
 742 <!-- ##### FUNCTION g_strsignal ##### -->
 743 <para>
 744 Returns a string describing the given signal, e.g. "Segmentation fault".
 745 This function is included since not all platforms support the
 746 <function>strsignal()</function> function.
 747 </para>
 748
 749 @signum: the signal number. See the <literal>signal</literal>
 750 documentation.
 751 @Returns: a string describing the signal.
 752 If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
 753 The string can only be used until the next call to g_strsignal.
 754
 755