| Enumerator | Value | Description |
|---|---|---|
| G_ASCII_ALNUM | 1 << 0 | |
| G_ASCII_ALPHA | 1 << 1 | |
| G_ASCII_CNTRL | 1 << 2 | |
| G_ASCII_DIGIT | 1 << 3 | |
| G_ASCII_GRAPH | 1 << 4 | |
| G_ASCII_LOWER | 1 << 5 | |
| G_ASCII_PRINT | 1 << 6 | |
| G_ASCII_PUNCT | 1 << 7 | |
| G_ASCII_SPACE | 1 << 8 | |
| G_ASCII_UPPER | 1 << 9 | |
| G_ASCII_XDIGIT | 1 << 10 |
| IMPORT_C const guint16 *const * | _g_ascii_table | ( | ) |
| GLIB_VAR const guint16 *const | g_ascii_table |
g_ascii_tolower: : any character.
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.
Return value: the result of converting to lower case. If is not an ASCII upper case letter, is returned unchanged.
g_ascii_toupper: : any character.
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.
Return value: the result of converting to upper case. If is not an ASCII lower case letter, is returned unchanged.
g_ascii_digit_value: : an ASCII character.
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.
Return value: If is a decimal digit (according to g_ascii_isdigit()), its numeric value. Otherwise, -1.
g_ascii_xdigit_value: : an ASCII character.
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.
Return value: If is a hex digit (according to g_ascii_isxdigit()), its numeric value. Otherwise, -1.
g_strerror: : the system error number. See the standard C errno documentation
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.
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()
g_strsignal: : the signal number. See the <literal>signal</literal> documentation
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.
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()
g_strreverse: : the string to reverse
Reverses all of the bytes in a string. For example, <literal>g_strreverse ("abcdef")</literal> 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().
Returns: the same pointer passed in as
g_strlcpy: : destination buffer : source buffer : length of in bytes
Portability wrapper that calls strlcpy() on systems which have it, and emulates strlcpy() otherwise. Copies to ; is guaranteed to be nul-terminated; must be nul-terminated; 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 <emphasis>not</emphasis> 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 <note>
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.
</note>
Returns: length of
| >= | , truncation occurred. |
g_strlcat: : destination buffer, already containing one nul-terminated string : source buffer : length of buffer in bytes (not length of existing string inside )
Portability wrapper that calls strlcat() on systems which have it, and emulates it otherwise. Appends nul-terminated string to , guaranteeing nul-termination for . The total size of won't exceed .
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). Returns size of attempted result, which is MIN (dest_size, strlen (original dest)) + strlen (src), so if retval >= dest_size, truncation occurred.
<note>
Caveat: this is supposedly a more secure alternative to strcat() or strncat(), but for real security g_strconcat() is harder to mess up.
</note>
g_strstr_len: : a string. : the maximum length of . Note that -1 is a valid length, if is nul-terminated, meaning it will search through the whole string. : the string to search for.
Searches the string for the first occurrence of the string , limiting the length of the search to .
Return value: a pointer to the found occurrence, or NULL if not found.
g_strrstr: : a nul-terminated string. : the nul-terminated string to search for.
Searches the string for the last occurrence of the string .
Return value: a pointer to the found occurrence, or NULL if not found.
g_strrstr_len: : a nul-terminated string. : the maximum length of . : the nul-terminated string to search for.
Searches the string for the last occurrence of the string , limiting the length of the search to .
Return value: a pointer to the found occurrence, or NULL if not found.
g_str_has_suffix: : a nul-terminated string. : the nul-terminated suffix to look for.
Looks whether the string ends with .
Return value: TRUE if end with , FALSE otherwise.
Since: 2.2
g_str_has_prefix: : a nul-terminated string. : the nul-terminated prefix to look for.
Looks whether the string begins with .
Return value: TRUE if begins with , FALSE otherwise.
Since: 2.2
g_strtod: : the string to convert to a numeric value. : if non-NULL, it returns the character after the last character used in the conversion.
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.
Return value: the gdouble value.
g_ascii_strtod: : the string to convert to a numeric value. : if non-NULL, it returns the character after the last character used in the conversion.
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.
Return value: the gdouble value.
g_ascii_strtoull: : 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
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 returns (if is non-NULL).
Return value: the guint64 value or zero on error.
Since: 2.2
g_ascii_strtoll: : 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
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 returns (if is non-NULL).
Return value: the gint64 value or zero on error.
Since: 2.12
g_ascii_dtostr: : A buffer to place the resulting string in : The length of the buffer. : The gdouble to convert
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 bytes.
Return value: The pointer to the buffer with the converted string.
g_ascii_formatd: : 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
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().
Return value: The pointer to the buffer with the converted string.
g_ascii_strcasecmp: : string to compare with . : string to compare with .
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.
Return value: 0 if the strings match, a negative value if < , or a positive value if > .
g_ascii_strncasecmp: : string to compare with . : string to compare with . : number of characters to compare.
Compare and , ignoring the case of ASCII characters and any characters after the first 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.
Return value: 0 if the strings match, a negative value if < , or a positive value if > .
g_ascii_strdown: : a string. : length of in bytes, or -1 if is nul-terminated.
Converts all upper case ASCII letters to lower case ASCII letters.
Return value: a newly-allocated string, with all the upper case characters in 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.)
g_ascii_strup: : a string. : length of in bytes, or -1 if is nul-terminated.
Converts all lower case ASCII letters to upper case ASCII letters.
Return value: a newly allocated string, with all the lower case characters in 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.)
g_strcasecmp: : a string. : a string to compare with .
A case-insensitive string comparison, corresponding to the standard strcasecmp() function on platforms which support it.
Return value: 0 if the strings match, a negative value if < , or a positive value if > .
Deprecated:2.2: See g_strncasecmp() for a discussion of why this function is deprecated and how to replace it.
g_strncasecmp: : a string. : a string to compare with . : the maximum number of characters to compare.
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 characters of the strings.
Return value: 0 if the strings match, a negative value if < , or a positive value if > .
Deprecated:2.2: 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.
g_strdown: : the string to convert.
Converts a string to lower case.
Return value: the string
Deprecated:2.2: This function is totally broken for the reasons discussed in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() instead.
g_strup: : the string to convert.
Converts a string to upper case.
Return value: the string
Deprecated:2.2: This function is totally broken for the reasons discussed in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
g_strdup: : the string to duplicate
Duplicates a string. If is NULL it returns NULL. The returned string should be freed with g_free() when no longer needed.
Returns: a newly-allocated copy of
| IMPORT_C gchar | G_GNUC_MALLOC |
g_strdup_vprintf: : a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link> : the list of parameters to insert into the format string
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.
Returns: a newly-allocated string holding the result
g_strndup: : the string to duplicate : the maximum number of bytes to copy from
Duplicates the first bytes of a string, returning a newly-allocated buffer + 1 bytes long which will always be nul-terminated. If is less than bytes long the buffer is padded with nuls. If is NULL it returns NULL. The returned value should be freed when no longer needed.
<note>
To copy a number of characters from a UTF-8 encoded string, use g_utf8_strncpy() instead.
</note>
Returns: a newly-allocated buffer containing the first bytes of , nul-terminated
g_strnfill: : the length of the new string : the byte to fill the string with
Creates a new string bytes long filled with . The returned string should be freed when no longer needed.
Returns: a newly-allocated string filled the
g_strconcat: : the first string to add, which must not be NULL : a NULL-terminated list of strings to append to the string
Concatenates all of the given strings into one long string. The returned string should be freed with g_free() when no longer needed.
<warning>
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.
</warning>
Returns: a newly-allocated string containing all the string arguments
g_strjoin: : a string to insert between each of the strings, or NULL : a NULL-terminated list of strings to join
Joins a number of strings together to form one long string, with the optional inserted between each of them. The returned string should be freed with g_free().
Returns: a newly-allocated string containing all of the strings joined together, with between them
| IMPORT_C gpointer | g_memdup | ( | gconstpointer | mem, |
| guint | byte_size | |||
| ) | ||||
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 is reached. : the maximum number of pieces to split into. If this is less than 1, the string is split completely.
Splits a string into a maximum of pieces, using the given . If is reached, the remainder of 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().
Return value: a newly-allocated NULL-terminated array of strings. Use g_strfreev() to free it.
g_strsplit_set: : 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 into. If this is less than 1, the string is split completely
Splits into a number of tokens not containing any of the characters in . A token is the (possibly empty) longest string that does not contain any of the characters in . If 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.
Return value: a newly-allocated NULL-terminated array of strings. Use g_strfreev() to free it.
Since: 2.4
g_strjoinv: : a string to insert between each of the strings, or NULL : a NULL-terminated array of strings to join
Joins a number of strings together to form one long string, with the optional inserted between each of them. The returned string should be freed with g_free().
Returns: a newly-allocated string containing all of the strings joined together, with between them
| IMPORT_C void | g_strfreev | ( | gchar ** | str_array | ) |
g_strfreev: : a NULL-terminated array of strings to free.
Frees a NULL-terminated array of strings, and the array itself. If called on a NULL value, g_strfreev() simply returns.
g_strdupv: : NULL-terminated array of strings.
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.
Return value: a new NULL-terminated array of strings.
g_strv_length: : a NULL-terminated array of strings.
Returns the length of the given NULL-terminated string array .
Return value: length of .
Since: 2.6
g_strip_context: : a string : another string
An auxiliary function for gettext() support (see Q_()).
Return value: , unless is identical to and contains a '|' character, in which case a pointer to the substring of msgid after the first '|' character is returned.
Since: 2.4
g_dgettext: : the translation domain to use, or NULL to use the domain set with textdomain() : message to translate
This function is a wrapper of dgettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale.
The advantage of using this function over dgettext() proper is that libraries using this function (like GTK+) will not use translations if the application using the library does not have translations for the current locale. This results in a consistent English-only interface instead of one having partial translations. For this feature to work, the call to textdomain() and setlocale() should precede any g_dgettext() invocations. For GTK+, it means calling textdomain() before gtk_init or its variants.
This function disables translations if and only if upon its first call all the following conditions hold: <itemizedlist> <listitem> is not NULL</listitem> <listitem>textdomain() has been called to set a default text domain</listitem> <listitem>there is no translations available for the default text domain and the current locale</listitem> <listitem>current locale is not "C" or any English locales (those starting with "en_")</listitem> </itemizedlist>
Note that this behavior may not be desired for example if an application has its untranslated messages in a language other than English. In those cases the application should call textdomain() after initializing GTK+.
Applications should normally not use this function directly, but use the _() macro for translations.
Returns: The translated string
Since: 2.18
| IMPORT_C G_CONST_RETURN gchar * | g_dngettext | ( | const gchar * | domain, |
| const gchar * | msgid, | |||
| const gchar * | msgid_plural, | |||
| gulong | n | |||
| ) | ||||
g_dngettext: : the translation domain to use, or NULL to use the domain set with textdomain() : message to translate : plural form of the message : the quantity for which translation is needed
This function is a wrapper of dngettext() which does not translate the message if the default domain as set with textdomain() has no translations for the current locale.
See g_dgettext() for details of how this differs from dngettext() proper.
Returns: The translated string
Since: 2.18
| IMPORT_C G_CONST_RETURN gchar * | g_dpgettext | ( | const gchar * | domain, |
| const gchar * | msgctxtid, | |||
| gsize | msgidoffset | |||
| ) | ||||
g_dpgettext: : the translation domain to use, or NULL to use the domain set with textdomain() : a combined message context and message id, separated by a \004 character : the offset of the message id in
This function is a variant of g_dgettext() which supports a disambiguating message context. GNU gettext uses the '\004' character to separate the message context and message id in . If 0 is passed as , this function will fall back to trying to use the deprecated convention of using "|" as a separation character.
This uses g_dgettext() internally. See that functions for differences with dgettext() proper.
Applications should normally not use this function directly, but use the C_() macro for translations with context.
Returns: The translated string
Since: 2.16