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 | |
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 (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 | */ |
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 (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 | */ |
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 (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 | */ |
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 (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 | */ |
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 (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 | */ |
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, 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 | */ |
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: 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 | */ |
425 | GString * |
426 | g_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 | */ |
524 | GString * |
525 | g_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 | */ |
545 | GString * |
546 | g_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 | */ |
570 | GString * |
571 | g_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 |
589 | GString * |
590 | g_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 | */ |
608 | GString * |
609 | g_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 | */ |
627 | GString * |
628 | g_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 | */ |
652 | GString * |
653 | g_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 | */ |
670 | GString * |
671 | g_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 | */ |
689 | GString * |
690 | g_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 | */ |
709 | GString * |
710 | g_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 | */ |
727 | GString * |
728 | g_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 | */ |
770 | GString * |
771 | g_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 | */ |
853 | GString * |
854 | g_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 | */ |
876 | GString * |
877 | g_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 | */ |
923 | GString * |
924 | g_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 | */ |
978 | guint |
979 | g_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 | */ |
1029 | GString * |
1030 | g_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 | */ |
1060 | GString * |
1061 | g_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 | */ |
1093 | GString * |
1094 | g_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 | */ |
1127 | GString * |
1128 | g_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 | */ |
1162 | void |
1163 | g_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 | */ |
1196 | void |
1197 | g_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 | */ |
1232 | void |
1233 | g_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 | */ |
1269 | void |
1270 | g_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 | |