glib2.0_2.20.1
[mer:glib2_0.git] / docs / reference / glib / tmpl / string_utils.sgml
1 <!-- ##### SECTION Title ##### -->
2 String Utility Functions
3
4 <!-- ##### SECTION Short_Description ##### -->
5 various string-related functions
6
7 <!-- ##### SECTION Long_Description ##### -->
8 <para>
9 This section describes a number of utility functions for creating,
10 duplicating, and manipulating strings.
11 </para>
12 <para>
13 Note that the functions g_printf(), g_fprintf(), g_sprintf(), g_snprintf(),
14 g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() are declared in 
15 the header <filename>gprintf.h</filename> which is <emphasis>not</emphasis>
16 included in <filename>glib.h</filename> (otherwise using 
17 <filename>glib.h</filename> would drag in <filename>stdio.h</filename>), so
18 you'll have to explicitly include <literal>&lt;glib/gprintf.h&gt;</literal> 
19 in order to use the GLib printf() functions. 
20 </para>
21 <para id="string-precision">
22 While you may use the printf() functions to format UTF-8 strings, notice that
23 the precision of a <literal>&percnt;Ns</literal> parameter is interpreted as the
24 number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> to print.
25 On top of that, the GNU libc implementation of the printf() functions has the "feature"
26 that it checks that the string given for the <literal>&percnt;Ns</literal> parameter
27 consists of a whole number of characters in the current encoding. So, unless you
28 are sure you are always going to be in an UTF-8 locale or your know your text is restricted 
29 to ASCII, avoid using <literal>&percnt;Ns</literal>.
30 If your intention is to format strings for a certain number of columns, then 
31 <literal>&percnt;Ns</literal> is not a correct solution anyway, since it fails to take 
32 wide characters (see g_unichar_iswide()) into account.
33 </para>
34
35 <!-- ##### SECTION See_Also ##### -->
36 <para>
37
38 </para>
39
40 <!-- ##### SECTION Stability_Level ##### -->
41
42
43 <!-- ##### FUNCTION g_strdup ##### -->
44 <para>
45
46 </para>
47
48 @str: 
49 @Returns: 
50
51
52 <!-- ##### FUNCTION g_strndup ##### -->
53 <para>
54
55 </para>
56
57 @str: 
58 @n: 
59 @Returns: 
60
61
62 <!-- ##### FUNCTION g_strdupv ##### -->
63 <para>
64 </para>
65
66 @str_array: 
67 @Returns: 
68
69
70 <!-- ##### FUNCTION g_strnfill ##### -->
71 <para>
72
73 </para>
74
75 @length: 
76 @fill_char: 
77 @Returns: 
78
79
80 <!-- ##### FUNCTION g_stpcpy ##### -->
81 <para>
82
83 </para>
84
85 @dest: 
86 @src: 
87 @Returns: 
88
89
90 <!-- ##### FUNCTION g_strstr_len ##### -->
91 <para>
92
93 </para>
94
95 @haystack: 
96 @haystack_len: 
97 @needle: 
98 @Returns: 
99
100
101 <!-- ##### FUNCTION g_strrstr ##### -->
102 <para>
103
104 </para>
105
106 @haystack: 
107 @needle: 
108 @Returns: 
109
110
111 <!-- ##### FUNCTION g_strrstr_len ##### -->
112 <para>
113
114 </para>
115
116 @haystack: 
117 @haystack_len: 
118 @needle: 
119 @Returns: 
120
121
122 <!-- ##### FUNCTION g_str_has_prefix ##### -->
123 <para>
124
125 </para>
126
127 @str: 
128 @prefix: 
129 @Returns: 
130
131
132 <!-- ##### FUNCTION g_str_has_suffix ##### -->
133 <para>
134
135 </para>
136
137 @str: 
138 @suffix: 
139 @Returns: 
140
141
142 <!-- ##### FUNCTION g_strcmp0 ##### -->
143 <para>
144
145 </para>
146
147 @str1: 
148 @str2: 
149 @Returns: 
150
151
152 <!-- ##### FUNCTION g_strlcpy ##### -->
153 <para>
154
155 </para>
156
157 @dest: 
158 @src: 
159 @dest_size: 
160 @Returns: 
161
162
163 <!-- ##### FUNCTION g_strlcat ##### -->
164 <para>
165
166 </para>
167
168 @dest: 
169 @src: 
170 @dest_size: 
171 @Returns: 
172
173
174 <!-- ##### FUNCTION g_strdup_printf ##### -->
175 <para>
176 </para>
177
178 @format: 
179 @Varargs: 
180 @Returns: 
181
182
183 <!-- ##### FUNCTION g_strdup_vprintf ##### -->
184 <para>
185
186 </para>
187
188 @format: 
189 @args: 
190 @Returns: 
191
192
193 <!-- ##### FUNCTION g_printf ##### -->
194 <para>
195
196 </para>
197
198 @format: 
199 @Varargs: 
200 @Returns: 
201
202
203 <!-- ##### FUNCTION g_vprintf ##### -->
204 <para>
205
206 </para>
207
208 @format: 
209 @args: 
210 @Returns: 
211
212
213 <!-- ##### FUNCTION g_fprintf ##### -->
214 <para>
215
216 </para>
217
218 @file: 
219 @format: 
220 @Varargs: 
221 @Returns: 
222
223
224 <!-- ##### FUNCTION g_vfprintf ##### -->
225 <para>
226
227 </para>
228
229 @file: 
230 @format: 
231 @args: 
232 @Returns: 
233
234
235 <!-- ##### FUNCTION g_sprintf ##### -->
236 <para>
237
238 </para>
239
240 @string: 
241 @format: 
242 @Varargs: 
243 @Returns: 
244
245
246 <!-- ##### FUNCTION g_vsprintf ##### -->
247 <para>
248
249 </para>
250
251 @string: 
252 @format: 
253 @args: 
254 @Returns: 
255
256
257 <!-- ##### FUNCTION g_snprintf ##### -->
258 <para>
259 </para>
260
261 @string: 
262 @n: 
263 @format: 
264 @Varargs: 
265 @Returns: 
266
267
268 <!-- ##### FUNCTION g_vsnprintf ##### -->
269 <para>
270 </para>
271
272 @string: 
273 @n: 
274 @format: 
275 @args: 
276 @Returns: 
277
278
279 <!-- ##### FUNCTION g_vasprintf ##### -->
280 <para>
281
282 </para>
283
284 @string: 
285 @format: 
286 @args: 
287 @Returns: 
288
289
290 <!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
291 <para>
292 Calculates the maximum space needed to store the output of the sprintf() 
293 function.
294 </para>
295
296 @format: the format string. See the printf() documentation.
297 @args: the parameters to be inserted into the format string.
298 @Returns: the maximum space needed to store the formatted string.
299
300
301 <!-- ##### FUNCTION g_ascii_isalnum ##### -->
302 <para>
303 Determines whether a character is alphanumeric.
304 </para>
305 <para>
306 Unlike the standard C library isalnum() function, this only
307 recognizes standard ASCII letters and ignores the locale, returning
308 %FALSE for all non-ASCII characters. Also unlike the standard
309 library function, this takes a <type>char</type>, not an <type>int</type>, 
310 so don't call it on %EOF but no need to cast to #guchar before passing a 
311 possibly non-ASCII character in.
312 </para>
313
314 @c: any character
315 @Returns: %TRUE if @c is an ASCII alphanumeric character
316
317
318 <!-- ##### FUNCTION g_ascii_isalpha ##### -->
319 <para>
320 Determines whether a character is alphabetic (i.e. a letter).
321 </para>
322 <para>
323 Unlike the standard C library isalpha() function, this only
324 recognizes standard ASCII letters and ignores the locale, returning
325 %FALSE for all non-ASCII characters. Also unlike the standard
326 library function, this takes a <type>char</type>, not an <type>int</type>, 
327 so don't call it on %EOF but no need to cast to #guchar before passing a 
328 possibly non-ASCII character in.
329 </para>
330
331 @c: any character
332 @Returns: %TRUE if @c is an ASCII alphabetic character
333
334
335 <!-- ##### FUNCTION g_ascii_iscntrl ##### -->
336 <para>
337 Determines whether a character is a control character.
338 </para>
339 <para>
340 Unlike the standard C library iscntrl() function, this only
341 recognizes standard ASCII control characters and ignores the locale,
342 returning %FALSE for all non-ASCII characters. Also unlike the standard
343 library function, this takes a <type>char</type>, not an <type>int</type>, 
344 so don't call it on %EOF but no need to cast to #guchar before passing a 
345 possibly non-ASCII character in.
346 </para>
347
348 @c: any character
349 @Returns: %TRUE if @c is an ASCII control character.
350
351
352 <!-- ##### FUNCTION g_ascii_isdigit ##### -->
353 <para>
354 Determines whether a character is digit (0-9).
355 </para>
356 <para>
357 Unlike the standard C library isdigit() function,
358 this takes a <type>char</type>, not an <type>int</type>, so don't call it
359 on %EOF but no need to cast to #guchar before passing a possibly
360 non-ASCII character in.
361 </para>
362
363 @c: any character
364 @Returns: %TRUE if @c is an ASCII digit.
365
366
367 <!-- ##### FUNCTION g_ascii_isgraph ##### -->
368 <para>
369 Determines whether a character is a printing character and not a space.
370 </para>
371 <para>
372 Unlike the standard C library isgraph() function, 
373 this only recognizes standard ASCII characters and ignores the locale, 
374 returning %FALSE for all non-ASCII characters. Also unlike the standard
375 library function, this takes a <type>char</type>, not an <type>int</type>, 
376 so don't call it on %EOF but no need to cast to #guchar before passing a 
377 possibly non-ASCII character in.
378 </para>
379
380 @c: any character
381 @Returns: %TRUE if @c is an ASCII printing character other than space.
382
383
384 <!-- ##### FUNCTION g_ascii_islower ##### -->
385 <para>
386 Determines whether a character is an ASCII lower case letter.
387 </para>
388 <para>
389 Unlike the standard C library islower() function, 
390 this only recognizes standard ASCII letters and ignores the locale,
391 returning %FALSE for all non-ASCII characters. Also unlike the standard
392 library function, this takes a <type>char</type>, not an <type>int</type>, 
393 so don't call it on %EOF but no need to worry about casting to #guchar 
394 before passing a possibly non-ASCII character in.
395 </para>
396
397 @c: any character
398 @Returns: %TRUE if @c is an ASCII lower case letter
399
400
401 <!-- ##### FUNCTION g_ascii_isprint ##### -->
402 <para>
403 Determines whether a character is a printing character.
404 </para>
405 <para>
406 Unlike the standard C library isprint() function, 
407 this only recognizes standard ASCII characters and ignores the locale, 
408 returning %FALSE for all non-ASCII characters. Also unlike the standard
409 library function, this takes a <type>char</type>, not an <type>int</type>, 
410 so don't call it on %EOF but no need to cast to #guchar before passing a 
411 possibly non-ASCII character in.
412 </para>
413
414 @c: any character
415 @Returns: %TRUE if @c is an ASCII printing character.
416
417
418 <!-- ##### FUNCTION g_ascii_ispunct ##### -->
419 <para>
420 Determines whether a character is a punctuation character.
421 </para>
422 <para>
423 Unlike the standard C library ispunct() function, 
424 this only recognizes standard ASCII letters and ignores the locale, 
425 returning %FALSE for all non-ASCII characters. Also unlike the standard
426 library function, this takes a <type>char</type>, not an <type>int</type>, 
427 so don't call it on %EOF but no need to cast to #guchar before passing a 
428 possibly non-ASCII character in.
429 </para>
430
431 @c: any character
432 @Returns: %TRUE if @c is an ASCII punctuation character.
433
434
435 <!-- ##### FUNCTION g_ascii_isspace ##### -->
436 <para>
437 Determines whether a character is a white-space character.
438 </para>
439 <para>
440 Unlike the standard C library isspace() function, 
441 this only recognizes standard ASCII white-space and ignores the locale, 
442 returning %FALSE for all non-ASCII characters. Also unlike the standard
443 library function, this takes a <type>char</type>, not an <type>int</type>, 
444 so don't call it on %EOF but no need to cast to #guchar before passing a 
445 possibly non-ASCII character in.
446 </para>
447
448 @c: any character
449 @Returns: %TRUE if @c is an ASCII white-space character
450
451
452 <!-- ##### FUNCTION g_ascii_isupper ##### -->
453 <para>
454 Determines whether a character is an ASCII upper case letter.
455 </para>
456 <para>
457 Unlike the standard C library isupper() function, 
458 this only recognizes standard ASCII letters and ignores the locale, 
459 returning %FALSE for all non-ASCII characters. Also unlike the standard
460 library function, this takes a <type>char</type>, not an <type>int</type>, 
461 so don't call it on %EOF but no need to worry about casting to #guchar 
462 before passing a possibly non-ASCII character in.
463 </para>
464
465 @c: any character
466 @Returns: %TRUE if @c is an ASCII upper case letter
467
468
469 <!-- ##### FUNCTION g_ascii_isxdigit ##### -->
470 <para>
471 Determines whether a character is a hexadecimal-digit character.
472 </para>
473 <para>
474 Unlike the standard C library isxdigit() function,
475 this takes a <type>char</type>, not an <type>int</type>, so
476 don't call it on %EOF but no need to cast to #guchar before passing a
477 possibly non-ASCII character in.
478 </para>
479
480 @c: any character
481 @Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
482
483
484 <!-- ##### FUNCTION g_ascii_digit_value ##### -->
485 <para>
486
487 </para>
488
489 @c: 
490 @Returns: 
491
492
493 <!-- ##### FUNCTION g_ascii_xdigit_value ##### -->
494 <para>
495
496 </para>
497
498 @c: 
499 @Returns: 
500
501
502 <!-- ##### FUNCTION g_ascii_strcasecmp ##### -->
503 <para>
504
505 </para>
506
507 @s1: 
508 @s2: 
509 @Returns: 
510
511
512 <!-- ##### FUNCTION g_ascii_strncasecmp ##### -->
513 <para>
514
515 </para>
516
517 @s1: 
518 @s2: 
519 @n: 
520 @Returns: 
521
522
523 <!-- ##### FUNCTION g_ascii_strup ##### -->
524 <para>
525
526 </para>
527
528 @str: 
529 @len: 
530 @Returns: 
531
532
533 <!-- ##### FUNCTION g_ascii_strdown ##### -->
534 <para>
535
536 </para>
537
538 @str: 
539 @len: 
540 @Returns: 
541
542
543 <!-- ##### FUNCTION g_ascii_tolower ##### -->
544 <para>
545
546 </para>
547
548 @c: 
549 @Returns: 
550
551
552 <!-- ##### FUNCTION g_ascii_toupper ##### -->
553 <para>
554
555 </para>
556
557 @c: 
558 @Returns: 
559
560
561 <!-- ##### FUNCTION g_string_ascii_up ##### -->
562 <para>
563
564 </para>
565
566 @string: 
567 @Returns: 
568
569
570 <!-- ##### FUNCTION g_string_ascii_down ##### -->
571 <para>
572
573 </para>
574
575 @string: 
576 @Returns: 
577
578
579 <!-- ##### FUNCTION g_strup ##### -->
580 <para>
581 </para>
582
583 @string: 
584 @Returns: 
585
586
587 <!-- ##### FUNCTION g_strdown ##### -->
588 <para>
589 </para>
590
591 @string: 
592 @Returns: 
593
594
595 <!-- ##### FUNCTION g_strcasecmp ##### -->
596 <para>
597 </para>
598
599 @s1: 
600 @s2: 
601 @Returns: 
602
603
604 <!-- ##### FUNCTION g_strncasecmp ##### -->
605 <para>
606 </para>
607
608 @s1: 
609 @s2: 
610 @n: 
611 @Returns: 
612
613
614 <!-- ##### FUNCTION g_strreverse ##### -->
615 <para>
616
617 </para>
618
619 @string: 
620 @Returns: 
621
622
623 <!-- ##### FUNCTION g_ascii_strtoll ##### -->
624 <para>
625
626 </para>
627
628 @nptr: 
629 @endptr: 
630 @base: 
631 @Returns: 
632
633
634 <!-- ##### FUNCTION g_ascii_strtoull ##### -->
635 <para>
636
637 </para>
638
639 @nptr: 
640 @endptr: 
641 @base: 
642 @Returns: 
643
644
645 <!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
646 <para>
647 A good size for a buffer to be passed into g_ascii_dtostr().
648 It is guaranteed to be enough for all output of that function on systems with
649  64bit IEEE-compatible doubles.
650 </para>
651 <para>
652 The typical usage would be something like:
653 <informalexample><programlisting>
654   char buf[G_ASCII_DTOSTR_BUF_SIZE];
655
656   fprintf (out, "value=&percnt;s\n", g_ascii_dtostr (buf, sizeof (buf), value));
657 </programlisting></informalexample>
658 </para>
659
660
661
662 <!-- ##### FUNCTION g_ascii_strtod ##### -->
663 <para>
664
665 </para>
666
667 @nptr: 
668 @endptr: 
669 @Returns: 
670
671
672 <!-- ##### FUNCTION g_ascii_dtostr ##### -->
673 <para>
674
675 </para>
676
677 @buffer: 
678 @buf_len: 
679 @d: 
680 @Returns: 
681
682
683 <!-- ##### FUNCTION g_ascii_formatd ##### -->
684 <para>
685
686 </para>
687
688 @buffer: 
689 @buf_len: 
690 @format: 
691 @d: 
692 @Returns: 
693
694
695 <!-- ##### FUNCTION g_strtod ##### -->
696 <para>
697
698 </para>
699
700 @nptr: 
701 @endptr: 
702 @Returns: 
703
704
705 <!-- ##### FUNCTION g_strchug ##### -->
706 <para>
707 Removes leading whitespace from a string, by moving the rest of the
708 characters forward.
709 </para>
710 <para>
711 This function doesn't allocate or reallocate any memory; it modifies @string
712 in place. The pointer to @string is returned to allow the nesting of functions.
713 </para>
714 <para>
715 Also see g_strchomp() and g_strstrip().
716 </para>
717
718 @string: a string to remove the leading whitespace from.
719 @Returns: @string.
720
721
722 <!-- ##### FUNCTION g_strchomp ##### -->
723 <para>
724 Removes trailing whitespace from a string.
725 </para>
726 <para>
727 This function doesn't allocate or reallocate any memory; it modifies @string in
728 place. The pointer to @string is returned to allow the nesting of functions.
729 </para>
730 <para>
731 Also see g_strchug() and g_strstrip().
732 </para>
733
734 @string: a string to remove the trailing whitespace from.
735 @Returns: @string.
736
737
738 <!-- ##### MACRO g_strstrip ##### -->
739 <para>
740 Removes leading and trailing whitespace from a string. See g_strchomp() and
741 g_strchug().
742 </para>
743
744 @string: a string to remove the leading and trailing whitespace from.
745
746
747 <!-- ##### FUNCTION g_strdelimit ##### -->
748 <para>
749 Converts any delimiter characters in @string to @new_delimiter.
750 Any characters in @string which are found in @delimiters are changed
751 to the @new_delimiter character. Modifies @string in place, and returns 
752 @string itself, not a copy. The return value is to allow nesting such as
753 <literal>g_ascii_strup (g_strdelimit (str, "abc", '?'))</literal>.
754 </para>
755
756 @string: the string to convert.
757 @delimiters: a string containing the current delimiters, or %NULL to use the
758 standard delimiters defined in #G_STR_DELIMITERS.
759 @new_delimiter: the new delimiter character.
760 @Returns: @string.
761
762
763 <!-- ##### MACRO G_STR_DELIMITERS ##### -->
764 <para>
765 The standard delimiters, used in g_strdelimit().
766 </para>
767
768
769
770 <!-- ##### FUNCTION g_strescape ##### -->
771 <para>
772 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
773 '&quot;' in the string @source by inserting a '\' before
774 them. Additionally all characters in the range 0x01-0x1F (everything
775 below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
776 replaced with a '\' followed by their octal representation. Characters
777 supplied in @exceptions are not escaped.
778 </para>
779
780 <para>
781 g_strcompress() does the reverse conversion.
782 </para>
783
784 @source: a string to escape.
785 @exceptions: a string of characters not to escape in @source.
786 @Returns: a newly-allocated copy of @source with certain
787 characters escaped. See above.
788
789
790 <!-- ##### FUNCTION g_strcompress ##### -->
791 <para>
792 Replaces all escaped characters with their one byte equivalent. It
793 does the reverse conversion of g_strescape(). 
794 </para>
795
796 @source: a string to compress.
797 @Returns: a newly-allocated copy of @source with all escaped 
798 character compressed.
799
800
801 <!-- ##### FUNCTION g_strcanon ##### -->
802 <para>
803 For each character in @string, if the character is not in @valid_chars,
804 replaces the character with @substitutor. Modifies @string in place, 
805 and return @string itself, not a copy. The return value is to allow
806 nesting such as <literal>g_ascii_strup (g_strcanon (str, "abc", '?'))</literal>.
807 </para>
808
809 @string: a nul-terminated array of bytes.
810 @valid_chars: bytes permitted in @string.
811 @substitutor: replacement character for disallowed bytes.
812 @Returns: @string.
813
814
815 <!-- ##### FUNCTION g_strsplit ##### -->
816 <para>
817 </para>
818
819 @string: 
820 @delimiter: 
821 @max_tokens: 
822 @Returns: 
823
824
825 <!-- ##### FUNCTION g_strsplit_set ##### -->
826 <para>
827
828 </para>
829
830 @string: 
831 @delimiters: 
832 @max_tokens: 
833 @Returns: 
834
835
836 <!-- ##### FUNCTION g_strfreev ##### -->
837 <para>
838
839 </para>
840
841 @str_array: 
842
843
844 <!-- ##### FUNCTION g_strconcat ##### -->
845 <para>
846
847 </para>
848
849 @string1: 
850 @Varargs: 
851 @Returns: 
852
853
854 <!-- ##### FUNCTION g_strjoin ##### -->
855 <para>
856
857 </para>
858
859 @separator: 
860 @Varargs: 
861 @Returns: 
862
863
864 <!-- ##### FUNCTION g_strjoinv ##### -->
865 <para>
866
867 </para>
868
869 @separator: 
870 @str_array: 
871 @Returns: 
872
873
874 <!-- ##### FUNCTION g_strv_length ##### -->
875 <para>
876
877 </para>
878
879 @str_array: 
880 @Returns: 
881
882
883 <!-- ##### FUNCTION g_strerror ##### -->
884 <para>
885
886 </para>
887
888 @errnum: 
889 @Returns: 
890
891
892 <!-- ##### FUNCTION g_strsignal ##### -->
893 <para>
894
895 </para>
896
897 @signum: 
898 @Returns: 
899
900