nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 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, 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  
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  
77 static inline gsize
78 nearest_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  
95 static void
96 g_string_maybe_expand (GString *string,
97 gsize len)
98 {
99 if (string->len + len >= string->allocated_len)
100 {
101 string->allocated_len = nearest_power (1, string->len + len + 1);
102 string->str = g_realloc (string->str, 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 */
118 GString *
119 g_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 */
142 GString *
143 g_string_new (const gchar *init)
144 {
145 GString *string;
146  
147 if (init == NULL || *init == '\0')
148 string = g_string_sized_new (2);
149 else
150 {
151 gint len;
152  
153 len = strlen (init);
154 string = g_string_sized_new (len + 2);
155  
156 g_string_append_len (string, 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 */
177 GString *
178 g_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 (len);
188  
189 if (init)
190 g_string_append_len (string, 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 */
209 gchar *
210 g_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 (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 */
246 GBytes*
247 g_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 (buf, 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 */
272 gboolean
273 g_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 */
305 guint
306 g_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 */
335 GString *
336 g_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, 0);
349 g_string_append (string, 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 */
364 GString *
365 g_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 */
389 GString *
390 g_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 - 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
411 *
412 * Inserts @len bytes of @val into @string at @pos.
413 * Because @len is provided, @val may contain embedded
414 * nuls and need not be nul-terminated. If @pos is -1,
415 * bytes are inserted at the end of the string.
416 *
417 * Since this function does not stop at nul bytes, it is
418 * the caller's responsibility to ensure that @val has at
419 * least @len addressable bytes.
420 *
421 * Returns: (transfer none): @string
422 */
423 GString *
424 g_string_insert_len (GString *string,
425 gssize pos,
426 const gchar *val,
427 gssize len)
428 {
429 g_return_val_if_fail (string != NULL, NULL);
430 g_return_val_if_fail (len == 0 || val != NULL, string);
431  
432 if (len == 0)
433 return string;
434  
435 if (len < 0)
436 len = strlen (val);
437  
438 if (pos < 0)
439 pos = string->len;
440 else
441 g_return_val_if_fail (pos <= string->len, string);
442  
443 /* Check whether val represents a substring of string.
444 * This test probably violates chapter and verse of the C standards,
445 * since ">=" and "<=" are only valid when val really is a substring.
446 * In practice, it will work on modern archs.
447 */
448 if (G_UNLIKELY (val >= string->str && val <= string->str + string->len))
449 {
450 gsize offset = val - string->str;
451 gsize precount = 0;
452  
453 g_string_maybe_expand (string, len);
454 val = string->str + offset;
455 /* At this point, val is valid again. */
456  
457 /* Open up space where we are going to insert. */
458 if (pos < string->len)
459 memmove (string->str + pos + len, string->str + pos, string->len - pos);
460  
461 /* Move the source part before the gap, if any. */
462 if (offset < pos)
463 {
464 precount = MIN (len, pos - offset);
465 memcpy (string->str + pos, val, precount);
466 }
467  
468 /* Move the source part after the gap, if any. */
469 if (len > precount)
470 memcpy (string->str + pos + precount,
471 val + /* Already moved: */ precount + /* Space opened up: */ len,
472 len - precount);
473 }
474 else
475 {
476 g_string_maybe_expand (string, len);
477  
478 /* If we aren't appending at the end, move a hunk
479 * of the old string to the end, opening up space
480 */
481 if (pos < string->len)
482 memmove (string->str + pos + len, string->str + pos, string->len - pos);
483  
484 /* insert the new string */
485 if (len == 1)
486 string->str[pos] = *val;
487 else
488 memcpy (string->str + pos, val, len);
489 }
490  
491 string->len += len;
492  
493 string->str[string->len] = 0;
494  
495 return string;
496 }
497  
498 #define SUB_DELIM_CHARS "!$&'()*+,;="
499  
500 static gboolean
501 is_valid (char c,
502 const char *reserved_chars_allowed)
503 {
504 if (g_ascii_isalnum (c) ||
505 c == '-' ||
506 c == '.' ||
507 c == '_' ||
508 c == '~')
509 return TRUE;
510  
511 if (reserved_chars_allowed &&
512 strchr (reserved_chars_allowed, c) != NULL)
513 return TRUE;
514  
515 return FALSE;
516 }
517  
518 static gboolean
519 gunichar_ok (gunichar c)
520 {
521 return
522 (c != (gunichar) -2) &&
523 (c != (gunichar) -1);
524 }
525  
526 /**
527 * g_string_append_uri_escaped:
528 * @string: a #GString
529 * @unescaped: a string
530 * @reserved_chars_allowed: a string of reserved characters allowed
531 * to be used, or %NULL
532 * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters
533 *
534 * Appends @unescaped to @string, escaped any characters that
535 * are reserved in URIs using URI-style escape sequences.
536 *
537 * Returns: (transfer none): @string
538 *
539 * Since: 2.16
540 */
541 GString *
542 g_string_append_uri_escaped (GString *string,
543 const gchar *unescaped,
544 const gchar *reserved_chars_allowed,
545 gboolean allow_utf8)
546 {
547 unsigned char c;
548 const gchar *end;
549 static const gchar hex[16] = "0123456789ABCDEF";
550  
551 g_return_val_if_fail (string != NULL, NULL);
552 g_return_val_if_fail (unescaped != NULL, NULL);
553  
554 end = unescaped + strlen (unescaped);
555  
556 while ((c = *unescaped) != 0)
557 {
558 if (c >= 0x80 && allow_utf8 &&
559 gunichar_ok (g_utf8_get_char_validated (unescaped, end - unescaped)))
560 {
561 int len = g_utf8_skip [c];
562 g_string_append_len (string, unescaped, len);
563 unescaped += len;
564 }
565 else if (is_valid (c, reserved_chars_allowed))
566 {
567 g_string_append_c (string, c);
568 unescaped++;
569 }
570 else
571 {
572 g_string_append_c (string, '%');
573 g_string_append_c (string, hex[((guchar)c) >> 4]);
574 g_string_append_c (string, hex[((guchar)c) & 0xf]);
575 unescaped++;
576 }
577 }
578  
579 return string;
580 }
581  
582 /**
583 * g_string_append:
584 * @string: a #GString
585 * @val: the string to append onto the end of @string
586 *
587 * Adds a string onto the end of a #GString, expanding
588 * it if necessary.
589 *
590 * Returns: (transfer none): @string
591 */
592 GString *
593 g_string_append (GString *string,
594 const gchar *val)
595 {
596 return g_string_insert_len (string, -1, val, -1);
597 }
598  
599 /**
600 * g_string_append_len:
601 * @string: a #GString
602 * @val: bytes to append
603 * @len: number of bytes of @val to use
604 *
605 * Appends @len bytes of @val to @string. Because @len is
606 * provided, @val may contain embedded nuls and need not
607 * be nul-terminated.
608 *
609 * Since this function does not stop at nul bytes, it is
610 * the caller's responsibility to ensure that @val has at
611 * least @len addressable bytes.
612 *
613 * Returns: (transfer none): @string
614 */
615 GString *
616 g_string_append_len (GString *string,
617 const gchar *val,
618 gssize len)
619 {
620 return g_string_insert_len (string, -1, val, len);
621 }
622  
623 /**
624 * g_string_append_c:
625 * @string: a #GString
626 * @c: the byte to append onto the end of @string
627 *
628 * Adds a byte onto the end of a #GString, expanding
629 * it if necessary.
630 *
631 * Returns: (transfer none): @string
632 */
633 #undef g_string_append_c
634 GString *
635 g_string_append_c (GString *string,
636 gchar c)
637 {
638 g_return_val_if_fail (string != NULL, NULL);
639  
640 return g_string_insert_c (string, -1, c);
641 }
642  
643 /**
644 * g_string_append_unichar:
645 * @string: a #GString
646 * @wc: a Unicode character
647 *
648 * Converts a Unicode character into UTF-8, and appends it
649 * to the string.
650 *
651 * Returns: (transfer none): @string
652 */
653 GString *
654 g_string_append_unichar (GString *string,
655 gunichar wc)
656 {
657 g_return_val_if_fail (string != NULL, NULL);
658  
659 return g_string_insert_unichar (string, -1, wc);
660 }
661  
662 /**
663 * g_string_prepend:
664 * @string: a #GString
665 * @val: the string to prepend on the start of @string
666 *
667 * Adds a string on to the start of a #GString,
668 * expanding it if necessary.
669 *
670 * Returns: (transfer none): @string
671 */
672 GString *
673 g_string_prepend (GString *string,
674 const gchar *val)
675 {
676 return g_string_insert_len (string, 0, val, -1);
677 }
678  
679 /**
680 * g_string_prepend_len:
681 * @string: a #GString
682 * @val: bytes to prepend
683 * @len: number of bytes in @val to prepend
684 *
685 * Prepends @len bytes of @val to @string.
686 * Because @len is provided, @val may contain
687 * embedded nuls and need not be nul-terminated.
688 *
689 * Since this function does not stop at nul bytes,
690 * it is the caller's responsibility to ensure that
691 * @val has at least @len addressable bytes.
692 *
693 * Returns: (transfer none): @string
694 */
695 GString *
696 g_string_prepend_len (GString *string,
697 const gchar *val,
698 gssize len)
699 {
700 return g_string_insert_len (string, 0, val, len);
701 }
702  
703 /**
704 * g_string_prepend_c:
705 * @string: a #GString
706 * @c: the byte to prepend on the start of the #GString
707 *
708 * Adds a byte onto the start of a #GString,
709 * expanding it if necessary.
710 *
711 * Returns: (transfer none): @string
712 */
713 GString *
714 g_string_prepend_c (GString *string,
715 gchar c)
716 {
717 g_return_val_if_fail (string != NULL, NULL);
718  
719 return g_string_insert_c (string, 0, c);
720 }
721  
722 /**
723 * g_string_prepend_unichar:
724 * @string: a #GString
725 * @wc: a Unicode character
726 *
727 * Converts a Unicode character into UTF-8, and prepends it
728 * to the string.
729 *
730 * Returns: (transfer none): @string
731 */
732 GString *
733 g_string_prepend_unichar (GString *string,
734 gunichar wc)
735 {
736 g_return_val_if_fail (string != NULL, NULL);
737  
738 return g_string_insert_unichar (string, 0, wc);
739 }
740  
741 /**
742 * g_string_insert:
743 * @string: a #GString
744 * @pos: the position to insert the copy of the string
745 * @val: the string to insert
746 *
747 * Inserts a copy of a string into a #GString,
748 * expanding it if necessary.
749 *
750 * Returns: (transfer none): @string
751 */
752 GString *
753 g_string_insert (GString *string,
754 gssize pos,
755 const gchar *val)
756 {
757 return g_string_insert_len (string, pos, val, -1);
758 }
759  
760 /**
761 * g_string_insert_c:
762 * @string: a #GString
763 * @pos: the position to insert the byte
764 * @c: the byte to insert
765 *
766 * Inserts a byte into a #GString, expanding it if necessary.
767 *
768 * Returns: (transfer none): @string
769 */
770 GString *
771 g_string_insert_c (GString *string,
772 gssize pos,
773 gchar c)
774 {
775 g_return_val_if_fail (string != NULL, NULL);
776  
777 g_string_maybe_expand (string, 1);
778  
779 if (pos < 0)
780 pos = string->len;
781 else
782 g_return_val_if_fail (pos <= string->len, string);
783  
784 /* If not just an append, move the old stuff */
785 if (pos < string->len)
786 memmove (string->str + pos + 1, string->str + pos, string->len - pos);
787  
788 string->str[pos] = c;
789  
790 string->len += 1;
791  
792 string->str[string->len] = 0;
793  
794 return string;
795 }
796  
797 /**
798 * g_string_insert_unichar:
799 * @string: a #GString
800 * @pos: the position at which to insert character, or -1
801 * to append at the end of the string
802 * @wc: a Unicode character
803 *
804 * Converts a Unicode character into UTF-8, and insert it
805 * into the string at the given position.
806 *
807 * Returns: (transfer none): @string
808 */
809 GString *
810 g_string_insert_unichar (GString *string,
811 gssize pos,
812 gunichar wc)
813 {
814 gint charlen, first, i;
815 gchar *dest;
816  
817 g_return_val_if_fail (string != NULL, NULL);
818  
819 /* Code copied from g_unichar_to_utf() */
820 if (wc < 0x80)
821 {
822 first = 0;
823 charlen = 1;
824 }
825 else if (wc < 0x800)
826 {
827 first = 0xc0;
828 charlen = 2;
829 }
830 else if (wc < 0x10000)
831 {
832 first = 0xe0;
833 charlen = 3;
834 }
835 else if (wc < 0x200000)
836 {
837 first = 0xf0;
838 charlen = 4;
839 }
840 else if (wc < 0x4000000)
841 {
842 first = 0xf8;
843 charlen = 5;
844 }
845 else
846 {
847 first = 0xfc;
848 charlen = 6;
849 }
850 /* End of copied code */
851  
852 g_string_maybe_expand (string, charlen);
853  
854 if (pos < 0)
855 pos = string->len;
856 else
857 g_return_val_if_fail (pos <= string->len, string);
858  
859 /* If not just an append, move the old stuff */
860 if (pos < string->len)
861 memmove (string->str + pos + charlen, string->str + pos, string->len - pos);
862  
863 dest = string->str + pos;
864 /* Code copied from g_unichar_to_utf() */
865 for (i = charlen - 1; i > 0; --i)
866 {
867 dest[i] = (wc & 0x3f) | 0x80;
868 wc >>= 6;
869 }
870 dest[0] = wc | first;
871 /* End of copied code */
872  
873 string->len += charlen;
874  
875 string->str[string->len] = 0;
876  
877 return string;
878 }
879  
880 /**
881 * g_string_overwrite:
882 * @string: a #GString
883 * @pos: the position at which to start overwriting
884 * @val: the string that will overwrite the @string starting at @pos
885 *
886 * Overwrites part of a string, lengthening it if necessary.
887 *
888 * Returns: (transfer none): @string
889 *
890 * Since: 2.14
891 */
892 GString *
893 g_string_overwrite (GString *string,
894 gsize pos,
895 const gchar *val)
896 {
897 g_return_val_if_fail (val != NULL, string);
898 return g_string_overwrite_len (string, pos, val, strlen (val));
899 }
900  
901 /**
902 * g_string_overwrite_len:
903 * @string: a #GString
904 * @pos: the position at which to start overwriting
905 * @val: the string that will overwrite the @string starting at @pos
906 * @len: the number of bytes to write from @val
907 *
908 * Overwrites part of a string, lengthening it if necessary.
909 * This function will work with embedded nuls.
910 *
911 * Returns: (transfer none): @string
912 *
913 * Since: 2.14
914 */
915 GString *
916 g_string_overwrite_len (GString *string,
917 gsize pos,
918 const gchar *val,
919 gssize len)
920 {
921 gsize end;
922  
923 g_return_val_if_fail (string != NULL, NULL);
924  
925 if (!len)
926 return string;
927  
928 g_return_val_if_fail (val != NULL, string);
929 g_return_val_if_fail (pos <= string->len, string);
930  
931 if (len < 0)
932 len = strlen (val);
933  
934 end = pos + len;
935  
936 if (end > string->len)
937 g_string_maybe_expand (string, end - string->len);
938  
939 memcpy (string->str + pos, val, len);
940  
941 if (end > string->len)
942 {
943 string->str[end] = '\0';
944 string->len = end;
945 }
946  
947 return string;
948 }
949  
950 /**
951 * g_string_erase:
952 * @string: a #GString
953 * @pos: the position of the content to remove
954 * @len: the number of bytes to remove, or -1 to remove all
955 * following bytes
956 *
957 * Removes @len bytes from a #GString, starting at position @pos.
958 * The rest of the #GString is shifted down to fill the gap.
959 *
960 * Returns: (transfer none): @string
961 */
962 GString *
963 g_string_erase (GString *string,
964 gssize pos,
965 gssize len)
966 {
967 g_return_val_if_fail (string != NULL, NULL);
968 g_return_val_if_fail (pos >= 0, string);
969 g_return_val_if_fail (pos <= string->len, string);
970  
971 if (len < 0)
972 len = string->len - pos;
973 else
974 {
975 g_return_val_if_fail (pos + len <= string->len, string);
976  
977 if (pos + len < string->len)
978 memmove (string->str + pos, string->str + pos + len, string->len - (pos + len));
979 }
980  
981 string->len -= len;
982  
983 string->str[string->len] = 0;
984  
985 return string;
986 }
987  
988 /**
989 * g_string_ascii_down:
990 * @string: a GString
991 *
992 * Converts all uppercase ASCII letters to lowercase ASCII letters.
993 *
994 * Returns: (transfer none): passed-in @string pointer, with all the
995 * uppercase characters converted to lowercase in place,
996 * with semantics that exactly match g_ascii_tolower().
997 */
998 GString *
999 g_string_ascii_down (GString *string)
1000 {
1001 gchar *s;
1002 gint n;
1003  
1004 g_return_val_if_fail (string != NULL, NULL);
1005  
1006 n = string->len;
1007 s = string->str;
1008  
1009 while (n)
1010 {
1011 *s = g_ascii_tolower (*s);
1012 s++;
1013 n--;
1014 }
1015  
1016 return string;
1017 }
1018  
1019 /**
1020 * g_string_ascii_up:
1021 * @string: a GString
1022 *
1023 * Converts all lowercase ASCII letters to uppercase ASCII letters.
1024 *
1025 * Returns: (transfer none): passed-in @string pointer, with all the
1026 * lowercase characters converted to uppercase in place,
1027 * with semantics that exactly match g_ascii_toupper().
1028 */
1029 GString *
1030 g_string_ascii_up (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_toupper (*s);
1043 s++;
1044 n--;
1045 }
1046  
1047 return string;
1048 }
1049  
1050 /**
1051 * g_string_down:
1052 * @string: a #GString
1053 *
1054 * Converts a #GString to lowercase.
1055 *
1056 * Returns: (transfer none): the #GString
1057 *
1058 * Deprecated:2.2: This function uses the locale-specific
1059 * tolower() function, which is almost never the right thing.
1060 * Use g_string_ascii_down() or g_utf8_strdown() instead.
1061 */
1062 GString *
1063 g_string_down (GString *string)
1064 {
1065 guchar *s;
1066 glong n;
1067  
1068 g_return_val_if_fail (string != NULL, NULL);
1069  
1070 n = string->len;
1071 s = (guchar *) string->str;
1072  
1073 while (n)
1074 {
1075 if (isupper (*s))
1076 *s = tolower (*s);
1077 s++;
1078 n--;
1079 }
1080  
1081 return string;
1082 }
1083  
1084 /**
1085 * g_string_up:
1086 * @string: a #GString
1087 *
1088 * Converts a #GString to uppercase.
1089 *
1090 * Returns: (transfer none): @string
1091 *
1092 * Deprecated:2.2: This function uses the locale-specific
1093 * toupper() function, which is almost never the right thing.
1094 * Use g_string_ascii_up() or g_utf8_strup() instead.
1095 */
1096 GString *
1097 g_string_up (GString *string)
1098 {
1099 guchar *s;
1100 glong n;
1101  
1102 g_return_val_if_fail (string != NULL, NULL);
1103  
1104 n = string->len;
1105 s = (guchar *) string->str;
1106  
1107 while (n)
1108 {
1109 if (islower (*s))
1110 *s = toupper (*s);
1111 s++;
1112 n--;
1113 }
1114  
1115 return string;
1116 }
1117  
1118 /**
1119 * g_string_append_vprintf:
1120 * @string: a #GString
1121 * @format: the string format. See the printf() documentation
1122 * @args: the list of arguments to insert in the output
1123 *
1124 * Appends a formatted string onto the end of a #GString.
1125 * This function is similar to g_string_append_printf()
1126 * except that the arguments to the format string are passed
1127 * as a va_list.
1128 *
1129 * Since: 2.14
1130 */
1131 void
1132 g_string_append_vprintf (GString *string,
1133 const gchar *format,
1134 va_list args)
1135 {
1136 gchar *buf;
1137 gint len;
1138  
1139 g_return_if_fail (string != NULL);
1140 g_return_if_fail (format != NULL);
1141  
1142 len = g_vasprintf (&buf, format, args);
1143  
1144 if (len >= 0)
1145 {
1146 g_string_maybe_expand (string, len);
1147 memcpy (string->str + string->len, buf, len + 1);
1148 string->len += len;
1149 g_free (buf);
1150 }
1151 }
1152  
1153 /**
1154 * g_string_vprintf:
1155 * @string: a #GString
1156 * @format: the string format. See the printf() documentation
1157 * @args: the parameters to insert into the format string
1158 *
1159 * Writes a formatted string into a #GString.
1160 * This function is similar to g_string_printf() except that
1161 * the arguments to the format string are passed as a va_list.
1162 *
1163 * Since: 2.14
1164 */
1165 void
1166 g_string_vprintf (GString *string,
1167 const gchar *format,
1168 va_list args)
1169 {
1170 g_string_truncate (string, 0);
1171 g_string_append_vprintf (string, format, args);
1172 }
1173  
1174 /**
1175 * g_string_sprintf:
1176 * @string: a #GString
1177 * @format: the string format. See the sprintf() documentation
1178 * @...: the parameters to insert into the format string
1179 *
1180 * Writes a formatted string into a #GString.
1181 * This is similar to the standard sprintf() function,
1182 * except that the #GString buffer automatically expands
1183 * to contain the results. The previous contents of the
1184 * #GString are destroyed.
1185 *
1186 * Deprecated: This function has been renamed to g_string_printf().
1187 */
1188  
1189 /**
1190 * g_string_printf:
1191 * @string: a #GString
1192 * @format: the string format. See the printf() documentation
1193 * @...: the parameters to insert into the format string
1194 *
1195 * Writes a formatted string into a #GString.
1196 * This is similar to the standard sprintf() function,
1197 * except that the #GString buffer automatically expands
1198 * to contain the results. The previous contents of the
1199 * #GString are destroyed.
1200 */
1201 void
1202 g_string_printf (GString *string,
1203 const gchar *format,
1204 ...)
1205 {
1206 va_list args;
1207  
1208 g_string_truncate (string, 0);
1209  
1210 va_start (args, format);
1211 g_string_append_vprintf (string, format, args);
1212 va_end (args);
1213 }
1214  
1215 /**
1216 * g_string_sprintfa:
1217 * @string: a #GString
1218 * @format: the string format. See the sprintf() documentation
1219 * @...: the parameters to insert into the format string
1220 *
1221 * Appends a formatted string onto the end of a #GString.
1222 * This function is similar to g_string_sprintf() except that
1223 * the text is appended to the #GString.
1224 *
1225 * Deprecated: This function has been renamed to g_string_append_printf()
1226 */
1227  
1228 /**
1229 * g_string_append_printf:
1230 * @string: a #GString
1231 * @format: the string format. See the printf() documentation
1232 * @...: the parameters to insert into the format string
1233 *
1234 * Appends a formatted string onto the end of a #GString.
1235 * This function is similar to g_string_printf() except
1236 * that the text is appended to the #GString.
1237 */
1238 void
1239 g_string_append_printf (GString *string,
1240 const gchar *format,
1241 ...)
1242 {
1243 va_list args;
1244  
1245 va_start (args, format);
1246 g_string_append_vprintf (string, format, args);
1247 va_end (args);
1248 }