1 <!-- ##### SECTION Title ##### -->
2 String Utility Functions
4 <!-- ##### SECTION Short_Description ##### -->
5 various string-related functions
7 <!-- ##### SECTION Long_Description ##### -->
9 This section describes a number of utility functions for creating,
10 duplicating, and manipulating strings.
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><glib/gprintf.h></literal>
19 in order to use the GLib printf() functions.
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>%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>%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>%Ns</literal>.
30 If your intention is to format strings for a certain number of columns, then
31 <literal>%Ns</literal> is not a correct solution anyway, since it fails to take
32 wide characters (see g_unichar_iswide()) into account.
35 <!-- ##### SECTION See_Also ##### -->
40 <!-- ##### SECTION Stability_Level ##### -->
43 <!-- ##### FUNCTION g_strdup ##### -->
52 <!-- ##### FUNCTION g_strndup ##### -->
62 <!-- ##### FUNCTION g_strdupv ##### -->
70 <!-- ##### FUNCTION g_strnfill ##### -->
80 <!-- ##### FUNCTION g_stpcpy ##### -->
90 <!-- ##### FUNCTION g_strstr_len ##### -->
101 <!-- ##### FUNCTION g_strrstr ##### -->
111 <!-- ##### FUNCTION g_strrstr_len ##### -->
122 <!-- ##### FUNCTION g_str_has_prefix ##### -->
132 <!-- ##### FUNCTION g_str_has_suffix ##### -->
142 <!-- ##### FUNCTION g_strcmp0 ##### -->
152 <!-- ##### FUNCTION g_strlcpy ##### -->
163 <!-- ##### FUNCTION g_strlcat ##### -->
174 <!-- ##### FUNCTION g_strdup_printf ##### -->
183 <!-- ##### FUNCTION g_strdup_vprintf ##### -->
193 <!-- ##### FUNCTION g_printf ##### -->
203 <!-- ##### FUNCTION g_vprintf ##### -->
213 <!-- ##### FUNCTION g_fprintf ##### -->
224 <!-- ##### FUNCTION g_vfprintf ##### -->
235 <!-- ##### FUNCTION g_sprintf ##### -->
246 <!-- ##### FUNCTION g_vsprintf ##### -->
257 <!-- ##### FUNCTION g_snprintf ##### -->
268 <!-- ##### FUNCTION g_vsnprintf ##### -->
279 <!-- ##### FUNCTION g_vasprintf ##### -->
290 <!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
292 Calculates the maximum space needed to store the output of the sprintf()
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.
301 <!-- ##### FUNCTION g_ascii_isalnum ##### -->
303 Determines whether a character is alphanumeric.
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.
315 @Returns: %TRUE if @c is an ASCII alphanumeric character
318 <!-- ##### FUNCTION g_ascii_isalpha ##### -->
320 Determines whether a character is alphabetic (i.e. a letter).
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.
332 @Returns: %TRUE if @c is an ASCII alphabetic character
335 <!-- ##### FUNCTION g_ascii_iscntrl ##### -->
337 Determines whether a character is a control character.
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.
349 @Returns: %TRUE if @c is an ASCII control character.
352 <!-- ##### FUNCTION g_ascii_isdigit ##### -->
354 Determines whether a character is digit (0-9).
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.
364 @Returns: %TRUE if @c is an ASCII digit.
367 <!-- ##### FUNCTION g_ascii_isgraph ##### -->
369 Determines whether a character is a printing character and not a space.
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.
381 @Returns: %TRUE if @c is an ASCII printing character other than space.
384 <!-- ##### FUNCTION g_ascii_islower ##### -->
386 Determines whether a character is an ASCII lower case letter.
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.
398 @Returns: %TRUE if @c is an ASCII lower case letter
401 <!-- ##### FUNCTION g_ascii_isprint ##### -->
403 Determines whether a character is a printing character.
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.
415 @Returns: %TRUE if @c is an ASCII printing character.
418 <!-- ##### FUNCTION g_ascii_ispunct ##### -->
420 Determines whether a character is a punctuation character.
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.
432 @Returns: %TRUE if @c is an ASCII punctuation character.
435 <!-- ##### FUNCTION g_ascii_isspace ##### -->
437 Determines whether a character is a white-space character.
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.
449 @Returns: %TRUE if @c is an ASCII white-space character
452 <!-- ##### FUNCTION g_ascii_isupper ##### -->
454 Determines whether a character is an ASCII upper case letter.
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.
466 @Returns: %TRUE if @c is an ASCII upper case letter
469 <!-- ##### FUNCTION g_ascii_isxdigit ##### -->
471 Determines whether a character is a hexadecimal-digit character.
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.
481 @Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
484 <!-- ##### FUNCTION g_ascii_digit_value ##### -->
493 <!-- ##### FUNCTION g_ascii_xdigit_value ##### -->
502 <!-- ##### FUNCTION g_ascii_strcasecmp ##### -->
512 <!-- ##### FUNCTION g_ascii_strncasecmp ##### -->
523 <!-- ##### FUNCTION g_ascii_strup ##### -->
533 <!-- ##### FUNCTION g_ascii_strdown ##### -->
543 <!-- ##### FUNCTION g_ascii_tolower ##### -->
552 <!-- ##### FUNCTION g_ascii_toupper ##### -->
561 <!-- ##### FUNCTION g_string_ascii_up ##### -->
570 <!-- ##### FUNCTION g_string_ascii_down ##### -->
579 <!-- ##### FUNCTION g_strup ##### -->
587 <!-- ##### FUNCTION g_strdown ##### -->
595 <!-- ##### FUNCTION g_strcasecmp ##### -->
604 <!-- ##### FUNCTION g_strncasecmp ##### -->
614 <!-- ##### FUNCTION g_strreverse ##### -->
623 <!-- ##### FUNCTION g_ascii_strtoll ##### -->
634 <!-- ##### FUNCTION g_ascii_strtoull ##### -->
645 <!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
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.
652 The typical usage would be something like:
653 <informalexample><programlisting>
654 char buf[G_ASCII_DTOSTR_BUF_SIZE];
656 fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
657 </programlisting></informalexample>
662 <!-- ##### FUNCTION g_ascii_strtod ##### -->
672 <!-- ##### FUNCTION g_ascii_dtostr ##### -->
683 <!-- ##### FUNCTION g_ascii_formatd ##### -->
695 <!-- ##### FUNCTION g_strtod ##### -->
705 <!-- ##### FUNCTION g_strchug ##### -->
707 Removes leading whitespace from a string, by moving the rest of the
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.
715 Also see g_strchomp() and g_strstrip().
718 @string: a string to remove the leading whitespace from.
722 <!-- ##### FUNCTION g_strchomp ##### -->
724 Removes trailing whitespace from a string.
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.
731 Also see g_strchug() and g_strstrip().
734 @string: a string to remove the trailing whitespace from.
738 <!-- ##### MACRO g_strstrip ##### -->
740 Removes leading and trailing whitespace from a string. See g_strchomp() and
744 @string: a string to remove the leading and trailing whitespace from.
747 <!-- ##### FUNCTION g_strdelimit ##### -->
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>.
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.
763 <!-- ##### MACRO G_STR_DELIMITERS ##### -->
765 The standard delimiters, used in g_strdelimit().
770 <!-- ##### FUNCTION g_strescape ##### -->
772 Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
773 '"' 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.
781 g_strcompress() does the reverse conversion.
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.
790 <!-- ##### FUNCTION g_strcompress ##### -->
792 Replaces all escaped characters with their one byte equivalent. It
793 does the reverse conversion of g_strescape().
796 @source: a string to compress.
797 @Returns: a newly-allocated copy of @source with all escaped
798 character compressed.
801 <!-- ##### FUNCTION g_strcanon ##### -->
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>.
809 @string: a nul-terminated array of bytes.
810 @valid_chars: bytes permitted in @string.
811 @substitutor: replacement character for disallowed bytes.
815 <!-- ##### FUNCTION g_strsplit ##### -->
825 <!-- ##### FUNCTION g_strsplit_set ##### -->
836 <!-- ##### FUNCTION g_strfreev ##### -->
844 <!-- ##### FUNCTION g_strconcat ##### -->
854 <!-- ##### FUNCTION g_strjoin ##### -->
864 <!-- ##### FUNCTION g_strjoinv ##### -->
874 <!-- ##### FUNCTION g_strv_length ##### -->
883 <!-- ##### FUNCTION g_strerror ##### -->
892 <!-- ##### FUNCTION g_strsignal ##### -->