![]() |
![]() |
![]() |
GLib Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <glib.h> #include <glib/gprintf.h> gchar* g_strdup (const gchar *str); gchar* g_strndup (const gchar *str, gsize n); gchar** g_strdupv (gchar **str_array); gchar* g_strnfill (gsize length, gchar fill_char); gchar* g_stpcpy (gchar *dest, const char *src); gchar * g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle); gchar * g_strrstr (const gchar *haystack, const gchar *needle); gchar * g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle); gboolean g_str_has_prefix (const gchar *str, const gchar *prefix); gboolean g_str_has_suffix (const gchar *str, const gchar *suffix); int g_strcmp0 (const char *str1, const char *str2); gsize g_strlcpy (gchar *dest, const gchar *src, gsize dest_size); gsize g_strlcat (gchar *dest, const gchar *src, gsize dest_size); gchar* g_strdup_printf (const gchar *format, ...); gchar* g_strdup_vprintf (const gchar *format, va_list args); gint g_printf (gchar const *format, ...); gint g_vprintf (gchar const *format, va_list args); gint g_fprintf (FILE *file, gchar const *format, ...); gint g_vfprintf (FILE *file, gchar const *format, va_list args); gint g_sprintf (gchar *string, gchar const *format, ...); gint g_vsprintf (gchar *string, gchar const *format, va_list args); gint g_snprintf (gchar *string, gulong n, gchar const *format, ...); gint g_vsnprintf (gchar *string, gulong n, gchar const *format, va_list args); gint g_vasprintf (gchar **string, gchar const *format, va_list args); gsize g_printf_string_upper_bound (const gchar *format, va_list args); gboolean g_ascii_isalnum (gchar c); gboolean g_ascii_isalpha (gchar c); gboolean g_ascii_iscntrl (gchar c); gboolean g_ascii_isdigit (gchar c); gboolean g_ascii_isgraph (gchar c); gboolean g_ascii_islower (gchar c); gboolean g_ascii_isprint (gchar c); gboolean g_ascii_ispunct (gchar c); gboolean g_ascii_isspace (gchar c); gboolean g_ascii_isupper (gchar c); gboolean g_ascii_isxdigit (gchar c); gint g_ascii_digit_value (gchar c); gint g_ascii_xdigit_value (gchar c); gint g_ascii_strcasecmp (const gchar *s1, const gchar *s2); gint g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n); gchar* g_ascii_strup (const gchar *str, gssize len); gchar* g_ascii_strdown (const gchar *str, gssize len); gchar g_ascii_tolower (gchar c); gchar g_ascii_toupper (gchar c); GString* g_string_ascii_up (GString *string); GString* g_string_ascii_down (GString *string); gchar* g_strup (gchar *string); gchar* g_strdown (gchar *string); gint g_strcasecmp (const gchar *s1, const gchar *s2); gint g_strncasecmp (const gchar *s1, const gchar *s2, guint n); gchar* g_strreverse (gchar *string); gint64 g_ascii_strtoll (const gchar *nptr, gchar **endptr, guint base); guint64 g_ascii_strtoull (const gchar *nptr, gchar **endptr, guint base); #define G_ASCII_DTOSTR_BUF_SIZE gdouble g_ascii_strtod (const gchar *nptr, gchar **endptr); gchar * g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d); gchar * g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d); gdouble g_strtod (const gchar *nptr, gchar **endptr); gchar* g_strchug (gchar *string); gchar* g_strchomp (gchar *string); #define g_strstrip ( string ) gchar* g_strdelimit (gchar *string, const gchar *delimiters, gchar new_delimiter); #define G_STR_DELIMITERS gchar* g_strescape (const gchar *source, const gchar *exceptions); gchar* g_strcompress (const gchar *source); gchar* g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor); gchar** g_strsplit (const gchar *string, const gchar *delimiter, gint max_tokens); gchar ** g_strsplit_set (const gchar *string, const gchar *delimiters, gint max_tokens); void g_strfreev (gchar **str_array); gchar* g_strconcat (const gchar *string1, ...); gchar* g_strjoin (const gchar *separator, ...); gchar* g_strjoinv (const gchar *separator, gchar **str_array); guint g_strv_length (gchar **str_array); const gchar* g_strerror (gint errnum); const gchar* g_strsignal (gint signum);
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.
gchar* g_strdup (const gchar *str);
Duplicates a string. If str
is NULL
it returns NULL
.
The returned string should be freed with g_free()
when no longer needed.
|
the string to duplicate |
Returns : |
a newly-allocated copy of str
|
gchar* g_strndup (const gchar *str, gsize n);
Duplicates the first n
bytes of a string, returning a newly-allocated
buffer n
+ 1 bytes long which will always be nul-terminated.
If str
is less than n
bytes long the buffer is padded with nuls.
If str
is NULL
it returns NULL
.
The returned value should be freed when no longer needed.
To copy a number of characters from a UTF-8 encoded string, use
g_utf8_strncpy()
instead.
|
the string to duplicate |
|
the maximum number of bytes to copy from str
|
Returns : |
a newly-allocated buffer containing the first n bytes
of str , nul-terminated
|
gchar** g_strdupv (gchar **str_array);
Copies NULL
-terminated array of strings. The copy is a deep copy;
the new array should be freed by first freeing each string, then
the array itself. g_strfreev()
does this for you. If called
on a NULL
value, g_strdupv()
simply returns NULL
.
gchar* g_strnfill (gsize length, gchar fill_char);
Creates a new string length
bytes long filled with fill_char
.
The returned string should be freed when no longer needed.
|
the length of the new string |
|
the byte to fill the string with |
Returns : |
a newly-allocated string filled the fill_char
|
gchar* g_stpcpy (gchar *dest, const char *src);
Copies a nul-terminated string into the dest buffer, include the trailing nul, and return a pointer to the trailing nul byte. This is useful for concatenating multiple strings together without having to repeatedly scan for the end.
|
destination buffer. |
|
source string. |
Returns : |
a pointer to trailing nul byte. |
gchar * g_strstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle);
Searches the string haystack
for the first occurrence
of the string needle
, limiting the length of the search
to haystack_len
.
|
a string. |
|
the maximum length of haystack . Note that -1 is
a valid length, if haystack is nul-terminated, meaning it will
search through the whole string.
|
|
the string to search for. |
Returns : |
a pointer to the found occurrence, or
NULL if not found.
|
gchar * g_strrstr (const gchar *haystack, const gchar *needle);
Searches the string haystack
for the last occurrence
of the string needle
.
|
a nul-terminated string. |
|
the nul-terminated string to search for. |
Returns : |
a pointer to the found occurrence, or
NULL if not found.
|
gchar * g_strrstr_len (const gchar *haystack, gssize haystack_len, const gchar *needle);
Searches the string haystack
for the last occurrence
of the string needle
, limiting the length of the search
to haystack_len
.
|
a nul-terminated string. |
|
the maximum length of haystack .
|
|
the nul-terminated string to search for. |
Returns : |
a pointer to the found occurrence, or
NULL if not found.
|
gboolean g_str_has_prefix (const gchar *str, const gchar *prefix);
Looks whether the string str
begins with prefix
.
|
a nul-terminated string. |
|
the nul-terminated prefix to look for. |
Returns : |
TRUE if str begins with prefix , FALSE otherwise.
|
Since 2.2
gboolean g_str_has_suffix (const gchar *str, const gchar *suffix);
Looks whether the string str
ends with suffix
.
|
a nul-terminated string. |
|
the nul-terminated suffix to look for. |
Returns : |
TRUE if str end with suffix , FALSE otherwise.
|
Since 2.2
int g_strcmp0 (const char *str1, const char *str2);
Compares str1
and str2
like strcmp()
. Handles NULL
gracefully by sorting it before non-NULL
strings.
|
a C string or NULL
|
|
another C string or NULL
|
Returns : |
-1, 0 or 1, if str1 is <, == or > than str2 .
|
Since 2.16
gsize g_strlcpy (gchar *dest, const gchar *src, gsize dest_size);
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.
At most dest_size - 1 characters will be copied. Always nul-terminates
(unless dest_size == 0). This function does not
allocate memory. Unlike strncpy()
, this function doesn't pad dest (so
it's often faster). It returns the size of the attempted result,
strlen (src), so if retval
>= dest_size
, truncation occurred.
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.
|
destination buffer |
|
source buffer |
|
length of dest in bytes
|
Returns : |
length of src
|
gsize g_strlcat (gchar *dest, const gchar *src, gsize dest_size);
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
.
At most dest_size - 1 characters will be copied. Unlike strncat, dest_size is the full size of dest, not the space left over. This function does NOT allocate memory. This always NUL terminates (unless siz == 0 or there were no NUL characters in the dest_size characters of dest to start with).
|
destination buffer, already containing one nul-terminated string |
|
source buffer |
|
length of dest buffer in bytes (not length of existing string
inside dest )
|
Returns : |
size of attempted result, which is
MIN (dest_size, strlen (original dest)) + strlen (src),
so if retval >= dest_size, truncation occurred.
NoteCaveat: this is supposedly a more secure alternative to
|
gchar* g_strdup_printf (const gchar *format, ...);
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 with g_free()
when no
longer needed.
|
a standard printf() format string, but notice
string precision pitfalls
|
|
the parameters to insert into the format string |
Returns : |
a newly-allocated string holding the result |
gchar* g_strdup_vprintf (const gchar *format, va_list args);
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 with g_free()
when
no longer needed.
See also g_vasprintf()
, which offers the same functionality, but
additionally returns the length of the allocated string.
|
a standard printf() format string, but notice
string precision pitfalls
|
|
the list of parameters to insert into the format string |
Returns : |
a newly-allocated string holding the result |
gint g_printf (gchar const *format, ...);
An implementation of the standard printf()
function which supports
positional parameters, as specified in the Single Unix Specification.
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the arguments to insert in the output. |
Returns : |
the number of bytes printed. |
Since 2.2
gint g_vprintf (gchar const *format, va_list args);
An implementation of the standard vprintf()
function which supports
positional parameters, as specified in the Single Unix Specification.
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the list of arguments to insert in the output. |
Returns : |
the number of bytes printed. |
Since 2.2
gint g_fprintf (FILE *file, gchar const *format, ...);
An implementation of the standard fprintf()
function which supports
positional parameters, as specified in the Single Unix Specification.
|
the stream to write to. |
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the arguments to insert in the output. |
Returns : |
the number of bytes printed. |
Since 2.2
gint g_vfprintf (FILE *file, gchar const *format, va_list args);
An implementation of the standard fprintf()
function which supports
positional parameters, as specified in the Single Unix Specification.
|
the stream to write to. |
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the list of arguments to insert in the output. |
Returns : |
the number of bytes printed. |
Since 2.2
gint g_sprintf (gchar *string, gchar const *format, ...);
An implementation of the standard sprintf()
function which supports
positional parameters, as specified in the Single Unix Specification.
|
A pointer to a memory buffer to contain the resulting string. It is up to the caller to ensure that the allocated buffer is large enough to hold the formatted result |
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the arguments to insert in the output. |
Returns : |
the number of bytes printed. |
Since 2.2
gint g_vsprintf (gchar *string, gchar const *format, va_list args);
An implementation of the standard vsprintf()
function which supports
positional parameters, as specified in the Single Unix Specification.
|
the buffer to hold the output. |
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the list of arguments to insert in the output. |
Returns : |
the number of bytes printed. |
Since 2.2
gint g_snprintf (gchar *string, gulong n, gchar const *format, ...);
A safer form of the standard sprintf()
function. The output is guaranteed
to not exceed n
characters (including the terminating nul character), so
it is easy to ensure that a buffer overflow cannot occur.
See also g_strdup_printf()
.
In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string.
The return value of g_snprintf()
conforms to the snprintf()
function as standardized in ISO C99. Note that this is different from
traditional snprintf()
, which returns the length of the output string.
The format string may contain positional parameters, as specified in the Single Unix Specification.
|
the buffer to hold the output. |
|
the maximum number of bytes to produce (including the terminating nul character). |
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the arguments to insert in the output. |
Returns : |
the number of bytes which would be produced if the buffer was large enough. |
gint g_vsnprintf (gchar *string, gulong n, gchar const *format, va_list args);
A safer form of the standard vsprintf()
function. The output is guaranteed
to not exceed n
characters (including the terminating nul character), so
it is easy to ensure that a buffer overflow cannot occur.
See also g_strdup_vprintf()
.
In versions of GLib prior to 1.2.3, this function may return -1 if the output was truncated, and the truncated string may not be nul-terminated. In versions prior to 1.3.12, this function returns the length of the output string.
The return value of g_vsnprintf()
conforms to the vsnprintf()
function
as standardized in ISO C99. Note that this is different from traditional
vsnprintf()
, which returns the length of the output string.
The format string may contain positional parameters, as specified in the Single Unix Specification.
|
the buffer to hold the output. |
|
the maximum number of bytes to produce (including the terminating nul character). |
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the list of arguments to insert in the output. |
Returns : |
the number of bytes which would be produced if the buffer was large enough. |
gint g_vasprintf (gchar **string, gchar const *format, va_list args);
An implementation of the GNU vasprintf()
function which supports
positional parameters, as specified in the Single Unix Specification.
This function is similar to g_vsprintf()
, except that it allocates a
string to hold the output, instead of putting the output in a buffer
you allocate in advance.
|
the return location for the newly-allocated string. |
|
a standard printf() format string, but notice
string precision pitfalls.
|
|
the list of arguments to insert in the output. |
Returns : |
the number of bytes printed. |
Since 2.4
gsize g_printf_string_upper_bound (const gchar *format, va_list args);
Calculates the maximum space needed to store the output of the sprintf()
function.
|
the format string. See the printf() documentation.
|
|
the parameters to be inserted into the format string. |
Returns : |
the maximum space needed to store the formatted string. |
gboolean g_ascii_isalnum (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII alphanumeric character
|
gboolean g_ascii_isalpha (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII alphabetic character
|
gboolean g_ascii_iscntrl (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII control character.
|
gboolean g_ascii_isdigit (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII digit.
|
gboolean g_ascii_isgraph (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII printing character other than space.
|
gboolean g_ascii_islower (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII lower case letter
|
gboolean g_ascii_isprint (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII printing character.
|
gboolean g_ascii_ispunct (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII punctuation character.
|
gboolean g_ascii_isspace (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII white-space character
|
gboolean g_ascii_isupper (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII upper case letter
|
gboolean g_ascii_isxdigit (gchar c);
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.
|
any character |
Returns : |
%TRUE if c is an ASCII hexadecimal-digit character.
|
gint g_ascii_digit_value (gchar c);
Determines the numeric value of a character as a decimal
digit. Differs from g_unichar_digit_value()
because it takes
a char, so there's no worry about sign extension if characters
are signed.
|
an ASCII character. |
Returns : |
If c is a decimal digit (according to
g_ascii_isdigit() ), its numeric value. Otherwise, -1.
|
gint g_ascii_xdigit_value (gchar c);
Determines the numeric value of a character as a hexidecimal
digit. Differs from g_unichar_xdigit_value()
because it takes
a char, so there's no worry about sign extension if characters
are signed.
|
an ASCII character. |
Returns : |
If c is a hex digit (according to
g_ascii_isxdigit() ), its numeric value. Otherwise, -1.
|
gint g_ascii_strcasecmp (const gchar *s1, const gchar *s2);
Compare two strings, ignoring the case of ASCII characters.
Unlike the BSD strcasecmp()
function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
bytes as if they are not letters.
This function should be used only on strings that are known to be in encodings where the bytes corresponding to ASCII letters always represent themselves. This includes UTF-8 and the ISO-8859-* charsets, but not for instance double-byte encodings like the Windows Codepage 932, where the trailing bytes of double-byte characters include all ASCII letters. If you compare two CP932 strings using this function, you will get false matches.
|
string to compare with s2 .
|
|
string to compare with s1 .
|
Returns : |
0 if the strings match, a negative value if s1 < s2 ,
or a positive value if s1 > s2 .
|
gint g_ascii_strncasecmp (const gchar *s1, const gchar *s2, gsize n);
Compare s1
and s2
, ignoring the case of ASCII characters and any
characters after the first n
in each string.
Unlike the BSD strcasecmp()
function, this only recognizes standard
ASCII letters and ignores the locale, treating all non-ASCII
characters as if they are not letters.
The same warning as in g_ascii_strcasecmp()
applies: Use this
function only on strings known to be in encodings where bytes
corresponding to ASCII letters always represent themselves.
|
string to compare with s2 .
|
|
string to compare with s1 .
|
|
number of characters to compare. |
Returns : |
0 if the strings match, a negative value if s1 < s2 ,
or a positive value if s1 > s2 .
|
gchar* g_ascii_strup (const gchar *str, gssize len);
Converts all lower case ASCII letters to upper case ASCII letters.
|
a string. |
|
length of str in bytes, or -1 if str is nul-terminated.
|
Returns : |
a newly allocated string, with all the lower case
characters in str converted to upper case, with
semantics that exactly match g_ascii_toupper() . (Note
that this is unlike the old g_strup() , which modified
the string in place.)
|
gchar* g_ascii_strdown (const gchar *str, gssize len);
Converts all upper case ASCII letters to lower case ASCII letters.
|
a string. |
|
length of str in bytes, or -1 if str is nul-terminated.
|
Returns : |
a newly-allocated string, with all the upper case
characters in str converted to lower case, with
semantics that exactly match g_ascii_tolower() . (Note
that this is unlike the old g_strdown() , which modified
the string in place.)
|
gchar g_ascii_tolower (gchar c);
Convert a character to ASCII lower case.
Unlike the standard C library tolower()
function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are lower case
letters in a particular character set. Also unlike the standard
library function, this takes and returns 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.
|
any character. |
Returns : |
the result of converting c to lower case.
If c is not an ASCII upper case letter,
c is returned unchanged.
|
gchar g_ascii_toupper (gchar c);
Convert a character to ASCII upper case.
Unlike the standard C library toupper()
function, this only
recognizes standard ASCII letters and ignores the locale, returning
all non-ASCII characters unchanged, even if they are upper case
letters in a particular character set. Also unlike the standard
library function, this takes and returns 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.
|
any character. |
Returns : |
the result of converting c to upper case.
If c is not an ASCII lower case letter,
c is returned unchanged.
|
GString* g_string_ascii_up (GString *string);
Converts all lower case ASCII letters to upper case ASCII letters.
|
a GString |
Returns : |
passed-in string pointer, with all the lower case
characters converted to upper case in place, with
semantics that exactly match g_ascii_toupper() .
|
GString* g_string_ascii_down (GString *string);
Converts all upper case ASCII letters to lower case ASCII letters.
|
a GString |
Returns : |
passed-in string pointer, with all the upper case
characters converted to lower case in place, with
semantics that exactly match g_ascii_tolower() .
|
gchar* g_strup (gchar *string);
g_strup
has been deprecated since version 2.2 and should not be used in newly-written code. This function is totally broken for the reasons discussed
in the g_strncasecmp()
docs - use g_ascii_strup()
or g_utf8_strup()
instead.
Converts a string to upper case.
|
the string to convert. |
Returns : |
the string |
gchar* g_strdown (gchar *string);
g_strdown
has been deprecated since version 2.2 and should not be used in newly-written code. This function is totally broken for the reasons discussed
in the g_strncasecmp()
docs - use g_ascii_strdown()
or g_utf8_strdown()
instead.
Converts a string to lower case.
|
the string to convert. |
Returns : |
the string |
gint g_strcasecmp (const gchar *s1, const gchar *s2);
g_strcasecmp
has been deprecated since version 2.2 and should not be used in newly-written code. See g_strncasecmp()
for a discussion of why this function
is deprecated and how to replace it.
A case-insensitive string comparison, corresponding to the standard
strcasecmp()
function on platforms which support it.
|
a string. |
|
a string to compare with s1 .
|
Returns : |
0 if the strings match, a negative value if s1 < s2 ,
or a positive value if s1 > s2 .
|
gint g_strncasecmp (const gchar *s1, const gchar *s2, guint n);
g_strncasecmp
has been deprecated since version 2.2 and should not be used in newly-written code. The problem with g_strncasecmp()
is that it does the
comparison by calling toupper()
/tolower()
. These functions are
locale-specific and operate on single bytes. However, it is impossible
to handle things correctly from an I18N standpoint by operating on
bytes, since characters may be multibyte. Thus g_strncasecmp()
is
broken if your string is guaranteed to be ASCII, since it's
locale-sensitive, and it's broken if your string is localized, since
it doesn't work on many encodings at all, including UTF-8, EUC-JP,
etc.
There are therefore two replacement functions: g_ascii_strncasecmp()
,
which only works on ASCII and is not locale-sensitive, and
g_utf8_casefold()
, which is good for case-insensitive sorting of UTF-8.
A case-insensitive string comparison, corresponding to the standard
strncasecmp()
function on platforms which support it.
It is similar to g_strcasecmp()
except it only compares the first n
characters of the strings.
|
a string. |
|
a string to compare with s1 .
|
|
the maximum number of characters to compare. |
Returns : |
0 if the strings match, a negative value if s1 < s2 ,
or a positive value if s1 > s2 .
|
gchar* g_strreverse (gchar *string);
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()
.
|
the string to reverse |
Returns : |
the same pointer passed in as string
|
gint64 g_ascii_strtoll (const gchar *nptr, gchar **endptr, guint base);
Converts a string to a gint64 value.
This function behaves like the standard strtoll()
function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system strtoll()
function.
If the correct value would cause overflow, G_MAXINT64
or G_MININT64
is returned, and ERANGE
is stored in errno
. If the base is
outside the valid range, zero is returned, and EINVAL
is stored
in errno
. If the string conversion fails, zero is returned, and
endptr
returns nptr
(if endptr
is non-NULL
).
|
the string to convert to a numeric value. |
|
if non-NULL , it returns the character after
the last character used in the conversion.
|
|
to be used for the conversion, 2..36 or 0 |
Returns : |
the gint64 value or zero on error. |
Since 2.12
guint64 g_ascii_strtoull (const gchar *nptr, gchar **endptr, guint base);
Converts a string to a guint64 value.
This function behaves like the standard strtoull()
function
does in the C locale. It does this without actually
changing the current locale, since that would not be
thread-safe.
This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system strtoull()
function.
If the correct value would cause overflow, G_MAXUINT64
is returned, and ERANGE
is stored in errno
. If the base is
outside the valid range, zero is returned, and EINVAL
is stored
in errno
. If the string conversion fails, zero is returned, and
endptr
returns nptr
(if endptr
is non-NULL
).
|
the string to convert to a numeric value. |
|
if non-NULL , it returns the character after
the last character used in the conversion.
|
|
to be used for the conversion, 2..36 or 0 |
Returns : |
the guint64 value or zero on error. |
Since 2.2
#define G_ASCII_DTOSTR_BUF_SIZE (29 + 10)
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));
gdouble g_ascii_strtod (const gchar *nptr, gchar **endptr);
Converts a string to a gdouble value.
This function behaves like the standard strtod()
function
does in the C locale. It does this without actually changing
the current locale, since that would not be thread-safe.
A limitation of the implementation is that this function
will still accept localized versions of infinities and NANs.
This function is typically used when reading configuration
files or other non-user input that should be locale independent.
To handle input from the user you should normally use the
locale-sensitive system strtod()
function.
To convert from a gdouble to a string in a locale-insensitive
way, use g_ascii_dtostr()
.
If the correct value would cause overflow, plus or minus HUGE_VAL
is returned (according to the sign of the value), and ERANGE
is
stored in errno
. If the correct value would cause underflow,
zero is returned and ERANGE
is stored in errno
.
This function resets errno
before calling strtod()
so that
you can reliably detect overflow and underflow.
gchar * g_ascii_dtostr (gchar *buffer, gint buf_len, gdouble d);
Converts a gdouble to a string, using the '.' as decimal point.
This functions generates enough precision that converting
the string back using g_ascii_strtod()
gives the same machine-number
(on machines with IEEE compatible 64bit doubles). It is
guaranteed that the size of the resulting string will never
be larger than G_ASCII_DTOSTR_BUF_SIZE
bytes.
|
A buffer to place the resulting string in |
|
The length of the buffer. |
|
The gdouble to convert |
Returns : |
The pointer to the buffer with the converted string. |
gchar * g_ascii_formatd (gchar *buffer, gint buf_len, const gchar *format, gdouble d);
Converts a gdouble to a string, using the '.' as
decimal point. To format the number you pass in
a printf()
-style format string. Allowed conversion
specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'.
If you just want to want to serialize the value into a
string, use g_ascii_dtostr()
.
|
A buffer to place the resulting string in |
|
The length of the buffer. |
|
The printf() -style format to use for the
code to use for converting.
|
|
The gdouble to convert |
Returns : |
The pointer to the buffer with the converted string. |
gdouble g_strtod (const gchar *nptr, gchar **endptr);
Converts a string to a gdouble value.
It calls the standard strtod()
function to handle the conversion, but
if the string is not completely converted it attempts the conversion
again with g_ascii_strtod()
, and returns the best match.
This function should seldomly be used. The normal situation when reading
numbers not for human consumption is to use g_ascii_strtod()
. Only when
you know that you must expect both locale formatted and C formatted numbers
should you use this. Make sure that you don't pass strings such as comma
separated lists of values, since the commas may be interpreted as a decimal
point in some locales, causing unexpected results.
gchar* g_strchug (gchar *string);
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()
.
|
a string to remove the leading whitespace from. |
Returns : |
@string. |
gchar* g_strchomp (gchar *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()
.
|
a string to remove the trailing whitespace from. |
Returns : |
@string. |
#define g_strstrip( string )
Removes leading and trailing whitespace from a string. See g_strchomp()
and
g_strchug()
.
|
a string to remove the leading and trailing whitespace from. |
gchar* g_strdelimit (gchar *string, const gchar *delimiters, gchar new_delimiter);
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", '?'))
.
|
the string to convert. |
|
a string containing the current delimiters, or NULL to use the
standard delimiters defined in G_STR_DELIMITERS.
|
|
the new delimiter character. |
Returns : |
@string. |
#define G_STR_DELIMITERS "_-|> <."
The standard delimiters, used in g_strdelimit()
.
gchar* g_strescape (const gchar *source, const gchar *exceptions);
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.
|
a string to escape. |
|
a string of characters not to escape in source .
|
Returns : |
a newly-allocated copy of source with certain
characters escaped. See above.
|
gchar* g_strcompress (const gchar *source);
Replaces all escaped characters with their one byte equivalent. It
does the reverse conversion of g_strescape()
.
|
a string to compress. |
Returns : |
a newly-allocated copy of source with all escaped
character compressed.
|
gchar* g_strcanon (gchar *string, const gchar *valid_chars, gchar substitutor);
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", '?'))
.
|
a nul-terminated array of bytes. |
|
bytes permitted in string .
|
|
replacement character for disallowed bytes. |
Returns : |
@string. |
gchar** g_strsplit (const gchar *string, const gchar *delimiter, gint max_tokens);
Splits a string into a maximum of max_tokens
pieces, using the given
delimiter
. If max_tokens
is reached, the remainder of string
is appended
to the last token.
As a special case, the result of splitting the empty string "" is an empty
vector, not a vector containing a single string. The reason for this
special case is that being able to represent a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling g_strsplit()
.
|
a string to split. |
|
a string which specifies the places at which to split the string.
The delimiter is not included in any of the resulting strings, unless
max_tokens is reached.
|
|
the maximum number of pieces to split string into. If this is
less than 1, the string is split completely.
|
Returns : |
a newly-allocated NULL -terminated array of strings. Use
g_strfreev() to free it.
|
gchar ** g_strsplit_set (const gchar *string, const gchar *delimiters, gint max_tokens);
Splits string
into a number of tokens not containing any of the characters
in delimiter
. A token is the (possibly empty) longest string that does not
contain any of the characters in delimiters
. If max_tokens
is reached, the
remainder is appended to the last token.
For example the result of g_strsplit_set ("abc:def/ghi", ":/", -1) is a
NULL
-terminated vector containing the three strings "abc", "def",
and "ghi".
The result if g_strsplit_set (":def/ghi:", ":/", -1) is a NULL
-terminated
vector containing the four strings "", "def", "ghi", and "".
As a special case, the result of splitting the empty string "" is an empty
vector, not a vector containing a single string. The reason for this
special case is that being able to represent a empty vector is typically
more useful than consistent handling of empty elements. If you do need
to represent empty elements, you'll need to check for the empty string
before calling g_strsplit_set()
.
Note that this function works on bytes not characters, so it can't be used to delimit UTF-8 strings for anything but ASCII characters.
|
The string to be tokenized |
|
A nul-terminated string containing bytes that are used to split the string. |
|
The maximum number of tokens to split string into.
If this is less than 1, the string is split completely
|
Returns : |
a newly-allocated NULL -terminated array of strings. Use
g_strfreev() to free it.
|
Since 2.4
void g_strfreev (gchar **str_array);
Frees a NULL
-terminated array of strings, and the array itself.
If called on a NULL
value, g_strfreev()
simply returns.
|
a NULL -terminated array of strings to free.
|
gchar* g_strconcat (const gchar *string1, ...);
Concatenates all of the given strings into one long string.
The returned string should be freed with g_free()
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.
gchar* g_strjoin (const gchar *separator, ...);
Joins a number of strings together to form one long string, with the
optional separator
inserted between each of them. The returned string
should be freed with g_free()
.
gchar* g_strjoinv (const gchar *separator, gchar **str_array);
Joins a number of strings together to form one long string, with the
optional separator
inserted between each of them. The returned string
should be freed with g_free()
.
guint g_strv_length (gchar **str_array);
Returns the length of the given NULL
-terminated
string array str_array
.
|
a NULL -terminated array of strings.
|
Returns : |
length of str_array .
|
Since 2.6
const gchar* g_strerror (gint errnum);
Returns a string corresponding to the given error code, e.g.
"no such process". You should use this function in preference to
strerror()
, because it returns a string in UTF-8 encoding, and since
not all platforms support the strerror()
function.
|
the system error number. See the standard C errno
documentation
|
Returns : |
a UTF-8 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()
|
const gchar* g_strsignal (gint signum);
Returns a string describing the given signal, e.g. "Segmentation fault".
You should use this function in preference to strsignal()
, because it
returns a string in UTF-8 encoding, and since not all platforms support
the strsignal()
function.
|
the signal number. See the signal
documentation
|
Returns : |
a UTF-8 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()
|