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#ifdef HAVE_UNISTD_H 34#include <unistd.h> 35#endif 36#include <stdarg.h> 37#include <stdlib.h> 38#include <stdio.h> 39#include <string.h> 40#include <ctype.h> 41 42#include "glib.h" 43#include "gprintf.h" 44 45#include "galias.h" 46 47struct _GStringChunk 48{ 49 GHashTable *const_table; 50 GSList *storage_list; 51 gsize storage_next; 52 gsize this_size; 53 gsize default_size; 54}; 55 56/* Hash Functions. 57 */ 58 59/** 60 * g_str_equal: 61 * @v1: a key 62 * @v2: a key to compare with @v1 63 * 64 * Compares two strings for byte-by-byte equality and returns %TRUE 65 * if they are equal. It can be passed to g_hash_table_new() as the 66 * @key_equal_func parameter, when using strings as keys in a #GHashTable. 67 * 68 * Returns: %TRUE if the two keys match 69 */ 70gboolean 71g_str_equal (gconstpointer v1, 72 gconstpointer v2) 73{ 74 const gchar *string1 = v1; 75 const gchar *string2 = v2; 76 77 return strcmp (string1, string2) == 0; 78} 79 80/** 81 * g_str_hash: 82 * @v: a string key 83 * 84 * Converts a string to a hash value. 85 * It can be passed to g_hash_table_new() as the @hash_func 86 * parameter, when using strings as keys in a #GHashTable. 87 * 88 * Returns: a hash value corresponding to the key 89 */ 90guint 91g_str_hash (gconstpointer v) 92{ 93 /* 31 bit hash function */ 94 const signed char *p = v; 95 guint32 h = *p; 96 97 if (h) 98 for (p += 1; *p != '\0'; p++) 99 h = (h << 5) - h + *p; 100 101 return h; 102} 103 104#define MY_MAXSIZE ((gsize)-1) 105 106static inline gsize 107nearest_power (gsize base, gsize num) 108{ 109 if (num > MY_MAXSIZE / 2) 110 { 111 return MY_MAXSIZE; 112 } 113 else 114 { 115 gsize n = base; 116 117 while (n < num) 118 n <<= 1; 119 120 return n; 121 } 122} 123 124/* String Chunks. 125 */ 126 127/** 128 * g_string_chunk_new: 129 * @size: the default size of the blocks of memory which are 130 * allocated to store the strings. If a particular string 131 * is larger than this default size, a larger block of 132 * memory will be allocated for it. 133 * 134 * Creates a new #GStringChunk. 135 * 136 * Returns: a new #GStringChunk 137 */ 138GStringChunk* 139g_string_chunk_new (gsize size) 140{ 141 GStringChunk *new_chunk = g_new (GStringChunk, 1); 142 gsize actual_size = 1; 143 144 actual_size = nearest_power (1, size); 145 146 new_chunk->const_table = NULL; 147 new_chunk->storage_list = NULL; 148 new_chunk->storage_next = actual_size; 149 new_chunk->default_size = actual_size; 150 new_chunk->this_size = actual_size; 151 152 return new_chunk; 153} 154 155/** 156 * g_string_chunk_free: 157 * @chunk: a #GStringChunk 158 * 159 * Frees all memory allocated by the #GStringChunk. 160 * After calling g_string_chunk_free() it is not safe to 161 * access any of the strings which were contained within it. 162 */ 163void 164g_string_chunk_free (GStringChunk *chunk) 165{ 166 GSList *tmp_list; 167 168 g_return_if_fail (chunk != NULL); 169 170 if (chunk->storage_list) 171 { 172 for (tmp_list = chunk->storage_list; tmp_list; tmp_list = tmp_list->next) 173 g_free (tmp_list->data); 174 175 g_slist_free (chunk->storage_list); 176 } 177 178 if (chunk->const_table) 179 g_hash_table_destroy (chunk->const_table); 180 181 g_free (chunk); 182} 183 184/** 185 * g_string_chunk_clear: 186 * @chunk: a #GStringChunk 187 * 188 * Frees all strings contained within the #GStringChunk. 189 * After calling g_string_chunk_clear() it is not safe to 190 * access any of the strings which were contained within it. 191 * 192 * Since: 2.14 193 */ 194void 195g_string_chunk_clear (GStringChunk *chunk) 196{ 197 GSList *tmp_list; 198 199 g_return_if_fail (chunk != NULL); 200 201 if (chunk->storage_list) 202 { 203 for (tmp_list = chunk->storage_list; tmp_list; tmp_list = tmp_list->next) 204 g_free (tmp_list->data); 205 206 g_slist_free (chunk->storage_list); 207 208 chunk->storage_list = NULL; 209 chunk->storage_next = chunk->default_size; 210 chunk->this_size = chunk->default_size; 211 } 212 213 if (chunk->const_table) 214 g_hash_table_remove_all (chunk->const_table); 215} 216 217/** 218 * g_string_chunk_insert: 219 * @chunk: a #GStringChunk 220 * @string: the string to add 221 * 222 * Adds a copy of @string to the #GStringChunk. 223 * It returns a pointer to the new copy of the string 224 * in the #GStringChunk. The characters in the string 225 * can be changed, if necessary, though you should not 226 * change anything after the end of the string. 227 * 228 * Unlike g_string_chunk_insert_const(), this function 229 * does not check for duplicates. Also strings added 230 * with g_string_chunk_insert() will not be searched 231 * by g_string_chunk_insert_const() when looking for 232 * duplicates. 233 * 234 * Returns: a pointer to the copy of @string within 235 * the #GStringChunk 236 */ 237gchar* 238g_string_chunk_insert (GStringChunk *chunk, 239 const gchar *string) 240{ 241 g_return_val_if_fail (chunk != NULL, NULL); 242 243 return g_string_chunk_insert_len (chunk, string, -1); 244} 245 246/** 247 * g_string_chunk_insert_const: 248 * @chunk: a #GStringChunk 249 * @string: the string to add 250 * 251 * Adds a copy of @string to the #GStringChunk, unless the same 252 * string has already been added to the #GStringChunk with 253 * g_string_chunk_insert_const(). 254 * 255 * This function is useful if you need to copy a large number 256 * of strings but do not want to waste space storing duplicates. 257 * But you must remember that there may be several pointers to 258 * the same string, and so any changes made to the strings 259 * should be done very carefully. 260 * 261 * Note that g_string_chunk_insert_const() will not return a 262 * pointer to a string added with g_string_chunk_insert(), even 263 * if they do match. 264 * 265 * Returns: a pointer to the new or existing copy of @string 266 * within the #GStringChunk 267 */ 268gchar* 269g_string_chunk_insert_const (GStringChunk *chunk, 270 const gchar *string) 271{ 272 char* lookup; 273 274 g_return_val_if_fail (chunk != NULL, NULL); 275 276 if (!chunk->const_table) 277 chunk->const_table = g_hash_table_new (g_str_hash, g_str_equal); 278 279 lookup = (char*) g_hash_table_lookup (chunk->const_table, (gchar *)string); 280 281 if (!lookup) 282 { 283 lookup = g_string_chunk_insert (chunk, string); 284 g_hash_table_insert (chunk->const_table, lookup, lookup); 285 } 286 287 return lookup; 288} 289 290/** 291 * g_string_chunk_insert_len: 292 * @chunk: a #GStringChunk 293 * @string: bytes to insert 294 * @len: number of bytes of @string to insert, or -1 to insert a 295 * nul-terminated string 296 * 297 * Adds a copy of the first @len bytes of @string to the #GStringChunk. 298 * The copy is nul-terminated. 299 * 300 * Since this function does not stop at nul bytes, it is the caller's 301 * responsibility to ensure that @string has at least @len addressable 302 * bytes. 303 * 304 * The characters in the returned string can be changed, if necessary, 305 * though you should not change anything after the end of the string. 306 * 307 * Return value: a pointer to the copy of @string within the #GStringChunk 308 * 309 * Since: 2.4 310 **/ 311gchar* 312g_string_chunk_insert_len (GStringChunk *chunk, 313 const gchar *string, 314 gssize len) 315{ 316 gssize size; 317 gchar* pos; 318 319 g_return_val_if_fail (chunk != NULL, NULL); 320 321 if (len < 0) 322 size = strlen (string); 323 else 324 size = len; 325 326 if ((chunk->storage_next + size + 1) > chunk->this_size) 327 { 328 gsize new_size = nearest_power (chunk->default_size, size + 1); 329 330 chunk->storage_list = g_slist_prepend (chunk->storage_list, 331 g_new (gchar, new_size)); 332 333 chunk->this_size = new_size; 334 chunk->storage_next = 0; 335 } 336 337 pos = ((gchar *) chunk->storage_list->data) + chunk->storage_next; 338 339 *(pos + size) = '\0'; 340 341 strncpy (pos, string, size); 342 if (len > 0) 343 size = strlen (pos); 344 345 chunk->storage_next += size + 1; 346 347 return pos; 348} 349 350/* Strings. 351 */ 352static void 353g_string_maybe_expand (GString* string, 354 gsize len) 355{ 356 if (string->len + len >= string->allocated_len) 357 { 358 string->allocated_len = nearest_power (1, string->len + len + 1); 359 string->str = g_realloc (string->str, string->allocated_len); 360 } 361} 362 363/** 364 * g_string_sized_new: 365 * @dfl_size: the default size of the space allocated to 366 * hold the string 367 * 368 * Creates a new #GString, with enough space for @dfl_size 369 * bytes. This is useful if you are going to add a lot of 370 * text to the string and don't want it to be reallocated 371 * too often. 372 * 373 * Returns: the new #GString 374 */ 375GString* 376g_string_sized_new (gsize dfl_size) 377{ 378 GString *string = g_slice_new (GString); 379 380 string->allocated_len = 0; 381 string->len = 0; 382 string->str = NULL; 383 384 g_string_maybe_expand (string, MAX (dfl_size, 2)); 385 string->str[0] = 0; 386 387 return string; 388} 389 390/** 391 * g_string_new: 392 * @init: the initial text to copy into the string 393 * 394 * Creates a new #GString, initialized with the given string. 395 * 396 * Returns: the new #GString 397 */ 398GString* 399g_string_new (const gchar *init) 400{ 401 GString *string; 402 403 if (init == NULL || *init == '\0') 404 string = g_string_sized_new (2); 405 else 406 { 407 gint len; 408 409 len = strlen (init); 410 string = g_string_sized_new (len + 2); 411 412 g_string_append_len (string, init, len); 413 } 414 415 return string; 416} 417 418/** 419 * g_string_new_len: 420 * @init: initial contents of the string 421 * @len: length of @init to use 422 * 423 * Creates a new #GString with @len bytes of the @init buffer. 424 * Because a length is provided, @init need not be nul-terminated, 425 * and can contain embedded nul bytes. 426 * 427 * Since this function does not stop at nul bytes, it is the caller's 428 * responsibility to ensure that @init has at least @len addressable 429 * bytes. 430 * 431 * Returns: a new #GString 432 */ 433GString* 434g_string_new_len (const gchar *init, 435 gssize len) 436{ 437 GString *string; 438 439 if (len < 0) 440 return g_string_new (init); 441 else 442 { 443 string = g_string_sized_new (len); 444 445 if (init) 446 g_string_append_len (string, init, len); 447 448 return string; 449 } 450} 451 452/** 453 * g_string_free: 454 * @string: a #GString 455 * @free_segment: if %TRUE the actual character data is freed as well 456 * 457 * Frees the memory allocated for the #GString. 458 * If @free_segment is %TRUE it also frees the character data. 459 * 460 * Returns: the character data of @string 461 * (i.e. %NULL if @free_segment is %TRUE) 462 */ 463gchar* 464g_string_free (GString *string, 465 gboolean free_segment) 466{ 467 gchar *segment; 468 469 g_return_val_if_fail (string != NULL, NULL); 470 471 if (free_segment) 472 { 473 g_free (string->str); 474 segment = NULL; 475 } 476 else 477 segment = string->str; 478 479 g_slice_free (GString, string); 480 481 return segment; 482} 483 484/** 485 * g_string_equal: 486 * @v: a #GString 487 * @v2: another #GString 488 * 489 * Compares two strings for equality, returning %TRUE if they are equal. 490 * For use with #GHashTable. 491 * 492 * Returns: %TRUE if they strings are the same length and contain the 493 * same bytes 494 */ 495gboolean 496g_string_equal (const GString *v, 497 const GString *v2) 498{ 499 gchar *p, *q; 500 GString *string1 = (GString *) v; 501 GString *string2 = (GString *) v2; 502 gsize i = string1->len; 503 504 if (i != string2->len) 505 return FALSE; 506 507 p = string1->str; 508 q = string2->str; 509 while (i) 510 { 511 if (*p != *q) 512 return FALSE; 513 p++; 514 q++; 515 i--; 516 } 517 return TRUE; 518} 519 520/** 521 * g_string_hash: 522 * @str: a string to hash 523 * 524 * Creates a hash code for @str; for use with #GHashTable. 525 * 526 * Returns: hash code for @str 527 */ 528/* 31 bit hash function */ 529guint 530g_string_hash (const GString *str) 531{ 532 const gchar *p = str->str; 533 gsize n = str->len; 534 guint h = 0; 535 536 while (n--) 537 { 538 h = (h << 5) - h + *p; 539 p++; 540 } 541 542 return h; 543} 544 545/** 546 * g_string_assign: 547 * @string: the destination #GString. Its current contents 548 * are destroyed. 549 * @rval: the string to copy into @string 550 * 551 * Copies the bytes from a string into a #GString, 552 * destroying any previous contents. It is rather like 553 * the standard strcpy() function, except that you do not 554 * have to worry about having enough space to copy the string. 555 * 556 * Returns: @string 557 */ 558GString* 559g_string_assign (GString *string, 560 const gchar *rval) 561{ 562 g_return_val_if_fail (string != NULL, NULL); 563 g_return_val_if_fail (rval != NULL, string); 564 565 /* Make sure assigning to itself doesn't corrupt the string. */ 566 if (string->str != rval) 567 { 568 /* Assigning from substring should be ok since g_string_truncate 569 does not realloc. */ 570 g_string_truncate (string, 0); 571 g_string_append (string, rval); 572 } 573 574 return string; 575} 576 577/** 578 * g_string_truncate: 579 * @string: a #GString 580 * @len: the new size of @string 581 * 582 * Cuts off the end of the GString, leaving the first @len bytes. 583 * 584 * Returns: @string 585 */ 586GString* 587g_string_truncate (GString *string, 588 gsize len) 589{ 590 g_return_val_if_fail (string != NULL, NULL); 591 592 string->len = MIN (len, string->len); 593 string->str[string->len] = 0; 594 595 return string; 596} 597 598/** 599 * g_string_set_size: 600 * @string: a #GString 601 * @len: the new length 602 * 603 * Sets the length of a #GString. If the length is less than 604 * the current length, the string will be truncated. If the 605 * length is greater than the current length, the contents 606 * of the newly added area are undefined. (However, as 607 * always, string->str[string->len] will be a nul byte.) 608 * 609 * Return value: @string 610 **/ 611GString* 612g_string_set_size (GString *string, 613 gsize len) 614{ 615 g_return_val_if_fail (string != NULL, NULL); 616 617 if (len >= string->allocated_len) 618 g_string_maybe_expand (string, len - string->len); 619 620 string->len = len; 621 string->str[len] = 0; 622 623 return string; 624} 625 626/** 627 * g_string_insert_len: 628 * @string: a #GString 629 * @pos: position in @string where insertion should 630 * happen, or -1 for at the end 631 * @val: bytes to insert 632 * @len: number of bytes of @val to insert 633 * 634 * Inserts @len bytes of @val into @string at @pos. 635 * Because @len is provided, @val may contain embedded 636 * nuls and need not be nul-terminated. If @pos is -1, 637 * bytes are inserted at the end of the string. 638 * 639 * Since this function does not stop at nul bytes, it is 640 * the caller's responsibility to ensure that @val has at 641 * least @len addressable bytes. 642 * 643 * Returns: @string 644 */ 645GString* 646g_string_insert_len (GString *string, 647 gssize pos, 648 const gchar *val, 649 gssize len) 650{ 651 g_return_val_if_fail (string != NULL, NULL); 652 g_return_val_if_fail (val != NULL, string); 653 654 if (len < 0) 655 len = strlen (val); 656 657 if (pos < 0) 658 pos = string->len; 659 else 660 g_return_val_if_fail (pos <= string->len, string); 661 662 /* Check whether val represents a substring of string. This test 663 probably violates chapter and verse of the C standards, since 664 ">=" and "<=" are only valid when val really is a substring. 665 In practice, it will work on modern archs. */ 666 if (val >= string->str && val <= string->str + string->len) 667 { 668 gsize offset = val - string->str; 669 gsize precount = 0; 670 671 g_string_maybe_expand (string, len); 672 val = string->str + offset; 673 /* At this point, val is valid again. */ 674 675 /* Open up space where we are going to insert. */ 676 if (pos < string->len) 677 g_memmove (string->str + pos + len, string->str + pos, string->len - pos); 678 679 /* Move the source part before the gap, if any. */ 680 if (offset < pos) 681 { 682 precount = MIN (len, pos - offset); 683 memcpy (string->str + pos, val, precount); 684 } 685 686 /* Move the source part after the gap, if any. */ 687 if (len > precount) 688 memcpy (string->str + pos + precount, 689 val + /* Already moved: */ precount + /* Space opened up: */ len, 690 len - precount); 691 } 692 else 693 { 694 g_string_maybe_expand (string, len); 695 696 /* If we aren't appending at the end, move a hunk 697 * of the old string to the end, opening up space 698 */ 699 if (pos < string->len) 700 g_memmove (string->str + pos + len, string->str + pos, string->len - pos); 701 702 /* insert the new string */ 703 if (len == 1) 704 string->str[pos] = *val; 705 else 706 memcpy (string->str + pos, val, len); 707 } 708 709 string->len += len; 710 711 string->str[string->len] = 0; 712 713 return string; 714} 715 716#define SUB_DELIM_CHARS "!$&'()*+,;=" 717 718static gboolean 719is_valid (char c, const char *reserved_chars_allowed) 720{ 721 if (g_ascii_isalnum (c) || 722 c == '-' || 723 c == '.' || 724 c == '_' || 725 c == '~') 726 return TRUE; 727 728 if (reserved_chars_allowed && 729 strchr (reserved_chars_allowed, c) != NULL) 730 return TRUE; 731 732 return FALSE; 733} 734 735static gboolean 736gunichar_ok (gunichar c) 737{ 738 return 739 (c != (gunichar) -2) && 740 (c != (gunichar) -1); 741} 742 743/** 744 * g_string_append_uri_escaped: 745 * @string: a #GString 746 * @unescaped: a string 747 * @reserved_chars_allowed: a string of reserved characters allowed to be used 748 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters 749 * 750 * Appends @unescaped to @string, escaped any characters that 751 * are reserved in URIs using URI-style escape sequences. 752 * 753 * Returns: @string 754 * 755 * Since: 2.16 756 **/ 757GString * 758g_string_append_uri_escaped (GString *string, 759 const char *unescaped, 760 const char *reserved_chars_allowed, 761 gboolean allow_utf8) 762{ 763 unsigned char c; 764 const char *end; 765 static const gchar hex[16] = "0123456789ABCDEF"; 766 767 g_return_val_if_fail (string != NULL, NULL); 768 g_return_val_if_fail (unescaped != NULL, NULL); 769 770 end = unescaped + strlen (unescaped); 771 772 while ((c = *unescaped) != 0) 773 { 774 if (c >= 0x80 && allow_utf8 && 775 gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped))) 776 { 777 int len = g_utf8_skip [c]; 778 g_string_append_len (string, unescaped, len); 779 unescaped += len; 780 } 781 else if (is_valid (c, reserved_chars_allowed)) 782 { 783 g_string_append_c (string, c); 784 unescaped++; 785 } 786 else 787 { 788 g_string_append_c (string, '%'); 789 g_string_append_c (string, hex[((guchar)c) >> 4]); 790 g_string_append_c (string, hex[((guchar)c) & 0xf]); 791 unescaped++; 792 } 793 } 794 795 return string; 796} 797 798/** 799 * g_string_append: 800 * @string: a #GString 801 * @val: the string to append onto the end of @string 802 * 803 * Adds a string onto the end of a #GString, expanding 804 * it if necessary. 805 * 806 * Returns: @string 807 */ 808GString* 809g_string_append (GString *string, 810 const gchar *val) 811{ 812 g_return_val_if_fail (string != NULL, NULL); 813 g_return_val_if_fail (val != NULL, string); 814 815 return g_string_insert_len (string, -1, val, -1); 816} 817 818/** 819 * g_string_append_len: 820 * @string: a #GString 821 * @val: bytes to append 822 * @len: number of bytes of @val to use 823 * 824 * Appends @len bytes of @val to @string. Because @len is 825 * provided, @val may contain embedded nuls and need not 826 * be nul-terminated. 827 * 828 * Since this function does not stop at nul bytes, it is 829 * the caller's responsibility to ensure that @val has at 830 * least @len addressable bytes. 831 * 832 * Returns: @string 833 */ 834GString* 835g_string_append_len (GString *string, 836 const gchar *val, 837 gssize len) 838{ 839 g_return_val_if_fail (string != NULL, NULL); 840 g_return_val_if_fail (val != NULL, string); 841 842 return g_string_insert_len (string, -1, val, len); 843} 844 845/** 846 * g_string_append_c: 847 * @string: a #GString 848 * @c: the byte to append onto the end of @string 849 * 850 * Adds a byte onto the end of a #GString, expanding 851 * it if necessary. 852 * 853 * Returns: @string 854 */ 855#undef g_string_append_c 856GString* 857g_string_append_c (GString *string, 858 gchar c) 859{ 860 g_return_val_if_fail (string != NULL, NULL); 861 862 return g_string_insert_c (string, -1, c); 863} 864 865/** 866 * g_string_append_unichar: 867 * @string: a #GString 868 * @wc: a Unicode character 869 * 870 * Converts a Unicode character into UTF-8, and appends it 871 * to the string. 872 * 873 * Return value: @string 874 **/ 875GString* 876g_string_append_unichar (GString *string, 877 gunichar wc) 878{ 879 g_return_val_if_fail (string != NULL, NULL); 880 881 return g_string_insert_unichar (string, -1, wc); 882} 883 884/** 885 * g_string_prepend: 886 * @string: a #GString 887 * @val: the string to prepend on the start of @string 888 * 889 * Adds a string on to the start of a #GString, 890 * expanding it if necessary. 891 * 892 * Returns: @string 893 */ 894GString* 895g_string_prepend (GString *string, 896 const gchar *val) 897{ 898 g_return_val_if_fail (string != NULL, NULL); 899 g_return_val_if_fail (val != NULL, string); 900 901 return g_string_insert_len (string, 0, val, -1); 902} 903 904/** 905 * g_string_prepend_len: 906 * @string: a #GString 907 * @val: bytes to prepend 908 * @len: number of bytes in @val to prepend 909 * 910 * Prepends @len bytes of @val to @string. 911 * Because @len is provided, @val may contain 912 * embedded nuls and need not be nul-terminated. 913 * 914 * Since this function does not stop at nul bytes, 915 * it is the caller's responsibility to ensure that 916 * @val has at least @len addressable bytes. 917 * 918 * Returns: @string 919 */ 920GString* 921g_string_prepend_len (GString *string, 922 const gchar *val, 923 gssize len) 924{ 925 g_return_val_if_fail (string != NULL, NULL); 926 g_return_val_if_fail (val != NULL, string); 927 928 return g_string_insert_len (string, 0, val, len); 929} 930 931/** 932 * g_string_prepend_c: 933 * @string: a #GString 934 * @c: the byte to prepend on the start of the #GString 935 * 936 * Adds a byte onto the start of a #GString, 937 * expanding it if necessary. 938 * 939 * Returns: @string 940 */ 941GString* 942g_string_prepend_c (GString *string, 943 gchar c) 944{ 945 g_return_val_if_fail (string != NULL, NULL); 946 947 return g_string_insert_c (string, 0, c); 948} 949 950/** 951 * g_string_prepend_unichar: 952 * @string: a #GString 953 * @wc: a Unicode character 954 * 955 * Converts a Unicode character into UTF-8, and prepends it 956 * to the string. 957 * 958 * Return value: @string 959 **/ 960GString* 961g_string_prepend_unichar (GString *string, 962 gunichar wc) 963{ 964 g_return_val_if_fail (string != NULL, NULL); 965 966 return g_string_insert_unichar (string, 0, wc); 967} 968 969/** 970 * g_string_insert: 971 * @string: a #GString 972 * @pos: the position to insert the copy of the string 973 * @val: the string to insert 974 * 975 * Inserts a copy of a string into a #GString, 976 * expanding it if necessary. 977 * 978 * Returns: @string 979 */ 980GString* 981g_string_insert (GString *string, 982 gssize pos, 983 const gchar *val) 984{ 985 g_return_val_if_fail (string != NULL, NULL); 986 g_return_val_if_fail (val != NULL, string); 987 if (pos >= 0) 988 g_return_val_if_fail (pos <= string->len, string); 989 990 return g_string_insert_len (string, pos, val, -1); 991} 992 993/** 994 * g_string_insert_c: 995 * @string: a #GString 996 * @pos: the position to insert the byte 997 * @c: the byte to insert 998 * 999 * Inserts a byte into a #GString, expanding it if necessary. 1000 * 1001 * Returns: @string 1002 */ 1003GString* 1004g_string_insert_c (GString *string, 1005 gssize pos, 1006 gchar c) 1007{ 1008 g_return_val_if_fail (string != NULL, NULL); 1009 1010 g_string_maybe_expand (string, 1); 1011 1012 if (pos < 0) 1013 pos = string->len; 1014 else 1015 g_return_val_if_fail (pos <= string->len, string); 1016 1017 /* If not just an append, move the old stuff */ 1018 if (pos < string->len) 1019 g_memmove (string->str + pos + 1, string->str + pos, string->len - pos); 1020 1021 string->str[pos] = c; 1022 1023 string->len += 1; 1024 1025 string->str[string->len] = 0; 1026 1027 return string; 1028} 1029 1030/** 1031 * g_string_insert_unichar: 1032 * @string: a #GString 1033 * @pos: the position at which to insert character, or -1 to 1034 * append at the end of the string 1035 * @wc: a Unicode character 1036 * 1037 * Converts a Unicode character into UTF-8, and insert it 1038 * into the string at the given position. 1039 * 1040 * Return value: @string 1041 **/ 1042GString* 1043g_string_insert_unichar (GString *string, 1044 gssize pos, 1045 gunichar wc) 1046{ 1047 gint charlen, first, i; 1048 gchar *dest; 1049 1050 g_return_val_if_fail (string != NULL, NULL); 1051 1052 /* Code copied from g_unichar_to_utf() */ 1053 if (wc < 0x80) 1054 { 1055 first = 0; 1056 charlen = 1; 1057 } 1058 else if (wc < 0x800) 1059 { 1060 first = 0xc0; 1061 charlen = 2; 1062 } 1063 else if (wc < 0x10000) 1064 { 1065 first = 0xe0; 1066 charlen = 3; 1067 } 1068 else if (wc < 0x200000) 1069 { 1070 first = 0xf0; 1071 charlen = 4; 1072 } 1073 else if (wc < 0x4000000) 1074 { 1075 first = 0xf8; 1076 charlen = 5; 1077 } 1078 else 1079 { 1080 first = 0xfc; 1081 charlen = 6; 1082 } 1083 /* End of copied code */ 1084 1085 g_string_maybe_expand (string, charlen); 1086 1087 if (pos < 0) 1088 pos = string->len; 1089 else 1090 g_return_val_if_fail (pos <= string->len, string); 1091 1092 /* If not just an append, move the old stuff */ 1093 if (pos < string->len) 1094 g_memmove (string->str + pos + charlen, string->str + pos, string->len - pos); 1095 1096 dest = string->str + pos; 1097 /* Code copied from g_unichar_to_utf() */ 1098 for (i = charlen - 1; i > 0; --i) 1099 { 1100 dest[i] = (wc & 0x3f) | 0x80; 1101 wc >>= 6; 1102 } 1103 dest[0] = wc | first; 1104 /* End of copied code */ 1105 1106 string->len += charlen; 1107 1108 string->str[string->len] = 0; 1109 1110 return string; 1111} 1112 1113/** 1114 * g_string_overwrite: 1115 * @string: a #GString 1116 * @pos: the position at which to start overwriting 1117 * @val: the string that will overwrite the @string starting at @pos 1118 * 1119 * Overwrites part of a string, lengthening it if necessary. 1120 * 1121 * Return value: @string 1122 * 1123 * Since: 2.14 1124 **/ 1125GString * 1126g_string_overwrite (GString *string, 1127 gsize pos, 1128 const gchar *val) 1129{ 1130 g_return_val_if_fail (val != NULL, string); 1131 return g_string_overwrite_len (string, pos, val, strlen (val)); 1132} 1133 1134/** 1135 * g_string_overwrite_len: 1136 * @string: a #GString 1137 * @pos: the position at which to start overwriting 1138 * @val: the string that will overwrite the @string starting at @pos 1139 * @len: the number of bytes to write from @val 1140 * 1141 * Overwrites part of a string, lengthening it if necessary. 1142 * This function will work with embedded nuls. 1143 * 1144 * Return value: @string 1145 * 1146 * Since: 2.14 1147 **/ 1148GString * 1149g_string_overwrite_len (GString *string, 1150 gsize pos, 1151 const gchar *val, 1152 gssize len) 1153{ 1154 gsize end; 1155 1156 g_return_val_if_fail (string != NULL, NULL); 1157 1158 if (!len) 1159 return string; 1160 1161 g_return_val_if_fail (val != NULL, string); 1162 g_return_val_if_fail (pos <= string->len, string); 1163 1164 if (len < 0) 1165 len = strlen (val); 1166 1167 end = pos + len; 1168 1169 if (end > string->len) 1170 g_string_maybe_expand (string, end - string->len); 1171 1172 memcpy (string->str + pos, val, len); 1173 1174 if (end > string->len) 1175 { 1176 string->str[end] = '\0'; 1177 string->len = end; 1178 } 1179 1180 return string; 1181} 1182 1183/** 1184 * g_string_erase: 1185 * @string: a #GString 1186 * @pos: the position of the content to remove 1187 * @len: the number of bytes to remove, or -1 to remove all 1188 * following bytes 1189 * 1190 * Removes @len bytes from a #GString, starting at position @pos. 1191 * The rest of the #GString is shifted down to fill the gap. 1192 * 1193 * Returns: @string 1194 */ 1195GString* 1196g_string_erase (GString *string, 1197 gssize pos, 1198 gssize len) 1199{ 1200 g_return_val_if_fail (string != NULL, NULL); 1201 g_return_val_if_fail (pos >= 0, string); 1202 g_return_val_if_fail (pos <= string->len, string); 1203 1204 if (len < 0) 1205 len = string->len - pos; 1206 else 1207 { 1208 g_return_val_if_fail (pos + len <= string->len, string); 1209 1210 if (pos + len < string->len) 1211 g_memmove (string->str + pos, string->str + pos + len, string->len - (pos + len)); 1212 } 1213 1214 string->len -= len; 1215 1216 string->str[string->len] = 0; 1217 1218 return string; 1219} 1220 1221/** 1222 * g_string_ascii_down: 1223 * @string: a GString 1224 * 1225 * Converts all upper case ASCII letters to lower case ASCII letters. 1226 * 1227 * Return value: passed-in @string pointer, with all the upper case 1228 * characters converted to lower case in place, with 1229 * semantics that exactly match g_ascii_tolower(). 1230 **/ 1231GString* 1232g_string_ascii_down (GString *string) 1233{ 1234 gchar *s; 1235 gint n; 1236 1237 g_return_val_if_fail (string != NULL, NULL); 1238 1239 n = string->len; 1240 s = string->str; 1241 1242 while (n) 1243 { 1244 *s = g_ascii_tolower (*s); 1245 s++; 1246 n--; 1247 } 1248 1249 return string; 1250} 1251 1252/** 1253 * g_string_ascii_up: 1254 * @string: a GString 1255 * 1256 * Converts all lower case ASCII letters to upper case ASCII letters. 1257 * 1258 * Return value: passed-in @string pointer, with all the lower case 1259 * characters converted to upper case in place, with 1260 * semantics that exactly match g_ascii_toupper(). 1261 **/ 1262GString* 1263g_string_ascii_up (GString *string) 1264{ 1265 gchar *s; 1266 gint n; 1267 1268 g_return_val_if_fail (string != NULL, NULL); 1269 1270 n = string->len; 1271 s = string->str; 1272 1273 while (n) 1274 { 1275 *s = g_ascii_toupper (*s); 1276 s++; 1277 n--; 1278 } 1279 1280 return string; 1281} 1282 1283/** 1284 * g_string_down: 1285 * @string: a #GString 1286 * 1287 * Converts a #GString to lowercase. 1288 * 1289 * Returns: the #GString. 1290 * 1291 * Deprecated:2.2: This function uses the locale-specific 1292 * tolower() function, which is almost never the right thing. 1293 * Use g_string_ascii_down() or g_utf8_strdown() instead. 1294 */ 1295GString* 1296g_string_down (GString *string) 1297{ 1298 guchar *s; 1299 glong n; 1300 1301 g_return_val_if_fail (string != NULL, NULL); 1302 1303 n = string->len; 1304 s = (guchar *) string->str; 1305 1306 while (n) 1307 { 1308 if (isupper (*s)) 1309 *s = tolower (*s); 1310 s++; 1311 n--; 1312 } 1313 1314 return string; 1315} 1316 1317/** 1318 * g_string_up: 1319 * @string: a #GString 1320 * 1321 * Converts a #GString to uppercase. 1322 * 1323 * Return value: @string 1324 * 1325 * Deprecated:2.2: This function uses the locale-specific 1326 * toupper() function, which is almost never the right thing. 1327 * Use g_string_ascii_up() or g_utf8_strup() instead. 1328 **/ 1329GString* 1330g_string_up (GString *string) 1331{ 1332 guchar *s; 1333 glong n; 1334 1335 g_return_val_if_fail (string != NULL, NULL); 1336 1337 n = string->len; 1338 s = (guchar *) string->str; 1339 1340 while (n) 1341 { 1342 if (islower (*s)) 1343 *s = toupper (*s); 1344 s++; 1345 n--; 1346 } 1347 1348 return string; 1349} 1350 1351/** 1352 * g_string_append_vprintf: 1353 * @string: a #GString 1354 * @format: the string format. See the printf() documentation 1355 * @args: the list of arguments to insert in the output 1356 * 1357 * Appends a formatted string onto the end of a #GString. 1358 * This function is similar to g_string_append_printf() 1359 * except that the arguments to the format string are passed 1360 * as a va_list. 1361 * 1362 * Since: 2.14 1363 */ 1364void 1365g_string_append_vprintf (GString *string, 1366 const gchar *format, 1367 va_list args) 1368{ 1369 gchar *buf; 1370 gint len; 1371 1372 g_return_if_fail (string != NULL); 1373 g_return_if_fail (format != NULL); 1374 1375 len = g_vasprintf (&buf, format, args); 1376 1377 if (len >= 0) 1378 { 1379 g_string_maybe_expand (string, len); 1380 memcpy (string->str + string->len, buf, len + 1); 1381 string->len += len; 1382 g_free (buf); 1383 } 1384} 1385 1386/** 1387 * g_string_vprintf: 1388 * @string: a #GString 1389 * @format: the string format. See the printf() documentation 1390 * @args: the parameters to insert into the format string 1391 * 1392 * Writes a formatted string into a #GString. 1393 * This function is similar to g_string_printf() except that 1394 * the arguments to the format string are passed as a va_list. 1395 * 1396 * Since: 2.14 1397 */ 1398void 1399g_string_vprintf (GString *string, 1400 const gchar *format, 1401 va_list args) 1402{ 1403 g_string_truncate (string, 0); 1404 g_string_append_vprintf (string, format, args); 1405} 1406 1407/** 1408 * g_string_sprintf: 1409 * @string: a #GString 1410 * @format: the string format. See the sprintf() documentation 1411 * @Varargs: the parameters to insert into the format string 1412 * 1413 * Writes a formatted string into a #GString. 1414 * This is similar to the standard sprintf() function, 1415 * except that the #GString buffer automatically expands 1416 * to contain the results. The previous contents of the 1417 * #GString are destroyed. 1418 * 1419 * Deprecated: This function has been renamed to g_string_printf(). 1420 */ 1421 1422/** 1423 * g_string_printf: 1424 * @string: a #GString 1425 * @format: the string format. See the printf() documentation 1426 * @Varargs: the parameters to insert into the format string 1427 * 1428 * Writes a formatted string into a #GString. 1429 * This is similar to the standard sprintf() function, 1430 * except that the #GString buffer automatically expands 1431 * to contain the results. The previous contents of the 1432 * #GString are destroyed. 1433 */ 1434void 1435g_string_printf (GString *string, 1436 const gchar *format, 1437 ...) 1438{ 1439 va_list args; 1440 1441 g_string_truncate (string, 0); 1442 1443 va_start (args, format); 1444 g_string_append_vprintf (string, format, args); 1445 va_end (args); 1446} 1447 1448/** 1449 * g_string_sprintfa: 1450 * @string: a #GString 1451 * @format: the string format. See the sprintf() documentation 1452 * @Varargs: the parameters to insert into the format string 1453 * 1454 * Appends a formatted string onto the end of a #GString. 1455 * This function is similar to g_string_sprintf() except that 1456 * the text is appended to the #GString. 1457 * 1458 * Deprecated: This function has been renamed to g_string_append_printf() 1459 */ 1460 1461/** 1462 * g_string_append_printf: 1463 * @string: a #GString 1464 * @format: the string format. See the printf() documentation 1465 * @Varargs: the parameters to insert into the format string 1466 * 1467 * Appends a formatted string onto the end of a #GString. 1468 * This function is similar to g_string_printf() except 1469 * that the text is appended to the #GString. 1470 */ 1471void 1472g_string_append_printf (GString *string, 1473 const gchar *format, 1474 ...) 1475{ 1476 va_list args; 1477 1478 va_start (args, format); 1479 g_string_append_vprintf (string, format, args); 1480 va_end (args); 1481} 1482 1483#define __G_STRING_C__ 1484#include "galiasdef.c" 1485