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.
@str:
@Returns:
@str:
@n:
@Returns:
@str_array:
@Returns:
@length:
@fill_char:
@Returns:
@dest:
@src:
@Returns:
@haystack:
@haystack_len:
@needle:
@Returns:
@haystack:
@needle:
@Returns:
@haystack:
@haystack_len:
@needle:
@Returns:
@str:
@prefix:
@Returns:
@str:
@suffix:
@Returns:
@str1:
@str2:
@Returns:
@dest:
@src:
@dest_size:
@Returns:
@dest:
@src:
@dest_size:
@Returns:
@format:
@Varargs:
@Returns:
@format:
@args:
@Returns:
@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:
@str:
@len:
@Returns:
@c:
@Returns:
@c:
@Returns:
@string:
@Returns:
@string:
@Returns:
@string:
@Returns:
@string:
@Returns:
@s1:
@s2:
@Returns:
@s1:
@s2:
@n:
@Returns:
@string:
@Returns:
@nptr:
@endptr:
@base:
@Returns:
@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.
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.
Also see g_strchomp() and g_strstrip().
@string: a string to remove the leading whitespace from.
@Returns: @string.
Removes trailing whitespace from a string.
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.
Also see g_strchug() and g_strstrip().
@string: a string to remove the trailing whitespace from.
@Returns: @string.
Removes leading and trailing whitespace from a string. See g_strchomp() and
g_strchug().
@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:
@string1:
@Varargs:
@Returns:
@separator:
@Varargs:
@Returns:
@separator:
@str_array:
@Returns:
@str_array:
@Returns:
@errnum:
@Returns:
@signum:
@Returns: