String Utility Functions
various string-related functions.
This section describes a number of utility functions for creating,
duplicating, and manipulating strings.
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 gprintf.h which is not
included in glib.h (otherwise using
glib.h would drag in stdio.h), so
you'll have to explicitly include <glib/gprintf.h>
in order to use the GLib printf() functions.
While you may use the printf() functions to format UTF-8 strings, notice that
the precision of a %Ns parameter is interpreted as the
number of bytes, not characters 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 %Ns 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 %Ns.
If your intention is to format strings for a certain number of columns, then
%Ns is not a correct solution anyway, since it fails to take
wide characters (see g_unichar_iswide()) into account.
Duplicates a string.
If @str is %NULL it returns %NULL.
The returned string should be freed when no longer needed.
@str: the string to duplicate.
@Returns: a newly-allocated copy of @str.
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.
@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.
@str_array:
@Returns:
Creates a new string @length characters long filled with @fill_char.
The returned string should be freed when no longer needed.
@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.
@dest:
@src:
@Returns:
@haystack:
@haystack_len:
@needle:
@Returns:
@haystack:
@needle:
@Returns:
@haystack:
@haystack_len:
@needle:
@Returns:
@str:
@prefix:
@Returns:
@str:
@suffix:
@Returns:
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.
@dest: destination buffer
@src: source buffer
@dest_size: length of @dest in bytes
@Returns: length of @src
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.
@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
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.
@format: a standard printf() format string, but notice
string precision pitfalls.
@Varargs: the parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.
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.
See also g_vasprintf(), which offers the same functionality, but additionally
returns the length of the allocated string.
@format: a standard printf() format string, but notice
string precision pitfalls.
@args: the list of parameters to insert into the format string.
@Returns: a newly-allocated string holding the result.
@format:
@Varargs:
@Returns:
@format:
@args:
@Returns:
@file:
@format:
@Varargs:
@Returns:
@file:
@format:
@args:
@Returns:
@string:
@format:
@Varargs:
@Returns:
@string:
@format:
@args:
@Returns:
@string:
@n:
@format:
@Varargs:
@Returns:
@string:
@n:
@format:
@args:
@Returns:
@string:
@format:
@args:
@Returns:
Calculates the maximum space needed to store the output of the sprintf() function.
@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.
Determines whether a character is alphanumeric.
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 char, not an int,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII alphanumeric character
Determines whether a character is alphabetic (i.e. a letter).
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 char, not an int,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII alphabetic character
Determines whether a character is a control character.
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 char, not an int,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII control character.
Determines whether a character is digit (0-9).
Unlike the standard C library isdigit() function,
this takes a char, not an int, so don't call it
on %EOF but no need to cast to #guchar before passing a possibly
non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII digit.
Determines whether a character is a printing character and not a space.
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 char, not an int,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII printing character other than space.
Determines whether a character is an ASCII lower case letter.
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 char, not an int,
so don't call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII lower case letter
Determines whether a character is a printing character.
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 char, not an int,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII printing character.
Determines whether a character is a punctuation character.
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 char, not an int,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII punctuation character.
Determines whether a character is a white-space character.
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 char, not an int,
so don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII white-space character
Determines whether a character is an ASCII upper case letter.
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 char, not an int,
so don't call it on %EOF but no need to worry about casting to #guchar
before passing a possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII upper case letter
Determines whether a character is a hexadecimal-digit character.
Unlike the standard C library isxdigit() function,
this takes a char, not an int, so
don't call it on %EOF but no need to cast to #guchar before passing a
possibly non-ASCII character in.
@c: any character
@Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
@c:
@Returns:
@c:
@Returns:
@s1:
@s2:
@Returns:
@s1:
@s2:
@n:
@Returns:
@str:
@len:
@Returns:
@string:
@str:
@len:
@Returns:
@c:
@Returns:
@c:
@Returns:
@string:
@Returns:
@string:
@Returns:
@string:
@Returns:
@string:
@Returns:
@s1:
@s2:
@Returns:
@s1:
@s2:
@n:
@Returns:
Reverses all of the bytes in a string.
For example, g_strreverse ("abcdef") will result in "fedcba".
Note that g_strreverse() doesn't work on UTF-8 strings containing multibyte characters.
For that purpose, use g_utf8_strreverse().
@string: the string to reverse.
@Returns: the same pointer passed in as @string.
@nptr:
@endptr:
@base:
@Returns:
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.
The typical usage would be something like:
char buf[G_ASCII_DTOSTR_BUF_SIZE];
fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
@nptr:
@endptr:
@Returns:
@buffer:
@buf_len:
@d:
@Returns:
@buffer:
@buf_len:
@format:
@d:
@Returns:
@nptr:
@endptr:
@Returns:
Removes leading whitespace from a string, by moving the rest of the
characters forward.
@string: a string to remove the leading whitespace from.
@Returns: @string.
Removes trailing whitespace from a string.
@string: a string to remove the trailing whitespace from.
@Returns: @string.
Removes leading and trailing whitespace from a string.
@string: a string to remove the leading and trailing whitespace from.
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
g_ascii_strup (g_strdelimit (str, "abc", '?')).
@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.
The standard delimiters, used in g_strdelimit().
Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\' and
'"' 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.
g_strcompress() does the reverse conversion.
@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.
Replaces all escaped characters with their one byte equivalent. It
does the reverse conversion of g_strescape().
@source: a string to compress.
@Returns: a newly-allocated copy of @source with all escaped
character compressed.
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 g_ascii_strup (g_strcanon (str, "abc", '?')).
@string: a nul-terminated array of bytes.
@valid_chars: bytes permitted in @string.
@substitutor: replacement character for disallowed bytes.
@Returns: @string.
@string:
@delimiter:
@max_tokens:
@Returns:
@string:
@delimiters:
@max_tokens:
@Returns:
@str_array:
Concatenates all of the given strings into one long string. The returned string
should be freed when no longer needed.
The variable argument list must end with %NULL.
If you forget the %NULL, g_strconcat() will start appending
random memory junk to your string.
@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.
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
@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.
Joins a number of strings together to form one long string, with the optional
@separator inserted between each of them.
@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.
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.
@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 (<code>)".
The string can only be used until the next call to g_strerror().
Returns a string describing the given signal, e.g. "Segmentation fault".
This function is included since not all platforms support the
strsignal() function.
@signum: the signal number. See the signal
documentation.
@Returns: a string describing the signal.
If the signal is unknown, it returns "unknown signal (<signum>)".
The string can only be used until the next call to g_strsignal().