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.1 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 */
17
18/*
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
23 */
24
25/*
26 * MT safe
27 */
28
29#include "config.h"
30
31#include <stdarg.h>
32#include <stdlib.h>
33#include <stdio.h>
34#include <string.h>
35#include <ctype.h>
36
37#include "gstring.h"
38#include "guriprivate.h"
39#include "gprintf.h"
40
41
42/**
43 * SECTION:strings
44 * @title: Strings
45 * @short_description: text buffers which grow automatically
46 * as text is added
47 *
48 * A #GString is an object that handles the memory management of a C
49 * string for you. The emphasis of #GString is on text, typically
50 * UTF-8. Crucially, the "str" member of a #GString is guaranteed to
51 * have a trailing nul character, and it is therefore always safe to
52 * call functions such as strchr() or g_strdup() on it.
53 *
54 * However, a #GString can also hold arbitrary binary data, because it
55 * has a "len" member, which includes any possible embedded nul
56 * characters in the data. Conceptually then, #GString is like a
57 * #GByteArray with the addition of many convenience methods for text,
58 * and a guaranteed nul terminator.
59 */
60
61/**
62 * GString:
63 * @str: points to the character data. It may move as text is added.
64 * The @str field is null-terminated and so
65 * can be used as an ordinary C string.
66 * @len: contains the length of the string, not including the
67 * terminating nul byte.
68 * @allocated_len: the number of bytes that can be stored in the
69 * string before it needs to be reallocated. May be larger than @len.
70 *
71 * The GString struct contains the public fields of a GString.
72 */
73
74
75#define MY_MAXSIZE ((gsize)-1)
76
77static inline gsize
78nearest_power (gsize base, gsize num)
79{
80 if (num > MY_MAXSIZE / 2)
81 {
82 return MY_MAXSIZE;
83 }
84 else
85 {
86 gsize n = base;
87
88 while (n < num)
89 n <<= 1;
90
91 return n;
92 }
93}
94
95static void
96g_string_maybe_expand (GString *string,
97 gsize len)
98{
99 if (string->len + len >= string->allocated_len)
100 {
101 string->allocated_len = nearest_power (base: 1, num: string->len + len + 1);
102 string->str = g_realloc (mem: string->str, n_bytes: string->allocated_len);
103 }
104}
105
106/**
107 * g_string_sized_new:
108 * @dfl_size: the default size of the space allocated to
109 * hold the string
110 *
111 * Creates a new #GString, with enough space for @dfl_size
112 * bytes. This is useful if you are going to add a lot of
113 * text to the string and don't want it to be reallocated
114 * too often.
115 *
116 * Returns: the new #GString
117 */
118GString *
119g_string_sized_new (gsize dfl_size)
120{
121 GString *string = g_slice_new (GString);
122
123 string->allocated_len = 0;
124 string->len = 0;
125 string->str = NULL;
126
127 g_string_maybe_expand (string, MAX (dfl_size, 2));
128 string->str[0] = 0;
129
130 return string;
131}
132
133/**
134 * g_string_new:
135 * @init: (nullable): the initial text to copy into the string, or %NULL to
136 * start with an empty string
137 *
138 * Creates a new #GString, initialized with the given string.
139 *
140 * Returns: the new #GString
141 */
142GString *
143g_string_new (const gchar *init)
144{
145 GString *string;
146
147 if (init == NULL || *init == '\0')
148 string = g_string_sized_new (dfl_size: 2);
149 else
150 {
151 gint len;
152
153 len = strlen (s: init);
154 string = g_string_sized_new (dfl_size: len + 2);
155
156 g_string_append_len (string, val: init, len);
157 }
158
159 return string;
160}
161
162/**
163 * g_string_new_len:
164 * @init: initial contents of the string
165 * @len: length of @init to use
166 *
167 * Creates a new #GString with @len bytes of the @init buffer.
168 * Because a length is provided, @init need not be nul-terminated,
169 * and can contain embedded nul bytes.
170 *
171 * Since this function does not stop at nul bytes, it is the caller's
172 * responsibility to ensure that @init has at least @len addressable
173 * bytes.
174 *
175 * Returns: a new #GString
176 */
177GString *
178g_string_new_len (const gchar *init,
179 gssize len)
180{
181 GString *string;
182
183 if (len < 0)
184 return g_string_new (init);
185 else
186 {
187 string = g_string_sized_new (dfl_size: len);
188
189 if (init)
190 g_string_append_len (string, val: init, len);
191
192 return string;
193 }
194}
195
196/**
197 * g_string_free:
198 * @string: (transfer full): a #GString
199 * @free_segment: if %TRUE, the actual character data is freed as well
200 *
201 * Frees the memory allocated for the #GString.
202 * If @free_segment is %TRUE it also frees the character data. If
203 * it's %FALSE, the caller gains ownership of the buffer and must
204 * free it after use with g_free().
205 *
206 * Returns: (nullable): the character data of @string
207 * (i.e. %NULL if @free_segment is %TRUE)
208 */
209gchar *
210g_string_free (GString *string,
211 gboolean free_segment)
212{
213 gchar *segment;
214
215 g_return_val_if_fail (string != NULL, NULL);
216
217 if (free_segment)
218 {
219 g_free (mem: string->str);
220 segment = NULL;
221 }
222 else
223 segment = string->str;
224
225 g_slice_free (GString, string);
226
227 return segment;
228}
229
230/**
231 * g_string_free_to_bytes:
232 * @string: (transfer full): a #GString
233 *
234 * Transfers ownership of the contents of @string to a newly allocated
235 * #GBytes. The #GString structure itself is deallocated, and it is
236 * therefore invalid to use @string after invoking this function.
237 *
238 * Note that while #GString ensures that its buffer always has a
239 * trailing nul character (not reflected in its "len"), the returned
240 * #GBytes does not include this extra nul; i.e. it has length exactly
241 * equal to the "len" member.
242 *
243 * Returns: (transfer full): A newly allocated #GBytes containing contents of @string; @string itself is freed
244 * Since: 2.34
245 */
246GBytes*
247g_string_free_to_bytes (GString *string)
248{
249 gsize len;
250 gchar *buf;
251
252 g_return_val_if_fail (string != NULL, NULL);
253
254 len = string->len;
255
256 buf = g_string_free (string, FALSE);
257
258 return g_bytes_new_take (data: buf, size: len);
259}
260
261/**
262 * g_string_equal:
263 * @v: a #GString
264 * @v2: another #GString
265 *
266 * Compares two strings for equality, returning %TRUE if they are equal.
267 * For use with #GHashTable.
268 *
269 * Returns: %TRUE if the strings are the same length and contain the
270 * same bytes
271 */
272gboolean
273g_string_equal (const GString *v,
274 const GString *v2)
275{
276 gchar *p, *q;
277 GString *string1 = (GString *) v;
278 GString *string2 = (GString *) v2;
279 gsize i = string1->len;
280
281 if (i != string2->len)
282 return FALSE;
283
284 p = string1->str;
285 q = string2->str;
286 while (i)
287 {
288 if (*p != *q)
289 return FALSE;
290 p++;
291 q++;
292 i--;
293 }
294 return TRUE;
295}
296
297/**
298 * g_string_hash:
299 * @str: a string to hash
300 *
301 * Creates a hash code for @str; for use with #GHashTable.
302 *
303 * Returns: hash code for @str
304 */
305guint
306g_string_hash (const GString *str)
307{
308 const gchar *p = str->str;
309 gsize n = str->len;
310 guint h = 0;
311
312 /* 31 bit hash function */
313 while (n--)
314 {
315 h = (h << 5) - h + *p;
316 p++;
317 }
318
319 return h;
320}
321
322/**
323 * g_string_assign:
324 * @string: the destination #GString. Its current contents
325 * are destroyed.
326 * @rval: the string to copy into @string
327 *
328 * Copies the bytes from a string into a #GString,
329 * destroying any previous contents. It is rather like
330 * the standard strcpy() function, except that you do not
331 * have to worry about having enough space to copy the string.
332 *
333 * Returns: (transfer none): @string
334 */
335GString *
336g_string_assign (GString *string,
337 const gchar *rval)
338{
339 g_return_val_if_fail (string != NULL, NULL);
340 g_return_val_if_fail (rval != NULL, string);
341
342 /* Make sure assigning to itself doesn't corrupt the string. */
343 if (string->str != rval)
344 {
345 /* Assigning from substring should be ok, since
346 * g_string_truncate() does not reallocate.
347 */
348 g_string_truncate (string, len: 0);
349 g_string_append (string, val: rval);
350 }
351
352 return string;
353}
354
355/**
356 * g_string_truncate:
357 * @string: a #GString
358 * @len: the new size of @string
359 *
360 * Cuts off the end of the GString, leaving the first @len bytes.
361 *
362 * Returns: (transfer none): @string
363 */
364GString *
365g_string_truncate (GString *string,
366 gsize len)
367{
368 g_return_val_if_fail (string != NULL, NULL);
369
370 string->len = MIN (len, string->len);
371 string->str[string->len] = 0;
372
373 return string;
374}
375
376/**
377 * g_string_set_size:
378 * @string: a #GString
379 * @len: the new length
380 *
381 * Sets the length of a #GString. If the length is less than
382 * the current length, the string will be truncated. If the
383 * length is greater than the current length, the contents
384 * of the newly added area are undefined. (However, as
385 * always, string->str[string->len] will be a nul byte.)
386 *
387 * Returns: (transfer none): @string
388 */
389GString *
390g_string_set_size (GString *string,
391 gsize len)
392{
393 g_return_val_if_fail (string != NULL, NULL);
394
395 if (len >= string->allocated_len)
396 g_string_maybe_expand (string, len: len - string->len);
397
398 string->len = len;
399 string->str[len] = 0;
400
401 return string;
402}
403
404/**
405 * g_string_insert_len:
406 * @string: a #GString
407 * @pos: position in @string where insertion should
408 * happen, or -1 for at the end
409 * @val: bytes to insert
410 * @len: number of bytes of @val to insert, or -1 for all of @val
411 *
412 * Inserts @len bytes of @val into @string at @pos.
413 *
414 * If @len is positive, @val may contain embedded nuls and need
415 * not be nul-terminated. It is the caller's responsibility to
416 * ensure that @val has at least @len addressable bytes.
417 *
418 * If @len is negative, @val must be nul-terminated and @len
419 * is considered to request the entire string length.
420 *
421 * If @pos is -1, bytes are inserted at the end of the string.
422 *
423 * Returns: (transfer none): @string
424 */
425GString *
426g_string_insert_len (GString *string,
427 gssize pos,
428 const gchar *val,
429 gssize len)
430{
431 gsize len_unsigned, pos_unsigned;
432
433 g_return_val_if_fail (string != NULL, NULL);
434 g_return_val_if_fail (len == 0 || val != NULL, string);
435
436 if (len == 0)
437 return string;
438
439 if (len < 0)
440 len = strlen (s: val);
441 len_unsigned = len;
442
443 if (pos < 0)
444 pos_unsigned = string->len;
445 else
446 {
447 pos_unsigned = pos;
448 g_return_val_if_fail (pos_unsigned <= string->len, string);
449 }
450
451 /* Check whether val represents a substring of string.
452 * This test probably violates chapter and verse of the C standards,
453 * since ">=" and "<=" are only valid when val really is a substring.
454 * In practice, it will work on modern archs.
455 */
456 if (G_UNLIKELY (val >= string->str && val <= string->str + string->len))
457 {
458 gsize offset = val - string->str;
459 gsize precount = 0;
460
461 g_string_maybe_expand (string, len: len_unsigned);
462 val = string->str + offset;
463 /* At this point, val is valid again. */
464
465 /* Open up space where we are going to insert. */
466 if (pos_unsigned < string->len)
467 memmove (dest: string->str + pos_unsigned + len_unsigned,
468 src: string->str + pos_unsigned, n: string->len - pos_unsigned);
469
470 /* Move the source part before the gap, if any. */
471 if (offset < pos_unsigned)
472 {
473 precount = MIN (len_unsigned, pos_unsigned - offset);
474 memcpy (dest: string->str + pos_unsigned, src: val, n: precount);
475 }
476
477 /* Move the source part after the gap, if any. */
478 if (len_unsigned > precount)
479 memcpy (dest: string->str + pos_unsigned + precount,
480 src: val + /* Already moved: */ precount +
481 /* Space opened up: */ len_unsigned,
482 n: len_unsigned - precount);
483 }
484 else
485 {
486 g_string_maybe_expand (string, len: len_unsigned);
487
488 /* If we aren't appending at the end, move a hunk
489 * of the old string to the end, opening up space
490 */
491 if (pos_unsigned < string->len)
492 memmove (dest: string->str + pos_unsigned + len_unsigned,
493 src: string->str + pos_unsigned, n: string->len - pos_unsigned);
494
495 /* insert the new string */
496 if (len_unsigned == 1)
497 string->str[pos_unsigned] = *val;
498 else
499 memcpy (dest: string->str + pos_unsigned, src: val, n: len_unsigned);
500 }
501
502 string->len += len_unsigned;
503
504 string->str[string->len] = 0;
505
506 return string;
507}
508
509/**
510 * g_string_append_uri_escaped:
511 * @string: a #GString
512 * @unescaped: a string
513 * @reserved_chars_allowed: a string of reserved characters allowed
514 * to be used, or %NULL
515 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
516 *
517 * Appends @unescaped to @string, escaping any characters that
518 * are reserved in URIs using URI-style escape sequences.
519 *
520 * Returns: (transfer none): @string
521 *
522 * Since: 2.16
523 */
524GString *
525g_string_append_uri_escaped (GString *string,
526 const gchar *unescaped,
527 const gchar *reserved_chars_allowed,
528 gboolean allow_utf8)
529{
530 _uri_encoder (out: string, start: (const guchar *) unescaped, length: strlen (s: unescaped),
531 reserved_chars_allowed, allow_utf8);
532 return string;
533}
534
535/**
536 * g_string_append:
537 * @string: a #GString
538 * @val: the string to append onto the end of @string
539 *
540 * Adds a string onto the end of a #GString, expanding
541 * it if necessary.
542 *
543 * Returns: (transfer none): @string
544 */
545GString *
546g_string_append (GString *string,
547 const gchar *val)
548{
549 return g_string_insert_len (string, pos: -1, val, len: -1);
550}
551
552/**
553 * g_string_append_len:
554 * @string: a #GString
555 * @val: bytes to append
556 * @len: number of bytes of @val to use, or -1 for all of @val
557 *
558 * Appends @len bytes of @val to @string.
559 *
560 * If @len is positive, @val may contain embedded nuls and need
561 * not be nul-terminated. It is the caller's responsibility to
562 * ensure that @val has at least @len addressable bytes.
563 *
564 * If @len is negative, @val must be nul-terminated and @len
565 * is considered to request the entire string length. This
566 * makes g_string_append_len() equivalent to g_string_append().
567 *
568 * Returns: (transfer none): @string
569 */
570GString *
571g_string_append_len (GString *string,
572 const gchar *val,
573 gssize len)
574{
575 return g_string_insert_len (string, pos: -1, val, len);
576}
577
578/**
579 * g_string_append_c:
580 * @string: a #GString
581 * @c: the byte to append onto the end of @string
582 *
583 * Adds a byte onto the end of a #GString, expanding
584 * it if necessary.
585 *
586 * Returns: (transfer none): @string
587 */
588#undef g_string_append_c
589GString *
590g_string_append_c (GString *string,
591 gchar c)
592{
593 g_return_val_if_fail (string != NULL, NULL);
594
595 return g_string_insert_c (string, pos: -1, c);
596}
597
598/**
599 * g_string_append_unichar:
600 * @string: a #GString
601 * @wc: a Unicode character
602 *
603 * Converts a Unicode character into UTF-8, and appends it
604 * to the string.
605 *
606 * Returns: (transfer none): @string
607 */
608GString *
609g_string_append_unichar (GString *string,
610 gunichar wc)
611{
612 g_return_val_if_fail (string != NULL, NULL);
613
614 return g_string_insert_unichar (string, pos: -1, wc);
615}
616
617/**
618 * g_string_prepend:
619 * @string: a #GString
620 * @val: the string to prepend on the start of @string
621 *
622 * Adds a string on to the start of a #GString,
623 * expanding it if necessary.
624 *
625 * Returns: (transfer none): @string
626 */
627GString *
628g_string_prepend (GString *string,
629 const gchar *val)
630{
631 return g_string_insert_len (string, pos: 0, val, len: -1);
632}
633
634/**
635 * g_string_prepend_len:
636 * @string: a #GString
637 * @val: bytes to prepend
638 * @len: number of bytes in @val to prepend, or -1 for all of @val
639 *
640 * Prepends @len bytes of @val to @string.
641 *
642 * If @len is positive, @val may contain embedded nuls and need
643 * not be nul-terminated. It is the caller's responsibility to
644 * ensure that @val has at least @len addressable bytes.
645 *
646 * If @len is negative, @val must be nul-terminated and @len
647 * is considered to request the entire string length. This
648 * makes g_string_prepend_len() equivalent to g_string_prepend().
649 *
650 * Returns: (transfer none): @string
651 */
652GString *
653g_string_prepend_len (GString *string,
654 const gchar *val,
655 gssize len)
656{
657 return g_string_insert_len (string, pos: 0, val, len);
658}
659
660/**
661 * g_string_prepend_c:
662 * @string: a #GString
663 * @c: the byte to prepend on the start of the #GString
664 *
665 * Adds a byte onto the start of a #GString,
666 * expanding it if necessary.
667 *
668 * Returns: (transfer none): @string
669 */
670GString *
671g_string_prepend_c (GString *string,
672 gchar c)
673{
674 g_return_val_if_fail (string != NULL, NULL);
675
676 return g_string_insert_c (string, pos: 0, c);
677}
678
679/**
680 * g_string_prepend_unichar:
681 * @string: a #GString
682 * @wc: a Unicode character
683 *
684 * Converts a Unicode character into UTF-8, and prepends it
685 * to the string.
686 *
687 * Returns: (transfer none): @string
688 */
689GString *
690g_string_prepend_unichar (GString *string,
691 gunichar wc)
692{
693 g_return_val_if_fail (string != NULL, NULL);
694
695 return g_string_insert_unichar (string, pos: 0, wc);
696}
697
698/**
699 * g_string_insert:
700 * @string: a #GString
701 * @pos: the position to insert the copy of the string
702 * @val: the string to insert
703 *
704 * Inserts a copy of a string into a #GString,
705 * expanding it if necessary.
706 *
707 * Returns: (transfer none): @string
708 */
709GString *
710g_string_insert (GString *string,
711 gssize pos,
712 const gchar *val)
713{
714 return g_string_insert_len (string, pos, val, len: -1);
715}
716
717/**
718 * g_string_insert_c:
719 * @string: a #GString
720 * @pos: the position to insert the byte
721 * @c: the byte to insert
722 *
723 * Inserts a byte into a #GString, expanding it if necessary.
724 *
725 * Returns: (transfer none): @string
726 */
727GString *
728g_string_insert_c (GString *string,
729 gssize pos,
730 gchar c)
731{
732 gsize pos_unsigned;
733
734 g_return_val_if_fail (string != NULL, NULL);
735
736 g_string_maybe_expand (string, len: 1);
737
738 if (pos < 0)
739 pos = string->len;
740 else
741 g_return_val_if_fail ((gsize) pos <= string->len, string);
742 pos_unsigned = pos;
743
744 /* If not just an append, move the old stuff */
745 if (pos_unsigned < string->len)
746 memmove (dest: string->str + pos_unsigned + 1,
747 src: string->str + pos_unsigned, n: string->len - pos_unsigned);
748
749 string->str[pos_unsigned] = c;
750
751 string->len += 1;
752
753 string->str[string->len] = 0;
754
755 return string;
756}
757
758/**
759 * g_string_insert_unichar:
760 * @string: a #GString
761 * @pos: the position at which to insert character, or -1
762 * to append at the end of the string
763 * @wc: a Unicode character
764 *
765 * Converts a Unicode character into UTF-8, and insert it
766 * into the string at the given position.
767 *
768 * Returns: (transfer none): @string
769 */
770GString *
771g_string_insert_unichar (GString *string,
772 gssize pos,
773 gunichar wc)
774{
775 gint charlen, first, i;
776 gchar *dest;
777
778 g_return_val_if_fail (string != NULL, NULL);
779
780 /* Code copied from g_unichar_to_utf() */
781 if (wc < 0x80)
782 {
783 first = 0;
784 charlen = 1;
785 }
786 else if (wc < 0x800)
787 {
788 first = 0xc0;
789 charlen = 2;
790 }
791 else if (wc < 0x10000)
792 {
793 first = 0xe0;
794 charlen = 3;
795 }
796 else if (wc < 0x200000)
797 {
798 first = 0xf0;
799 charlen = 4;
800 }
801 else if (wc < 0x4000000)
802 {
803 first = 0xf8;
804 charlen = 5;
805 }
806 else
807 {
808 first = 0xfc;
809 charlen = 6;
810 }
811 /* End of copied code */
812
813 g_string_maybe_expand (string, len: charlen);
814
815 if (pos < 0)
816 pos = string->len;
817 else
818 g_return_val_if_fail ((gsize) pos <= string->len, string);
819
820 /* If not just an append, move the old stuff */
821 if ((gsize) pos < string->len)
822 memmove (dest: string->str + pos + charlen, src: string->str + pos, n: string->len - pos);
823
824 dest = string->str + pos;
825 /* Code copied from g_unichar_to_utf() */
826 for (i = charlen - 1; i > 0; --i)
827 {
828 dest[i] = (wc & 0x3f) | 0x80;
829 wc >>= 6;
830 }
831 dest[0] = wc | first;
832 /* End of copied code */
833
834 string->len += charlen;
835
836 string->str[string->len] = 0;
837
838 return string;
839}
840
841/**
842 * g_string_overwrite:
843 * @string: a #GString
844 * @pos: the position at which to start overwriting
845 * @val: the string that will overwrite the @string starting at @pos
846 *
847 * Overwrites part of a string, lengthening it if necessary.
848 *
849 * Returns: (transfer none): @string
850 *
851 * Since: 2.14
852 */
853GString *
854g_string_overwrite (GString *string,
855 gsize pos,
856 const gchar *val)
857{
858 g_return_val_if_fail (val != NULL, string);
859 return g_string_overwrite_len (string, pos, val, len: strlen (s: val));
860}
861
862/**
863 * g_string_overwrite_len:
864 * @string: a #GString
865 * @pos: the position at which to start overwriting
866 * @val: the string that will overwrite the @string starting at @pos
867 * @len: the number of bytes to write from @val
868 *
869 * Overwrites part of a string, lengthening it if necessary.
870 * This function will work with embedded nuls.
871 *
872 * Returns: (transfer none): @string
873 *
874 * Since: 2.14
875 */
876GString *
877g_string_overwrite_len (GString *string,
878 gsize pos,
879 const gchar *val,
880 gssize len)
881{
882 gsize end;
883
884 g_return_val_if_fail (string != NULL, NULL);
885
886 if (!len)
887 return string;
888
889 g_return_val_if_fail (val != NULL, string);
890 g_return_val_if_fail (pos <= string->len, string);
891
892 if (len < 0)
893 len = strlen (s: val);
894
895 end = pos + len;
896
897 if (end > string->len)
898 g_string_maybe_expand (string, len: end - string->len);
899
900 memcpy (dest: string->str + pos, src: val, n: len);
901
902 if (end > string->len)
903 {
904 string->str[end] = '\0';
905 string->len = end;
906 }
907
908 return string;
909}
910
911/**
912 * g_string_erase:
913 * @string: a #GString
914 * @pos: the position of the content to remove
915 * @len: the number of bytes to remove, or -1 to remove all
916 * following bytes
917 *
918 * Removes @len bytes from a #GString, starting at position @pos.
919 * The rest of the #GString is shifted down to fill the gap.
920 *
921 * Returns: (transfer none): @string
922 */
923GString *
924g_string_erase (GString *string,
925 gssize pos,
926 gssize len)
927{
928 gsize len_unsigned, pos_unsigned;
929
930 g_return_val_if_fail (string != NULL, NULL);
931 g_return_val_if_fail (pos >= 0, string);
932 pos_unsigned = pos;
933
934 g_return_val_if_fail (pos_unsigned <= string->len, string);
935
936 if (len < 0)
937 len_unsigned = string->len - pos_unsigned;
938 else
939 {
940 len_unsigned = len;
941 g_return_val_if_fail (pos_unsigned + len_unsigned <= string->len, string);
942
943 if (pos_unsigned + len_unsigned < string->len)
944 memmove (dest: string->str + pos_unsigned,
945 src: string->str + pos_unsigned + len_unsigned,
946 n: string->len - (pos_unsigned + len_unsigned));
947 }
948
949 string->len -= len_unsigned;
950
951 string->str[string->len] = 0;
952
953 return string;
954}
955
956/**
957 * g_string_replace:
958 * @string: a #GString
959 * @find: the string to find in @string
960 * @replace: the string to insert in place of @find
961 * @limit: the maximum instances of @find to replace with @replace, or `0` for
962 * no limit
963 *
964 * Replaces the string @find with the string @replace in a #GString up to
965 * @limit times. If the number of instances of @find in the #GString is
966 * less than @limit, all instances are replaced. If the number of
967 * instances is `0`, all instances of @find are replaced.
968 *
969 * If @find is the empty string, since versions 2.69.1 and 2.68.4 the
970 * replacement will be inserted no more than once per possible position
971 * (beginning of string, end of string and between characters). This did
972 * not work correctly in earlier versions.
973 *
974 * Returns: the number of find and replace operations performed.
975 *
976 * Since: 2.68
977 */
978guint
979g_string_replace (GString *string,
980 const gchar *find,
981 const gchar *replace,
982 guint limit)
983{
984 gsize f_len, r_len, pos;
985 gchar *cur, *next;
986 gint n = 0;
987
988 g_return_val_if_fail (string != NULL, 0);
989 g_return_val_if_fail (find != NULL, 0);
990 g_return_val_if_fail (replace != NULL, 0);
991
992 f_len = strlen (s: find);
993 r_len = strlen (s: replace);
994 cur = string->str;
995
996 while ((next = strstr (haystack: cur, needle: find)) != NULL)
997 {
998 pos = next - string->str;
999 g_string_erase (string, pos, len: f_len);
1000 g_string_insert (string, pos, val: replace);
1001 cur = string->str + pos + r_len;
1002 n++;
1003 /* Only match the empty string once at any given position, to
1004 * avoid infinite loops */
1005 if (f_len == 0)
1006 {
1007 if (cur[0] == '\0')
1008 break;
1009 else
1010 cur++;
1011 }
1012 if (n == limit)
1013 break;
1014 }
1015
1016 return n;
1017}
1018
1019/**
1020 * g_string_ascii_down:
1021 * @string: a GString
1022 *
1023 * Converts all uppercase ASCII letters to lowercase ASCII letters.
1024 *
1025 * Returns: (transfer none): passed-in @string pointer, with all the
1026 * uppercase characters converted to lowercase in place,
1027 * with semantics that exactly match g_ascii_tolower().
1028 */
1029GString *
1030g_string_ascii_down (GString *string)
1031{
1032 gchar *s;
1033 gint n;
1034
1035 g_return_val_if_fail (string != NULL, NULL);
1036
1037 n = string->len;
1038 s = string->str;
1039
1040 while (n)
1041 {
1042 *s = g_ascii_tolower (c: *s);
1043 s++;
1044 n--;
1045 }
1046
1047 return string;
1048}
1049
1050/**
1051 * g_string_ascii_up:
1052 * @string: a GString
1053 *
1054 * Converts all lowercase ASCII letters to uppercase ASCII letters.
1055 *
1056 * Returns: (transfer none): passed-in @string pointer, with all the
1057 * lowercase characters converted to uppercase in place,
1058 * with semantics that exactly match g_ascii_toupper().
1059 */
1060GString *
1061g_string_ascii_up (GString *string)
1062{
1063 gchar *s;
1064 gint n;
1065
1066 g_return_val_if_fail (string != NULL, NULL);
1067
1068 n = string->len;
1069 s = string->str;
1070
1071 while (n)
1072 {
1073 *s = g_ascii_toupper (c: *s);
1074 s++;
1075 n--;
1076 }
1077
1078 return string;
1079}
1080
1081/**
1082 * g_string_down:
1083 * @string: a #GString
1084 *
1085 * Converts a #GString to lowercase.
1086 *
1087 * Returns: (transfer none): the #GString
1088 *
1089 * Deprecated:2.2: This function uses the locale-specific
1090 * tolower() function, which is almost never the right thing.
1091 * Use g_string_ascii_down() or g_utf8_strdown() instead.
1092 */
1093GString *
1094g_string_down (GString *string)
1095{
1096 guchar *s;
1097 glong n;
1098
1099 g_return_val_if_fail (string != NULL, NULL);
1100
1101 n = string->len;
1102 s = (guchar *) string->str;
1103
1104 while (n)
1105 {
1106 if (isupper (*s))
1107 *s = tolower (*s);
1108 s++;
1109 n--;
1110 }
1111
1112 return string;
1113}
1114
1115/**
1116 * g_string_up:
1117 * @string: a #GString
1118 *
1119 * Converts a #GString to uppercase.
1120 *
1121 * Returns: (transfer none): @string
1122 *
1123 * Deprecated:2.2: This function uses the locale-specific
1124 * toupper() function, which is almost never the right thing.
1125 * Use g_string_ascii_up() or g_utf8_strup() instead.
1126 */
1127GString *
1128g_string_up (GString *string)
1129{
1130 guchar *s;
1131 glong n;
1132
1133 g_return_val_if_fail (string != NULL, NULL);
1134
1135 n = string->len;
1136 s = (guchar *) string->str;
1137
1138 while (n)
1139 {
1140 if (islower (*s))
1141 *s = toupper (*s);
1142 s++;
1143 n--;
1144 }
1145
1146 return string;
1147}
1148
1149/**
1150 * g_string_append_vprintf:
1151 * @string: a #GString
1152 * @format: (not nullable): the string format. See the printf() documentation
1153 * @args: the list of arguments to insert in the output
1154 *
1155 * Appends a formatted string onto the end of a #GString.
1156 * This function is similar to g_string_append_printf()
1157 * except that the arguments to the format string are passed
1158 * as a va_list.
1159 *
1160 * Since: 2.14
1161 */
1162void
1163g_string_append_vprintf (GString *string,
1164 const gchar *format,
1165 va_list args)
1166{
1167 gchar *buf;
1168 gint len;
1169
1170 g_return_if_fail (string != NULL);
1171 g_return_if_fail (format != NULL);
1172
1173 len = g_vasprintf (string: &buf, format, args);
1174
1175 if (len >= 0)
1176 {
1177 g_string_maybe_expand (string, len);
1178 memcpy (dest: string->str + string->len, src: buf, n: len + 1);
1179 string->len += len;
1180 g_free (mem: buf);
1181 }
1182}
1183
1184/**
1185 * g_string_vprintf:
1186 * @string: a #GString
1187 * @format: (not nullable): the string format. See the printf() documentation
1188 * @args: the parameters to insert into the format string
1189 *
1190 * Writes a formatted string into a #GString.
1191 * This function is similar to g_string_printf() except that
1192 * the arguments to the format string are passed as a va_list.
1193 *
1194 * Since: 2.14
1195 */
1196void
1197g_string_vprintf (GString *string,
1198 const gchar *format,
1199 va_list args)
1200{
1201 g_string_truncate (string, len: 0);
1202 g_string_append_vprintf (string, format, args);
1203}
1204
1205/**
1206 * g_string_sprintf:
1207 * @string: a #GString
1208 * @format: the string format. See the sprintf() documentation
1209 * @...: the parameters to insert into the format string
1210 *
1211 * Writes a formatted string into a #GString.
1212 * This is similar to the standard sprintf() function,
1213 * except that the #GString buffer automatically expands
1214 * to contain the results. The previous contents of the
1215 * #GString are destroyed.
1216 *
1217 * Deprecated: This function has been renamed to g_string_printf().
1218 */
1219
1220/**
1221 * g_string_printf:
1222 * @string: a #GString
1223 * @format: the string format. See the printf() documentation
1224 * @...: the parameters to insert into the format string
1225 *
1226 * Writes a formatted string into a #GString.
1227 * This is similar to the standard sprintf() function,
1228 * except that the #GString buffer automatically expands
1229 * to contain the results. The previous contents of the
1230 * #GString are destroyed.
1231 */
1232void
1233g_string_printf (GString *string,
1234 const gchar *format,
1235 ...)
1236{
1237 va_list args;
1238
1239 g_string_truncate (string, len: 0);
1240
1241 va_start (args, format);
1242 g_string_append_vprintf (string, format, args);
1243 va_end (args);
1244}
1245
1246/**
1247 * g_string_sprintfa:
1248 * @string: a #GString
1249 * @format: the string format. See the sprintf() documentation
1250 * @...: the parameters to insert into the format string
1251 *
1252 * Appends a formatted string onto the end of a #GString.
1253 * This function is similar to g_string_sprintf() except that
1254 * the text is appended to the #GString.
1255 *
1256 * Deprecated: This function has been renamed to g_string_append_printf()
1257 */
1258
1259/**
1260 * g_string_append_printf:
1261 * @string: a #GString
1262 * @format: the string format. See the printf() documentation
1263 * @...: the parameters to insert into the format string
1264 *
1265 * Appends a formatted string onto the end of a #GString.
1266 * This function is similar to g_string_printf() except
1267 * that the text is appended to the #GString.
1268 */
1269void
1270g_string_append_printf (GString *string,
1271 const gchar *format,
1272 ...)
1273{
1274 va_list args;
1275
1276 va_start (args, format);
1277 g_string_append_vprintf (string, format, args);
1278 va_end (args);
1279}
1280

source code of gtk/subprojects/glib/glib/gstring.c