
@c %start of fragment

@deffn Function g-unichar-validate  (ch@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Checks whether @var{ch} is a valid Unicode character. Some possible integer
values of @var{ch} will not be valid. 0 is considered a valid character, though
it's normally a string terminator.

@table @var
@item ch
a Unicode character

@item ret
@samp{@code{#t}} if @var{ch} is a valid Unicode character

@end table

@end deffn

@deffn Function g-unichar-isalnum  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is alphanumeric. Given some UTF-8 text, obtain a
character value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is an alphanumeric character

@end table

@end deffn

@deffn Function g-unichar-isalpha  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is alphabetic (i.e. a letter). Given some UTF-8
text, obtain a character value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is an alphabetic character

@end table

@end deffn

@deffn Function g-unichar-iscntrl  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is a control character. Given some UTF-8 text,
obtain a character value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is a control character

@end table

@end deffn

@deffn Function g-unichar-isdigit  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is numeric (i.e. a digit). This covers ASCII 0-9
and also digits in other languages/scripts. Given some UTF-8 text, obtain a
character value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is a digit

@end table

@end deffn

@deffn Function g-unichar-isgraph  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is printable and not a space (returns
@samp{@code{#f}} for control characters, format characters, and spaces).
@code{g-unichar-isprint} is similar, but returns @samp{@code{#t}} for spaces.
Given some UTF-8 text, obtain a character value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is printable unless it's a space

@end table

@end deffn

@deffn Function g-unichar-islower  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is a lowercase letter. Given some UTF-8 text,
obtain a character value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is a lowercase letter

@end table

@end deffn

@deffn Function g-unichar-isprint  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is printable. Unlike @code{g-unichar-isgraph},
returns @samp{@code{#t}} for spaces. Given some UTF-8 text, obtain a character
value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is printable

@end table

@end deffn

@deffn Function g-unichar-ispunct  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is punctuation or a symbol. Given some UTF-8
text, obtain a character value with @code{g-utf8-get-char}.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is a punctuation or symbol character

@end table

@end deffn

@deffn Function g-unichar-isspace  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines whether a character is a space, tab, or line separator (newline,
carriage return, etc.). Given some UTF-8 text, obtain a character value with
@code{g-utf8-get-char}.

(Note: don't use this to do word breaking; you have to use Pango or equivalent
to get word breaking right, the algorithm is fairly complex.)

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is a space character

@end table

@end deffn

@deffn Function g-unichar-isupper  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines if a character is uppercase.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if @var{c} is an uppercase character

@end table

@end deffn

@deffn Function g-unichar-isxdigit  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines if a character is a hexidecimal digit.

@table @var
@item c
a Unicode character.

@item ret
@samp{@code{#t}} if the character is a hexadecimal digit

@end table

@end deffn

@deffn Function g-unichar-istitle  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines if a character is titlecase. Some characters in Unicode which are
composites, such as the DZ digraph have three case variants instead of just two.
The titlecase form is used at the beginning of a word where only the first
letter is capitalized. The titlecase form of the DZ digraph is U+01F2 LATIN
CAPITAL LETTTER D WITH SMALL LETTER Z.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if the character is titlecase

@end table

@end deffn

@deffn Function g-unichar-isdefined  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines if a given character is assigned in the Unicode standard.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if the character has an assigned value

@end table

@end deffn

@deffn Function g-unichar-iswide  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines if a character is typically rendered in a double-width cell.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if the character is wide

@end table

@end deffn

@deffn Function g-unichar-iswide-cjk  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool})
Determines if a character is typically rendered in a double-width cell under
legacy East Asian locales. If a character is wide according to
@code{g-unichar-iswide}, then it is also reported wide with this function, but
the converse is not necessarily true. See the
@uref{http://www.unicode.org/reports/tr11/,Unicode Standard Annex } for details.

@table @var
@item c
a Unicode character

@item ret
@samp{@code{#t}} if the character is wide in legacy East Asian locales

@end table

Since 2.12

@end deffn

@deffn Function g-unichar-toupper  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{unsigned-int32})
Converts a character to uppercase.

@table @var
@item c
a Unicode character

@item ret
the result of converting @var{c} to uppercase. If @var{c} is not an lowercase or
titlecase character, or has no upper case equivalent @var{c} is returned
unchanged.

@end table

@end deffn

@deffn Function g-unichar-tolower  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{unsigned-int32})
Converts a character to lower case.

@table @var
@item c
a Unicode character.

@item ret
the result of converting @var{c} to lower case. If @var{c} is not an upperlower
or titlecase character, or has no lowercase equivalent @var{c} is returned
unchanged.

@end table

@end deffn

@deffn Function g-unichar-totitle  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{unsigned-int32})
Converts a character to the titlecase.

@table @var
@item c
a Unicode character

@item ret
the result of converting @var{c} to titlecase. If @var{c} is not an uppercase or
lowercase character, @var{c} is returned unchanged.

@end table

@end deffn

@deffn Function g-unichar-digit-value  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{int})
Determines the numeric value of a character as a decimal digit.

@table @var
@item c
a Unicode character

@item ret
If @var{c} is a decimal digit (according to @code{g-unichar-isdigit}), its
numeric value. Otherwise, -1.

@end table

@end deffn

@deffn Function g-unichar-xdigit-value  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{int})
Determines the numeric value of a character as a hexidecimal digit.

@table @var
@item c
a Unicode character

@item ret
If @var{c} is a hex digit (according to @code{g-unichar-isxdigit}), its numeric
value. Otherwise, -1.

@end table

@end deffn

@deffn Function g-unichar-type  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{<g-unicode-type>})
Classifies a Unicode character by type.

@table @var
@item c
a Unicode character

@item ret
the type of the character.

@end table

@end deffn

@deffn Function g-unichar-break-type  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{<g-unicode-break-type>})
Determines the break type of @var{c}. @var{c} should be a Unicode character (to
derive a character from UTF-8 encoded text, use @code{g-utf8-get-char}). The
break type is used to find word and line breaks ("text boundaries"), Pango
implements the Unicode boundary resolution algorithms and normally you would use
a function such as @code{pango-break} instead of caring about break types
yourself.

@table @var
@item c
a Unicode character

@item ret
the break type of @var{c}

@end table

@end deffn

@deffn Function g-unichar-get-mirror-char  (ch@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{bool}) (mirrored_ch@tie{}@code{unsigned-int32})
In Unicode, some characters are @dfn{mirrored}. This means that their images are
mirrored horizontally in text that is laid out from right to left. For instance,
"(" would become its mirror image, ")", in right-to-left text.

If @var{ch} has the Unicode mirrored property and there is another unicode
character that typically has a glyph that is the mirror image of @var{ch}'s
glyph and @var{mirrored-ch} is set, it puts that character in the address
pointed to by @var{mirrored-ch}. Otherwise the original character is put.

@table @var
@item ch
a Unicode character

@item mirrored-ch
location to store the mirrored character

@item ret
@samp{@code{#t}} if @var{ch} has a mirrored character, @samp{@code{#f}}
otherwise

@end table

Since 2.4

@end deffn

@deffn Function g-utf8-get-char  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{unsigned-int32})
Converts a sequence of bytes encoded as UTF-8 to a Unicode character. If @var{p}
does not point to a valid UTF-8 encoded character, results are undefined. If you
are not sure that the bytes are complete valid Unicode characters, you should
use @code{g-utf8-get-char-validated} instead.

@table @var
@item p
a pointer to Unicode character encoded as UTF-8

@item ret
the resulting character

@end table

@end deffn

@deffn Function g-utf8-find-next-char  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Finds the start of the next UTF-8 character in the string after @var{p}.

@var{p} does not have to be at the beginning of a UTF-8 character. No check is
made to see if the character found is actually valid other than it starts with
an appropriate byte.

@table @var
@item p
a pointer to a position within a UTF-8 encoded string

@item end
a pointer to the end of the string, or @samp{@code{#f}} to indicate that the
string is nul-terminated, in which case the returned value will be

@item ret
a pointer to the found character or @samp{@code{#f}}

@end table

@end deffn

@deffn Function g-utf8-strlen  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{long})
Returns the length of the string in characters.

@table @var
@item p
pointer to the start of a UTF-8 encoded string.

@item max
the maximum number of bytes to examine. If @var{max} is less than 0, then the
string is assumed to be nul-terminated. If @var{max} is 0, @var{p} will not be
examined and may be @samp{@code{#f}}.

@item ret
the length of the string in characters

@end table

@end deffn

@deffn Function g-utf8-strchr  (p@tie{}@code{mchars}) (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{mchars})
Finds the leftmost occurrence of the given Unicode character in a UTF-8 encoded
string, while limiting the search to @var{len} bytes. If @var{len} is -1, allow
unbounded search.

@table @var
@item p
a nul-terminated UTF-8 encoded string

@item len
the maximum length of @var{p}

@item c
a Unicode character

@item ret
@samp{@code{#f}} if the string does not contain the character, otherwise, a
pointer to the start of the leftmost occurrence of the character in the string.

@end table

@end deffn

@deffn Function g-utf8-strrchr  (p@tie{}@code{mchars}) (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{mchars})
Find the rightmost occurrence of the given Unicode character in a UTF-8 encoded
string, while limiting the search to @var{len} bytes. If @var{len} is -1, allow
unbounded search.

@table @var
@item p
a nul-terminated UTF-8 encoded string

@item len
the maximum length of @var{p}

@item c
a Unicode character

@item ret
@samp{@code{#f}} if the string does not contain the character, otherwise, a
pointer to the start of the rightmost occurrence of the character in the string.

@end table

@end deffn

@deffn Function g-utf8-strreverse  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Reverses a UTF-8 string. @var{str} must be valid UTF-8 encoded text. (Use
@code{g-utf8-validate} on all text before trying to use UTF-8 utility functions
with it.)

Note that unlike @code{g-strreverse}, this function returns newly-allocated
memory, which should be freed with @code{g-free} when no longer needed.

@table @var
@item str
a UTF-8 encoded string

@item len
the maximum length of @var{str} to use. If @var{len} < 0, then the string is
nul-terminated.

@item ret
a newly-allocated string which is the reverse of @var{str}.

@end table

Since 2.2

@end deffn

@deffn Function g-utf8-validate  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{bool})
Validates UTF-8 encoded text. @var{str} is the text to validate; if @var{str} is
nul-terminated, then @var{max-len} can be -1, otherwise @var{max-len} should be
the number of bytes to validate. If @var{end} is non-@samp{@code{#f}}, then the
end of the valid range will be stored there (i.e. the start of the first invalid
character if some bytes were invalid, or the end of the text being validated
otherwise).

Note that @code{g-utf8-validate} returns @samp{@code{#f}} if @var{max-len} is
positive and NUL is met before @var{max-len} bytes have been read.

Returns @samp{@code{#t}} if all of @var{str} was valid. Many GLib and GTK+
routines @emph{require} valid UTF-8 as input; so data read from a file or the
network should be checked with @code{g-utf8-validate} before doing anything else
with it.

@table @var
@item str
a pointer to character data

@item max-len
max bytes to validate, or -1 to go until NUL

@item end
return location for end of valid data

@item ret
@samp{@code{#t}} if the text was valid UTF-8

@end table

@end deffn

@deffn Function g-utf8-strup  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts all Unicode characters in the string that have a case to uppercase. The
exact manner that this is done depends on the current locale, and may result in
the number of characters in the string increasing. (For instance, the German
ess-zet will be changed to SS.)

@table @var
@item str
a UTF-8 encoded string

@item len
length of @var{str}, in bytes, or -1 if @var{str} is nul-terminated.

@item ret
a newly allocated string, with all characters converted to uppercase.

@end table

@end deffn

@deffn Function g-utf8-strdown  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts all Unicode characters in the string that have a case to lowercase. The
exact manner that this is done depends on the current locale, and may result in
the number of characters in the string changing.

@table @var
@item str
a UTF-8 encoded string

@item len
length of @var{str}, in bytes, or -1 if @var{str} is nul-terminated.

@item ret
a newly allocated string, with all characters converted to lowercase.

@end table

@end deffn

@deffn Function g-utf8-casefold  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts a string into a form that is independent of case. The result will not
correspond to any particular case, but can be compared for equality or ordered
with the results of calling @code{g-utf8-casefold} on other strings.

Note that calling @code{g-utf8-casefold} followed by @code{g-utf8-collate} is
only an approximation to the correct linguistic case insensitive ordering,
though it is a fairly good one. Getting this exactly right would require a more
sophisticated collation function that takes case sensitivity into account. GLib
does not currently provide such a function.

@table @var
@item str
a UTF-8 encoded string

@item len
length of @var{str}, in bytes, or -1 if @var{str} is nul-terminated.

@item ret
a newly allocated string, that is a case independent form of @var{str}.

@end table

@end deffn

@deffn Function g-utf8-normalize  (p@tie{}@code{mchars}) (mode@tie{}@code{<g-normalize-mode>}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts a string into canonical form, standardizing such issues as whether a
character with an accent is represented as a base character and combining accent
or as a single precomposed character. You should generally call
@code{g-utf8-normalize} before comparing two Unicode strings.

The normalization mode @samp{G_NORMALIZE_DEFAULT} only standardizes differences
that do not affect the text content, such as the above-mentioned accent
representation. @samp{G_NORMALIZE_ALL} also standardizes the "compatibility"
characters in Unicode, such as SUPERSCRIPT THREE to the standard forms (in this
case DIGIT THREE). Formatting information may be lost but for most text
operations such characters should be considered the same. For example,
@code{g-utf8-collate} normalizes with @samp{G_NORMALIZE_ALL} as its first step.

@samp{G_NORMALIZE_DEFAULT_COMPOSE} and @samp{G_NORMALIZE_ALL_COMPOSE} are like
@samp{G_NORMALIZE_DEFAULT} and @samp{G_NORMALIZE_ALL}, but returned a result
with composed forms rather than a maximally decomposed form. This is often
useful if you intend to convert the string to a legacy encoding or pass it to a
system with less capable Unicode handling.

@table @var
@item str
a UTF-8 encoded string.

@item len
length of @var{str}, in bytes, or -1 if @var{str} is nul-terminated.

@item mode
the type of normalization to perform.

@item ret
a newly allocated string, that is the normalized form of @var{str}.

@end table

@end deffn

@deffn Function g-utf8-collate  (str1@tie{}@code{mchars}) (str2@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{int})
Compares two strings for ordering using the linguistically correct rules for the
current locale. When sorting a large number of strings, it will be significantly
faster to obtain collation keys with @code{g-utf8-collate-key} and compare the
keys with @code{strcmp} when sorting instead of sorting the original strings.

@table @var
@item str1
a UTF-8 encoded string

@item str2
a UTF-8 encoded string

@item ret
< 0 if @var{str1} compares before @var{str2}, 0 if they compare equal, > 0 if
@var{str1} compares after @var{str2}.

@end table

@end deffn

@deffn Function g-utf8-collate-key  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts a string into a collation key that can be compared with other collation
keys produced by the same function using @code{strcmp}. The results of comparing
the collation keys of two strings with @code{strcmp} will always be the same as
comparing the two original keys with @code{g-utf8-collate}.

@table @var
@item str
a UTF-8 encoded string.

@item len
length of @var{str}, in bytes, or -1 if @var{str} is nul-terminated.

@item ret
a newly allocated string. This string should be freed with @code{g-free} when
you are done with it.

@end table

@end deffn

@deffn Function g-utf8-collate-key-for-filename  (p@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts a string into a collation key that can be compared with other collation
keys produced by the same function using @code{strcmp}.

In order to sort filenames correctly, this function treats the dot '.' as a
special case. Most dictionary orderings seem to consider it insignificant, thus
producing the ordering "event.c" "eventgenerator.c" "event.h" instead of
"event.c" "event.h" "eventgenerator.c". Also, we would like to treat numbers
intelligently so that "file1" "file10" "file5" is sorted as "file1" "file5"
"file10".

@table @var
@item str
a UTF-8 encoded string.

@item len
length of @var{str}, in bytes, or -1 if @var{str} is nul-terminated.

@item ret
a newly allocated string. This string should be freed with @code{g-free} when
you are done with it.

@end table

Since 2.8

@end deffn

@deffn Function g-unichar-to-utf8  (c@tie{}@code{unsigned-int32}) @result{}@tie{} (ret@tie{}@code{mchars})
Converts a single character to UTF-8.

@table @var
@item c
a Unicode character code

@item outbuf
output buffer, must have at least 6 bytes of space. If @samp{@code{#f}}, the
length will be computed and returned and nothing will be written to
@var{outbuf}.

@item ret
number of bytes written

@end table

@end deffn


@c %end of fragment
