path: root/docs/reference/glib/tmpl/string_utils.sgml

<!-- ##### SECTION Title ##### -->
String Utility Functions

<!-- ##### SECTION Short_Description ##### -->
various string-related functions.

<!-- ##### SECTION Long_Description ##### -->
<para>
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
</para>
<para>
Note that the functions g_printf(), g_fprintf(), g_sprintf(), g_snprintf(),
g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf() are declared in 
the header <filename>gprintf.h</filename> which is <emphasis>not</emphasis>
included in <filename>glib.h</filename> (otherwise using 
<filename>glib.h</filename> would drag in <filename>stdio.h</filename>), so
you'll have to explicitly include <literal>&lt;glib/gprintf.h&gt;</literal> 
in order to use the GLib printf() functions. 
</para>
<para id="string-precision">
While you may use the printf() functions to format UTF-8 strings, notice that
the precision of a <literal>&percnt;Ns</literal> parameter is interpreted as the
number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis> to print.
On top of that, the GNU libc implementation of the printf() functions has the "feature"
that it checks that the string given for the <literal>&percnt;Ns</literal> parameter
consists of a whole number of characters in the current encoding. So, unless you
are sure you are always going to be in an UTF-8 locale or your know your text is restricted 
to ASCII, avoid using <literal>&percnt;Ns</literal>.
If your intention is to format strings for a certain number of columns, then 
<literal>&percnt;Ns</literal> is not a correct solution anyway, since it fails to take 
wide characters (see g_unichar_iswide()) into account.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### FUNCTION g_strdup ##### -->
<para>
Duplicates a string.
If @str is %NULL it returns %NULL.
The returned string should be freed when no longer needed.
</para>

@str: the string to duplicate.
@Returns: a newly-allocated copy of @str.


<!-- ##### FUNCTION g_strndup ##### -->
<para>
Duplicates the first @n characters of a string, returning a newly-allocated
buffer @n + 1 characters long which will always be nul-terminated.
If @str is less than @n characters long the buffer is padded with nuls.
If @str is %NULL it returns %NULL.
The returned value should be freed when no longer needed.
</para>

@str: the string to duplicate part of.
@n: the maximum number of characters to copy from @str.
@Returns: a newly-allocated buffer containing the first @n characters of @str,
nul-terminated.


<!-- ##### FUNCTION g_strdupv ##### -->
<para>
</para>

@str_array: 
@Returns: 


<!-- ##### FUNCTION g_strnfill ##### -->
<para>
Creates a new string @length characters long filled with @fill_char.
The returned string should be freed when no longer needed.
</para>

@length: the length of the new string.
@fill_char: the character to fill the string with.
@Returns: a newly-allocated string filled the @fill_char.


<!-- ##### FUNCTION g_stpcpy ##### -->
<para>

</para>

@dest: 
@src: 
@Returns: 


<!-- ##### FUNCTION g_strstr_len ##### -->
<para>

</para>

@haystack: 
@haystack_len: 
@needle: 
@Returns: 


<!-- ##### FUNCTION g_strrstr ##### -->
<para>

</para>

@haystack: 
@needle: 
@Returns: 


<!-- ##### FUNCTION g_strrstr_len ##### -->
<para>

</para>

@haystack: 
@haystack_len: 
@needle: 
@Returns: 


<!-- ##### FUNCTION g_str_has_prefix ##### -->
<para>

</para>

@str: 
@prefix: 
@Returns: 


<!-- ##### FUNCTION g_str_has_suffix ##### -->
<para>

</para>

@str: 
@suffix: 
@Returns: 


<!-- ##### FUNCTION g_strlcpy ##### -->
<para>
Portability wrapper that calls strlcpy() on systems which have it, and emulates
strlcpy() otherwise. Copies @src to @dest; @dest is guaranteed to be
nul-terminated; @src must be nul-terminated; @dest_size is the buffer size, not
the number of chars to copy. Caveat: strlcpy() is supposedly more secure than
strcpy() or strncpy(), but if you really want to avoid screwups, g_strdup() is
an even better idea.
</para>

@dest: destination buffer
@src: source buffer
@dest_size: length of @dest in bytes
@Returns: length of @src


<!-- ##### FUNCTION g_strlcat ##### -->
<para>
Portability wrapper that calls strlcat() on systems which have it, and emulates it otherwise. 
Appends nul-terminated @src string to @dest, guaranteeing
nul-termination for @dest. The total size of @dest won't exceed
@dest_size. Caveat: this is supposedly a more secure alternative to strcat() or
strncat(), but for real security g_strconcat() is harder to mess up.
</para>

@dest: destination buffer, already containing one nul-terminated string
@src: source buffer
@dest_size: length of @dest buffer in bytes (not length of existing string inside @dest)
@Returns: length of @src plus initial length of string in @dest


<!-- ##### FUNCTION g_strdup_printf ##### -->
<para>
Similar to the standard C sprintf() function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para>

@format: a standard printf() format string, but notice 
  <link linkend="string-precision">string precision pitfalls</link>.
@Varargs: the parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.


<!-- ##### FUNCTION g_strdup_vprintf ##### -->
<para>
Similar to the standard C vsprintf() function
but safer, since it calculates the maximum space required and allocates
memory to hold the result.
The returned string should be freed when no longer needed.
</para>
<para>
See also g_vasprintf(), which offers the same functionality, but additionally
returns the length of the allocated string. 
</para>

@format: a standard printf() format string, but notice 
  <link linkend="string-precision">string precision pitfalls</link>.
@args: the list of parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.


<!-- ##### FUNCTION g_printf ##### -->
<para>

</para>

@format: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION g_vprintf ##### -->
<para>

</para>

@format: 
@args: 
@Returns: 


<!-- ##### FUNCTION g_fprintf ##### -->
<para>

</para>

@file: 
@format: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION g_vfprintf ##### -->
<para>

</para>

@file: 
@format: 
@args: 
@Returns: 


<!-- ##### FUNCTION g_sprintf ##### -->
<para>

</para>

@string: 
@format: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION g_vsprintf ##### -->
<para>

</para>

@string: 
@format: 
@args: 
@Returns: 


<!-- ##### FUNCTION g_snprintf ##### -->
<para>
</para>

@string: 
@n: 
@format: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION g_vsnprintf ##### -->
<para>
</para>

@string: 
@n: 
@format: 
@args: 
@Returns: 


<!-- ##### FUNCTION g_vasprintf ##### -->
<para>

</para>

@string: 
@format: 
@args: 
@Returns: 


<!-- ##### FUNCTION g_printf_string_upper_bound ##### -->
<para>
Calculates the maximum space needed to store the output of the sprintf() function.
</para>

@format: the format string. See the printf() documentation.
@args: the parameters to be inserted into the format string.
@Returns: the maximum space needed to store the formatted string.


<!-- ##### FUNCTION g_ascii_isalnum ##### -->
<para>
Determines whether a character is alphanumeric.
</para>
<para>
Unlike the standard C library isalnum() function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to cast to #guchar before passing a 
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII alphanumeric character


<!-- ##### FUNCTION g_ascii_isalpha ##### -->
<para>
Determines whether a character is alphabetic (i.e. a letter).
</para>
<para>
Unlike the standard C library isalpha() function, this only
recognizes standard ASCII letters and ignores the locale, returning
%FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to cast to #guchar before passing a 
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII alphabetic character


<!-- ##### FUNCTION g_ascii_iscntrl ##### -->
<para>
Determines whether a character is a control character.
</para>
<para>
Unlike the standard C library iscntrl() function, this only
recognizes standard ASCII control characters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to cast to #guchar before passing a 
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII control character.


<!-- ##### FUNCTION g_ascii_isdigit ##### -->
<para>
Determines whether a character is digit (0-9).
</para>
<para>
Unlike the standard C library isdigit() function,
this takes a <type>char</type>, not an <type>int</type>, so don't call it
on %EOF but no need to cast to #guchar before passing a possibly
non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII digit.


<!-- ##### FUNCTION g_ascii_isgraph ##### -->
<para>
Determines whether a character is a printing character and not a space.
</para>
<para>
Unlike the standard C library isgraph() function, 
this only recognizes standard ASCII characters and ignores the locale, 
returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to cast to #guchar before passing a 
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII printing character other than space.


<!-- ##### FUNCTION g_ascii_islower ##### -->
<para>
Determines whether a character is an ASCII lower case letter.
</para>
<para>
Unlike the standard C library islower() function, 
this only recognizes standard ASCII letters and ignores the locale,
returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to worry about casting to #guchar 
before passing a possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII lower case letter


<!-- ##### FUNCTION g_ascii_isprint ##### -->
<para>
Determines whether a character is a printing character.
</para>
<para>
Unlike the standard C library isprint() function, 
this only recognizes standard ASCII characters and ignores the locale, 
returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to cast to #guchar before passing a 
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII printing character.


<!-- ##### FUNCTION g_ascii_ispunct ##### -->
<para>
Determines whether a character is a punctuation character.
</para>
<para>
Unlike the standard C library ispunct() function, 
this only recognizes standard ASCII letters and ignores the locale, 
returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to cast to #guchar before passing a 
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII punctuation character.


<!-- ##### FUNCTION g_ascii_isspace ##### -->
<para>
Determines whether a character is a white-space character.
</para>
<para>
Unlike the standard C library isspace() function, 
this only recognizes standard ASCII white-space and ignores the locale, 
returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to cast to #guchar before passing a 
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII white-space character


<!-- ##### FUNCTION g_ascii_isupper ##### -->
<para>
Determines whether a character is an ASCII upper case letter.
</para>
<para>
Unlike the standard C library isupper() function, 
this only recognizes standard ASCII letters and ignores the locale, 
returning %FALSE for all non-ASCII characters. Also unlike the standard
library function, this takes a <type>char</type>, not an <type>int</type>, 
so don't call it on %EOF but no need to worry about casting to #guchar 
before passing a possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII upper case letter


<!-- ##### FUNCTION g_ascii_isxdigit ##### -->
<para>
Determines whether a character is a hexadecimal-digit character.
</para>
<para>
Unlike the standard C library isxdigit() function,
this takes a <type>char</type>, not an <type>int</type>, so
don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
</para>

@c: any character
@Returns: %TRUE if @c is an ASCII hexadecimal-digit character.


<!-- ##### FUNCTION g_ascii_digit_value ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_ascii_xdigit_value ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strcasecmp ##### -->
<para>

</para>

@s1: 
@s2: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strncasecmp ##### -->
<para>

</para>

@s1: 
@s2: 
@n: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strup ##### -->
<para>

</para>

@str: 
@len: 
@Returns: 


<!-- ##### FUNCTION g_ascii_strdown ##### -->
<para>

</para>

@str: 
@len: 
@Returns: 


<!-- ##### FUNCTION g_ascii_tolower ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_ascii_toupper ##### -->
<para>

</para>

@c: 
@Returns: 


<!-- ##### FUNCTION g_string_ascii_up ##### -->
<para>

</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_string_ascii_down ##### -->
<para>

</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_strup ##### -->
<para>
</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_strdown ##### -->
<para>
</para>

@string: 
@Returns: 


<!-- ##### FUNCTION g_strcasecmp ##### -->
<para>
</para>

@s1: 
@s2: 
@Returns: 


<!-- ##### FUNCTION g_strncasecmp ##### -->
<para>
</para>

@s1: 
@s2: 
@n: 
@Returns: 


<!-- ##### FUNCTION g_strreverse ##### -->
<para>
Reverses all of the bytes in a string.
For example, <literal>g_strreverse ("abcdef")</literal> will result in "fedcba".
</para>
<para>
Note that g_strreverse() doesn't work on UTF-8 strings containing multibyte characters. 
For that purpose, use g_utf8_strreverse().
</para>

@string: the string to reverse.
@Returns: the same pointer passed in as @string.


<!-- ##### FUNCTION g_ascii_strtoull ##### -->
<para>

</para>

@nptr: 
@endptr: 
@base: 
@Returns: 


<!-- ##### MACRO G_ASCII_DTOSTR_BUF_SIZE ##### -->
<para>
A good size for a buffer to be passed into g_ascii_dtostr().
It is guaranteed to be enough for all output of that function on systems with
 64bit IEEE-compatible doubles.
</para>
<para>
The typical usage would be something like:
<informalexample><programlisting>
  char buf[G_ASCII_DTOSTR_BUF_SIZE];

  fprintf (out, "value=&percnt;s\n", g_ascii_dtostr (buf, sizeof (buf), value));
</programlisting></informalexample>
</para>



<!-- ##### FUNCTION g_ascii_strtod ##### -->
<para>

</para>

@nptr: 
@endptr: 
@Returns: 


<!-- ##### FUNCTION g_ascii_dtostr ##### -->
<para>

</para>

@buffer: 
@buf_len: 
@d: 
@Returns: 


<!-- ##### FUNCTION g_ascii_formatd ##### -->
<para>

</para>

@buffer: 
@buf_len: 
@format: 
@d: 
@Returns: 


<!-- ##### FUNCTION g_strtod ##### -->
<para>

</para>

@nptr: 
@endptr: 
@Returns: 


<!-- ##### FUNCTION g_strchug ##### -->
<para>
Removes leading whitespace from a string, by moving the rest of the
characters forward.
</para>
<para>
This function doesn't allocate or reallocate any memory; it modifies @string
in place. The pointer to @string is returned to allow the nesting of functions.
</para>
<para>
Also see g_strchomp() and g_strstrip().
</para>

@string: a string to remove the leading whitespace from.
@Returns: @string.


<!-- ##### FUNCTION g_strchomp ##### -->
<para>
Removes trailing whitespace from a string.
</para>
<para>
This function doesn't allocate or reallocate any memory; it modifies @string in
place. The pointer to @string is returned to allow the nesting of functions.
</para>
<para>
Also see g_strchug() and g_strstrip().
</para>

@string: a string to remove the trailing whitespace from.
@Returns: @string.


<!-- ##### MACRO g_strstrip ##### -->
<para>
Removes leading and trailing whitespace from a string. See g_strchomp() and
g_strchug().
</para>

@string: a string to remove the leading and trailing whitespace from.


<!-- ##### FUNCTION g_strdelimit ##### -->
<para>
Converts any delimiter characters in @string to @new_delimiter.
Any characters in @string which are found in @delimiters are changed
to the @new_delimiter character. Modifies @string in place, and returns 
@string itself, not a copy. The return value is to allow nesting such as
<literal>g_ascii_strup (g_strdelimit (str, "abc", '?'))</literal>.
</para>

@string: the string to convert.
@delimiters: a string containing the current delimiters, or %NULL to use the
standard delimiters defined in #G_STR_DELIMITERS.
@new_delimiter: the new delimiter character.
@Returns: @string.


<!-- ##### MACRO G_STR_DELIMITERS ##### -->
<para>
The standard delimiters, used in g_strdelimit().
</para>



<!-- ##### FUNCTION g_strescape ##### -->
<para>
Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
'&quot;' in the string @source by inserting a '\' before
them. Additionally all characters in the range 0x01-0x1F (everything
below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
replaced with a '\' followed by their octal representation. Characters
supplied in @exceptions are not escaped.
</para>

<para>
g_strcompress() does the reverse conversion.
</para>

@source: a string to escape.
@exceptions: a string of characters not to escape in @source.
@Returns: a newly-allocated copy of @source with certain
characters escaped. See above.


<!-- ##### FUNCTION g_strcompress ##### -->
<para>
Replaces all escaped characters with their one byte equivalent. It
does the reverse conversion of g_strescape(). 
</para>

@source: a string to compress.
@Returns: a newly-allocated copy of @source with all escaped 
character compressed.


<!-- ##### FUNCTION g_strcanon ##### -->
<para>
For each character in @string, if the character is not in @valid_chars,
replaces the character with @substitutor. Modifies @string in place, 
and return @string itself, not a copy. The return value is to allow
nesting such as <literal>g_ascii_strup (g_strcanon (str, "abc", '?'))</literal>.
</para>

@string: a nul-terminated array of bytes.
@valid_chars: bytes permitted in @string.
@substitutor: replacement character for disallowed bytes.
@Returns: @string.


<!-- ##### FUNCTION g_strsplit ##### -->
<para>
</para>

@string: 
@delimiter: 
@max_tokens: 
@Returns: 


<!-- ##### FUNCTION g_strsplit_set ##### -->
<para>

</para>

@string: 
@delimiters: 
@max_tokens: 
@Returns: 


<!-- ##### FUNCTION g_strfreev ##### -->
<para>

</para>

@str_array: 


<!-- ##### FUNCTION g_strconcat ##### -->
<para>
Concatenates all of the given strings into one long string.  The returned string
should be freed when no longer needed.  
</para>

<warning><para>
The variable argument list <emphasis>must</emphasis> end with %NULL. 
If you forget the %NULL, g_strconcat() will start appending
random memory junk to your string.
</para></warning>

@string1: The first string to add, which must not be %NULL.
@Varargs: a %NULL-terminated list of strings to append to the string.
@Returns: a newly-allocated string containing all the string arguments.


<!-- ##### FUNCTION g_strjoin ##### -->
<para>
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
</para>

@separator: a string to insert between each of the strings, or %NULL.
@Varargs: a %NULL-terminated list of strings to join.
@Returns: a newly-allocated string containing all of the strings joined
together, with @separator between them.


<!-- ##### FUNCTION g_strjoinv ##### -->
<para>
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
</para>

@separator: a string to insert between each of the strings, or %NULL.
@str_array: a %NULL-terminated array of strings to join.
@Returns: a newly-allocated string containing all of the strings joined
together, with @separator between them.


<!-- ##### FUNCTION g_strv_length ##### -->
<para>

</para>

@str_array: 
@Returns: 


<!-- ##### FUNCTION g_strerror ##### -->
<para>
Returns a string corresponding to the given error code, e.g. "no such process".
This function is included since not all platforms support the 
strerror() function.
</para>

@errnum: the system error number. See the standard C %errno
documentation.
@Returns: a string describing the error code.
If the error code is unknown, it returns "unknown error (&lt;code&gt;)".
The string can only be used until the next call to g_strerror().


<!-- ##### FUNCTION g_strsignal ##### -->
<para>
Returns a string describing the given signal, e.g. "Segmentation fault".
This function is included since not all platforms support the
strsignal() function.
</para>

@signum: the signal number. See the <literal>signal</literal>
documentation.
@Returns: a string describing the signal.
If the signal is unknown, it returns "unknown signal (&lt;signum&gt;)".
The string can only be used until the next call to g_strsignal().