<refentry id="glib-Unicode-Manipulation">
<refmeta>
<refentrytitle>Unicode Manipulation</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Unicode Manipulation</refname><refpurpose>functions operating on Unicode characters and UTF-8 strings.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


typedef     <link linkend="gunichar">gunichar</link>;
typedef     <link linkend="gunichar2">gunichar2</link>;

<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-validate">g_unichar_validate</link>              (<link linkend="gunichar">gunichar</link> ch);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isalnum">g_unichar_isalnum</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isalpha">g_unichar_isalpha</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-iscntrl">g_unichar_iscntrl</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isdigit">g_unichar_isdigit</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isgraph">g_unichar_isgraph</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-islower">g_unichar_islower</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isprint">g_unichar_isprint</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-ispunct">g_unichar_ispunct</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isspace">g_unichar_isspace</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isupper">g_unichar_isupper</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isxdigit">g_unichar_isxdigit</link>              (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-istitle">g_unichar_istitle</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-isdefined">g_unichar_isdefined</link>             (<link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-unichar-iswide">g_unichar_iswide</link>                (<link linkend="gunichar">gunichar</link> c);
<link linkend="gunichar">gunichar</link>    <link linkend="g-unichar-toupper">g_unichar_toupper</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gunichar">gunichar</link>    <link linkend="g-unichar-tolower">g_unichar_tolower</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gunichar">gunichar</link>    <link linkend="g-unichar-totitle">g_unichar_totitle</link>               (<link linkend="gunichar">gunichar</link> c);
<link linkend="gint">gint</link>        <link linkend="g-unichar-digit-value">g_unichar_digit_value</link>           (<link linkend="gunichar">gunichar</link> c);
<link linkend="gint">gint</link>        <link linkend="g-unichar-xdigit-value">g_unichar_xdigit_value</link>          (<link linkend="gunichar">gunichar</link> c);
enum        <link linkend="GUnicodeType">GUnicodeType</link>;
<link linkend="GUnicodeType">GUnicodeType</link> <link linkend="g-unichar-type">g_unichar_type</link>                 (<link linkend="gunichar">gunichar</link> c);
enum        <link linkend="GUnicodeBreakType">GUnicodeBreakType</link>;
<link linkend="GUnicodeBreakType">GUnicodeBreakType</link> <link linkend="g-unichar-break-type">g_unichar_break_type</link>      (<link linkend="gunichar">gunichar</link> c);
void        <link linkend="g-unicode-canonical-ordering">g_unicode_canonical_ordering</link>    (<link linkend="gunichar">gunichar</link> *string,
                                             <link linkend="gsize">gsize</link> len);
<link linkend="gunichar">gunichar</link>*   <link linkend="g-unicode-canonical-decomposition">g_unicode_canonical_decomposition</link>
                                            (<link linkend="gunichar">gunichar</link> ch,
                                             <link linkend="gsize">gsize</link> *result_len);

#define     <link linkend="g-utf8-next-char">g_utf8_next_char</link>                (p)
<link linkend="gunichar">gunichar</link>    <link linkend="g-utf8-get-char">g_utf8_get_char</link>                 (const <link linkend="gchar">gchar</link> *p);
<link linkend="gunichar">gunichar</link>    <link linkend="g-utf8-get-char-validated">g_utf8_get_char_validated</link>       (const  <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> max_len);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-offset-to-pointer">g_utf8_offset_to_pointer</link>        (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> offset);
<link linkend="glong">glong</link>       <link linkend="g-utf8-pointer-to-offset">g_utf8_pointer_to_offset</link>        (const <link linkend="gchar">gchar</link> *str,
                                             const <link linkend="gchar">gchar</link> *pos);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-prev-char">g_utf8_prev_char</link>                (const <link linkend="gchar">gchar</link> *p);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-find-next-char">g_utf8_find_next_char</link>           (const <link linkend="gchar">gchar</link> *p,
                                             const <link linkend="gchar">gchar</link> *end);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-find-prev-char">g_utf8_find_prev_char</link>           (const <link linkend="gchar">gchar</link> *str,
                                             const <link linkend="gchar">gchar</link> *p);
<link linkend="glong">glong</link>       <link linkend="g-utf8-strlen">g_utf8_strlen</link>                   (const <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> max);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-strncpy">g_utf8_strncpy</link>                  (<link linkend="gchar">gchar</link> *dest,
                                             const <link linkend="gchar">gchar</link> *src,
                                             <link linkend="gsize">gsize</link> n);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-strchr">g_utf8_strchr</link>                   (const <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gunichar">gunichar</link> c);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-strrchr">g_utf8_strrchr</link>                  (const <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gunichar">gunichar</link> c);
<link linkend="gboolean">gboolean</link>    <link linkend="g-utf8-validate">g_utf8_validate</link>                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> max_len,
                                             const <link linkend="gchar">gchar</link> **end);

<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-strup">g_utf8_strup</link>                    (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-strdown">g_utf8_strdown</link>                  (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-casefold">g_utf8_casefold</link>                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-normalize">g_utf8_normalize</link>                (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="GNormalizeMode">GNormalizeMode</link> mode);
enum        <link linkend="GNormalizeMode">GNormalizeMode</link>;
<link linkend="gint">gint</link>        <link linkend="g-utf8-collate">g_utf8_collate</link>                  (const <link linkend="gchar">gchar</link> *str1,
                                             const <link linkend="gchar">gchar</link> *str2);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf8-collate-key">g_utf8_collate_key</link>              (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);

<link linkend="gunichar2">gunichar2</link>*  <link linkend="g-utf8-to-utf16">g_utf8_to_utf16</link>                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gunichar">gunichar</link>*   <link linkend="g-utf8-to-ucs4">g_utf8_to_ucs4</link>                  (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gunichar">gunichar</link>*   <link linkend="g-utf8-to-ucs4-fast">g_utf8_to_ucs4_fast</link>             (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_written);
<link linkend="gunichar">gunichar</link>*   <link linkend="g-utf16-to-ucs4">g_utf16_to_ucs4</link>                 (const <link linkend="gunichar2">gunichar2</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-utf16-to-utf8">g_utf16_to_utf8</link>                 (const <link linkend="gunichar2">gunichar2</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gunichar2">gunichar2</link>*  <link linkend="g-ucs4-to-utf16">g_ucs4_to_utf16</link>                 (const <link linkend="gunichar">gunichar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-ucs4-to-utf8">g_ucs4_to_utf8</link>                  (const <link linkend="gunichar">gunichar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gint">gint</link>        <link linkend="g-unichar-to-utf8">g_unichar_to_utf8</link>               (<link linkend="gunichar">gunichar</link> c,
                                             <link linkend="gchar">gchar</link> *outbuf);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
This section describes a number of functions for dealing with
Unicode characters and strings.  There are analogues of the
traditional <filename>ctype.h</filename> character classification
and case conversion functions, UTF-8 analogues of some string utility 
functions, functions to perform normalization, case conversion and
collation on UTF-8 strings and finally functions to convert between
the UTF-8, UTF-16 and UCS-4 encodings of Unicode.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="gunichar">gunichar</title>
<programlisting>typedef guint32 gunichar;
</programlisting>
<para>
A type which can hold any UCS-4 character code. 
</para></refsect2>
<refsect2>
<title><anchor id="gunichar2">gunichar2</title>
<programlisting>typedef guint16 gunichar2;
</programlisting>
<para>
A type which can hold any UTF-16 character code. 
</para></refsect2>
<refsect2>
<title><anchor id="g-unichar-validate">g_unichar_validate ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_validate              (<link linkend="gunichar">gunichar</link> ch);</programlisting>
<para>
Checks whether <parameter>ch</parameter> is a valid Unicode character. Some possible
integer values of <parameter>ch</parameter> will not be valid. 0 is considered a valid
character, though it's normally a string terminator.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>ch</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>ch</parameter> is a valid Unicode character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isalnum">g_unichar_isalnum ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isalnum               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines whether a character is alphanumeric.
Given some UTF-8 text, obtain a character value
with <link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is an alphanumeric character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isalpha">g_unichar_isalpha ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isalpha               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines whether a character is alphabetic (i.e. a letter).
Given some UTF-8 text, obtain a character value with
<link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is an alphabetic character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-iscntrl">g_unichar_iscntrl ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_iscntrl               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines whether a character is a control character.
Given some UTF-8 text, obtain a character value with
<link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is a control character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isdigit">g_unichar_isdigit ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isdigit               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
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 <link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is a digit
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isgraph">g_unichar_isgraph ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isgraph               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines whether a character is printable and not a space
(returns <literal>FALSE</literal> for control characters, format characters, and
spaces). <link linkend="g-unichar-isprint">g_unichar_isprint</link>() is similar, but returns <literal>TRUE</literal> for
spaces. Given some UTF-8 text, obtain a character value with
<link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is printable unless it's a space
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-islower">g_unichar_islower ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_islower               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines whether a character is a lowercase letter.
Given some UTF-8 text, obtain a character value with
<link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is a lowercase letter
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isprint">g_unichar_isprint ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isprint               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines whether a character is printable.
Unlike <link linkend="g-unichar-isgraph">g_unichar_isgraph</link>(), returns <literal>TRUE</literal> for spaces.
Given some UTF-8 text, obtain a character value with
<link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is printable
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-ispunct">g_unichar_ispunct ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_ispunct               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines whether a character is punctuation or a symbol.
Given some UTF-8 text, obtain a character value with
<link linkend="g-utf8-get-char">g_utf8_get_char</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is a punctuation or symbol character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isspace">g_unichar_isspace ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isspace               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
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 <link linkend="g-utf8-get-char">g_utf8_get_char</link>().
</para>
<para>
(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.)</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is a punctuation character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isupper">g_unichar_isupper ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isupper               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines if a character is uppercase.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if <parameter>c</parameter> is an uppercase character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isxdigit">g_unichar_isxdigit ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isxdigit              (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines if a character is a hexidecimal digit.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the character is a hexadecimal digit
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-istitle">g_unichar_istitle ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_istitle               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the character is titlecase
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-isdefined">g_unichar_isdefined ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_isdefined             (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines if a given character is assigned in the Unicode
standard.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the character has an assigned value
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-iswide">g_unichar_iswide ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_unichar_iswide                (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines if a character is typically rendered in a double-width
cell.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the character is wide
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-toupper">g_unichar_toupper ()</title>
<programlisting><link linkend="gunichar">gunichar</link>    g_unichar_toupper               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Converts a character to uppercase.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the result of converting <parameter>c</parameter> to uppercase.
              If <parameter>c</parameter> is not an lowercase or titlecase character,
              or has no upper case equivalent <parameter>c</parameter> is returned unchanged.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-tolower">g_unichar_tolower ()</title>
<programlisting><link linkend="gunichar">gunichar</link>    g_unichar_tolower               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Converts a character to lower case.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the result of converting <parameter>c</parameter> to lower case.
              If <parameter>c</parameter> is not an upperlower or titlecase character,
              or has no lowercase equivalent <parameter>c</parameter> is returned unchanged.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-totitle">g_unichar_totitle ()</title>
<programlisting><link linkend="gunichar">gunichar</link>    g_unichar_totitle               (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Converts a character to the titlecase.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the result of converting <parameter>c</parameter> to titlecase.
              If <parameter>c</parameter> is not an uppercase or lowercase character,
              <parameter>c</parameter> is returned unchanged.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-digit-value">g_unichar_digit_value ()</title>
<programlisting><link linkend="gint">gint</link>        g_unichar_digit_value           (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines the numeric value of a character as a decimal
digit.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If <parameter>c</parameter> is a decimal digit (according to
<link linkend="g-unichar-isdigit">g_unichar_isdigit</link>()), its numeric value. Otherwise, -1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-xdigit-value">g_unichar_xdigit_value ()</title>
<programlisting><link linkend="gint">gint</link>        g_unichar_xdigit_value          (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines the numeric value of a character as a hexidecimal
digit.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If <parameter>c</parameter> is a hex digit (according to
<link linkend="g-unichar-isxdigit">g_unichar_isxdigit</link>()), its numeric value. Otherwise, -1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GUnicodeType">enum GUnicodeType</title>
<programlisting>typedef enum
{
  G_UNICODE_CONTROL,
  G_UNICODE_FORMAT,
  G_UNICODE_UNASSIGNED,
  G_UNICODE_PRIVATE_USE,
  G_UNICODE_SURROGATE,
  G_UNICODE_LOWERCASE_LETTER,
  G_UNICODE_MODIFIER_LETTER,
  G_UNICODE_OTHER_LETTER,
  G_UNICODE_TITLECASE_LETTER,
  G_UNICODE_UPPERCASE_LETTER,
  G_UNICODE_COMBINING_MARK,
  G_UNICODE_ENCLOSING_MARK,
  G_UNICODE_NON_SPACING_MARK,
  G_UNICODE_DECIMAL_NUMBER,
  G_UNICODE_LETTER_NUMBER,
  G_UNICODE_OTHER_NUMBER,
  G_UNICODE_CONNECT_PUNCTUATION,
  G_UNICODE_DASH_PUNCTUATION,
  G_UNICODE_CLOSE_PUNCTUATION,
  G_UNICODE_FINAL_PUNCTUATION,
  G_UNICODE_INITIAL_PUNCTUATION,
  G_UNICODE_OTHER_PUNCTUATION,
  G_UNICODE_OPEN_PUNCTUATION,
  G_UNICODE_CURRENCY_SYMBOL,
  G_UNICODE_MODIFIER_SYMBOL,
  G_UNICODE_MATH_SYMBOL,
  G_UNICODE_OTHER_SYMBOL,
  G_UNICODE_LINE_SEPARATOR,
  G_UNICODE_PARAGRAPH_SEPARATOR,
  G_UNICODE_SPACE_SEPARATOR
} GUnicodeType;
</programlisting>
<para>
These are the possible character classifications.
See <ulink url="http://www.unicode.org/Public/UNIDATA/UnicodeData.html"
>http://www.unicode.org/Public/UNIDATA/UnicodeData.html</ulink>.
</para></refsect2>
<refsect2>
<title><anchor id="g-unichar-type">g_unichar_type ()</title>
<programlisting><link linkend="GUnicodeType">GUnicodeType</link> g_unichar_type                 (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Classifies a Unicode character by type.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the type of the character.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GUnicodeBreakType">enum GUnicodeBreakType</title>
<programlisting>typedef enum
{
  G_UNICODE_BREAK_MANDATORY,
  G_UNICODE_BREAK_CARRIAGE_RETURN,
  G_UNICODE_BREAK_LINE_FEED,
  G_UNICODE_BREAK_COMBINING_MARK,
  G_UNICODE_BREAK_SURROGATE,
  G_UNICODE_BREAK_ZERO_WIDTH_SPACE,
  G_UNICODE_BREAK_INSEPARABLE,
  G_UNICODE_BREAK_NON_BREAKING_GLUE,
  G_UNICODE_BREAK_CONTINGENT,
  G_UNICODE_BREAK_SPACE,
  G_UNICODE_BREAK_AFTER,
  G_UNICODE_BREAK_BEFORE,
  G_UNICODE_BREAK_BEFORE_AND_AFTER,
  G_UNICODE_BREAK_HYPHEN,
  G_UNICODE_BREAK_NON_STARTER,
  G_UNICODE_BREAK_OPEN_PUNCTUATION,
  G_UNICODE_BREAK_CLOSE_PUNCTUATION,
  G_UNICODE_BREAK_QUOTATION,
  G_UNICODE_BREAK_EXCLAMATION,
  G_UNICODE_BREAK_IDEOGRAPHIC,
  G_UNICODE_BREAK_NUMERIC,
  G_UNICODE_BREAK_INFIX_SEPARATOR,
  G_UNICODE_BREAK_SYMBOL,
  G_UNICODE_BREAK_ALPHABETIC,
  G_UNICODE_BREAK_PREFIX,
  G_UNICODE_BREAK_POSTFIX,
  G_UNICODE_BREAK_COMPLEX_CONTEXT,
  G_UNICODE_BREAK_AMBIGUOUS,
  G_UNICODE_BREAK_UNKNOWN
} GUnicodeBreakType;
</programlisting>
<para>
These are the possible line break classifications.
See <ulink url="http://www.unicode.org/unicode/reports/tr14/"
>http://www.unicode.org/unicode/reports/tr14/</ulink>.
</para></refsect2>
<refsect2>
<title><anchor id="g-unichar-break-type">g_unichar_break_type ()</title>
<programlisting><link linkend="GUnicodeBreakType">GUnicodeBreakType</link> g_unichar_break_type      (<link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Determines the break type of <parameter>c</parameter>. <parameter>c</parameter> should be a Unicode character
(to derive a character from UTF-8 encoded text, use
<link linkend="g-utf8-get-char">g_utf8_get_char</link>()). 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 <link linkend="pango-break">pango_break</link>() instead of caring about break types yourself.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a Unicode character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the break type of <parameter>c</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unicode-canonical-ordering">g_unicode_canonical_ordering ()</title>
<programlisting>void        g_unicode_canonical_ordering    (<link linkend="gunichar">gunichar</link> *string,
                                             <link linkend="gsize">gsize</link> len);</programlisting>
<para>
Computes the canonical ordering of a string in-place.  
This rearranges decomposed characters in the string 
according to their combining classes.  See the Unicode 
manual for more information.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>string</parameter>&nbsp;:</entry>
<entry> a UCS-4 encoded string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>string</parameter> to use.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unicode-canonical-decomposition">g_unicode_canonical_decomposition ()</title>
<programlisting><link linkend="gunichar">gunichar</link>*   g_unicode_canonical_decomposition
                                            (<link linkend="gunichar">gunichar</link> ch,
                                             <link linkend="gsize">gsize</link> *result_len);</programlisting>
<para>
Computes the canonical decomposition of a Unicode character.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>ch</parameter>&nbsp;:</entry>
<entry> a Unicode character.
</entry></row>
<row><entry align="right"><parameter>result_len</parameter>&nbsp;:</entry>
<entry> location to store the length of the return value.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated string of Unicode characters.
  <parameter>result_len</parameter> is set to the resulting length of the string.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-next-char">g_utf8_next_char()</title>
<programlisting>#define     g_utf8_next_char(p)</programlisting>
<para>
Skips to the next character in a UTF-8 string. The string must be
valid; this macro is as fast as possible, and has no error-checking.
You would use this macro to iterate over a string character by
character. The macro returns the start of the next UTF-8 character.
Before using this macro, use <link linkend="g-utf8-validate">g_utf8_validate</link>() to validate strings
that may contain invalid UTF-8.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry>Pointer to the start of a valid UTF-8 character.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-get-char">g_utf8_get_char ()</title>
<programlisting><link linkend="gunichar">gunichar</link>    g_utf8_get_char                 (const <link linkend="gchar">gchar</link> *p);</programlisting>
<para>
Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
If <parameter>p</parameter> 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 <link linkend="g-utf8-get-char-validated">g_utf8_get_char_validated</link>()
instead.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> a pointer to Unicode character encoded as UTF-8
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the resulting character
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-get-char-validated">g_utf8_get_char_validated ()</title>
<programlisting><link linkend="gunichar">gunichar</link>    g_utf8_get_char_validated       (const  <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> max_len);</programlisting>
<para>
Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
This function checks for incomplete characters, for invalid characters
such as characters that are out of the range of Unicode, and for
overlong encodings of valid characters.
</para>
<para>
Return value: the resulting character. If <parameter>p</parameter> points to a partial
   sequence at the end of a string that could begin a valid character,</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> a pointer to Unicode character encoded as UTF-8
</entry></row>
<row><entry align="right"><parameter>max_len</parameter>&nbsp;:</entry>
<entry> the maximum number of bytes to read, or -1, for no maximum.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>(gunichar)-2; otherwise, if <parameter>p</parameter> does not point to a valid
   UTF-8 encoded Unicode character, returns (gunichar)-1.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-offset-to-pointer">g_utf8_offset_to_pointer ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_offset_to_pointer        (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> offset);</programlisting>
<para>
Converts from an integer character offset to a pointer to a position
within the string.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>offset</parameter>&nbsp;:</entry>
<entry> a character offset within <parameter>str</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the resulting pointer
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-pointer-to-offset">g_utf8_pointer_to_offset ()</title>
<programlisting><link linkend="glong">glong</link>       g_utf8_pointer_to_offset        (const <link linkend="gchar">gchar</link> *str,
                                             const <link linkend="gchar">gchar</link> *pos);</programlisting>
<para>
Converts from a pointer to position within a string to a integer
character offset.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>pos</parameter>&nbsp;:</entry>
<entry> a pointer to a position within <parameter>str</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the resulting character offset
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-prev-char">g_utf8_prev_char ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_prev_char                (const <link linkend="gchar">gchar</link> *p);</programlisting>
<para>
Finds the previous UTF-8 character in the string before <parameter>p</parameter>.
</para>
<para>
<parameter>p</parameter> 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. If <parameter>p</parameter> might be the first
character of the string, you must use <link linkend="g-utf8-find-prev-char">g_utf8_find_prev_char</link>() instead.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> a pointer to a position within a UTF-8 encoded string
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found character.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-find-next-char">g_utf8_find_next_char ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_find_next_char           (const <link linkend="gchar">gchar</link> *p,
                                             const <link linkend="gchar">gchar</link> *end);</programlisting>
<para>
Finds the start of the next UTF-8 character in the string after <parameter>p</parameter>.
</para>
<para>
<parameter>p</parameter> 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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> a pointer to a position within a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>end</parameter>&nbsp;:</entry>
<entry> a pointer to the end of the string, or <literal>NULL</literal> to indicate
       that the string is nul-terminated, in which case
       the returned value will be 
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found character or <literal>NULL</literal>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-find-prev-char">g_utf8_find_prev_char ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_find_prev_char           (const <link linkend="gchar">gchar</link> *str,
                                             const <link linkend="gchar">gchar</link> *p);</programlisting>
<para>
Given a position <parameter>p</parameter> with a UTF-8 encoded string <parameter>str</parameter>, find the start
of the previous UTF-8 character starting before <parameter>p</parameter>. Returns <literal>NULL</literal> if no
UTF-8 characters are present in <parameter>p</parameter> before <parameter>str</parameter>.
</para>
<para>
<parameter>p</parameter> 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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> pointer to the beginning of a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> pointer to some position within <parameter>str</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to the found character or <literal>NULL</literal>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-strlen">g_utf8_strlen ()</title>
<programlisting><link linkend="glong">glong</link>       g_utf8_strlen                   (const <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> max);</programlisting>
<para>
Returns the length of the string in characters.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> pointer to the start of a UTF-8 encoded string.
</entry></row>
<row><entry align="right"><parameter>max</parameter>&nbsp;:</entry>
<entry> the maximum number of bytes to examine. If <parameter>max</parameter>
      is less than 0, then the string is assumed to be
      nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the length of the string in characters
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-strncpy">g_utf8_strncpy ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_strncpy                  (<link linkend="gchar">gchar</link> *dest,
                                             const <link linkend="gchar">gchar</link> *src,
                                             <link linkend="gsize">gsize</link> n);</programlisting>
<para>
Like the standard C <function><link linkend="strncpy">strncpy</link>()</function> function, but 
copies a given number of characters instead of a given number of 
bytes. The <parameter>src</parameter> string must be valid UTF-8 encoded text. 
(Use <link linkend="g-utf8-validate">g_utf8_validate</link>() on all text before trying to use UTF-8 
utility functions with it.)</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dest</parameter>&nbsp;:</entry>
<entry> buffer to fill with characters from <parameter>src</parameter>
</entry></row>
<row><entry align="right"><parameter>src</parameter>&nbsp;:</entry>
<entry> UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>n</parameter>&nbsp;:</entry>
<entry> character count
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <parameter>dest</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-strchr">g_utf8_strchr ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_strchr                   (const <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Finds the leftmost occurrence of the given ISO10646 character
in a UTF-8 encoded string, while limiting the search to <parameter>len</parameter> bytes.
If <parameter>len</parameter> is -1, allow unbounded search.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> a nul-terminated UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>p</parameter>
</entry></row>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a ISO10646 character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>NULL</literal> if the string does not contain the character, 
  otherwise, a pointer to the start of the leftmost occurrence of 
  the character in the string.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-strrchr">g_utf8_strrchr ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_strrchr                  (const <link linkend="gchar">gchar</link> *p,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gunichar">gunichar</link> c);</programlisting>
<para>
Find the rightmost occurrence of the given ISO10646 character
in a UTF-8 encoded string, while limiting the search to <parameter>len</parameter> bytes.
If <parameter>len</parameter> is -1, allow unbounded search.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>p</parameter>&nbsp;:</entry>
<entry> a nul-terminated UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>p</parameter>
</entry></row>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a ISO10646 character
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>NULL</literal> if the string does not contain the character, 
  otherwise, a pointer to the start of the rightmost occurrence of the 
  character in the string.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-validate">g_utf8_validate ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_utf8_validate                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> max_len,
                                             const <link linkend="gchar">gchar</link> **end);</programlisting>
<para>
Validates UTF-8 encoded text. <parameter>str</parameter> is the text to validate;
if <parameter>str</parameter> is nul-terminated, then <parameter>max_len</parameter> can be -1, otherwise
<parameter>max_len</parameter> should be the number of bytes to validate.
If <parameter>end</parameter> is non-<literal>NULL</literal>, then the end of the valid range
will be stored there (i.e. the address of the first invalid byte
if some bytes were invalid, or the end of the text being validated
otherwise).
</para>
<para>
Returns <literal>TRUE</literal> if all of <parameter>str</parameter> was valid. Many GLib and GTK+
routines <emphasis>require</emphasis> valid UTF-8 as input;
so data read from a file or the network should be checked
with <link linkend="g-utf8-validate">g_utf8_validate</link>() before doing anything else with it.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a pointer to character data
</entry></row>
<row><entry align="right"><parameter>max_len</parameter>&nbsp;:</entry>
<entry> max bytes to validate, or -1 to go until nul
</entry></row>
<row><entry align="right"><parameter>end</parameter>&nbsp;:</entry>
<entry> return location for end of valid data
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the text was valid UTF-8
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-strup">g_utf8_strup ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_strup                    (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
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.)</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated string, with all characters
   converted to uppercase.  
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-strdown">g_utf8_strdown ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_strdown                  (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated string, with all characters
   converted to lowercase.  
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-casefold">g_utf8_casefold ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_casefold                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
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
<link linkend="g-utf8-casefold">g_utf8_casefold</link>() on other strings.
</para>
<para>
Note that calling <link linkend="g-utf8-casefold">g_utf8_casefold</link>() followed by <link linkend="g-utf8-collate">g_utf8_collate</link>() 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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated string, that is a
  case independent form of <parameter>str</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-normalize">g_utf8_normalize ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_normalize                (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="GNormalizeMode">GNormalizeMode</link> mode);</programlisting>
<para>
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 <link linkend="g-utf8-normalize">g_utf8_normalize</link>() before
comparing two Unicode strings.
</para>
<para>
The normalization mode <literal>G_NORMALIZE_DEFAULT</literal> only
standardizes differences that do not affect the
text content, such as the above-mentioned accent
representation. <literal>G_NORMALIZE_ALL</literal> 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, <link linkend="g-utf8-collate">g_utf8_collate</link>() normalizes
with <literal>G_NORMALIZE_ALL</literal> as its first step.
</para>
<para>
<literal>G_NORMALIZE_DEFAULT_COMPOSE</literal> and <literal>G_NORMALIZE_ALL_COMPOSE</literal>
are like <literal>G_NORMALIZE_DEFAULT</literal> and <literal>G_NORMALIZE_ALL</literal>,
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.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><parameter>mode</parameter>&nbsp;:</entry>
<entry> the type of normalization to perform.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated string, that is the 
  normalized form of <parameter>str</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GNormalizeMode">enum GNormalizeMode</title>
<programlisting>typedef enum {
  G_NORMALIZE_DEFAULT,
  G_NORMALIZE_NFD = G_NORMALIZE_DEFAULT,
  G_NORMALIZE_DEFAULT_COMPOSE,
  G_NORMALIZE_NFC = G_NORMALIZE_DEFAULT_COMPOSE,
  G_NORMALIZE_ALL,
  G_NORMALIZE_NFKD = G_NORMALIZE_ALL,
  G_NORMALIZE_ALL_COMPOSE,
  G_NORMALIZE_NFKC = G_NORMALIZE_ALL_COMPOSE
} GNormalizeMode;
</programlisting>
<para>
Defines how a Unicode string is transformed in a 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. Unicode strings should generally be normalized before comparing them.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_NORMALIZE_DEFAULT</literal></entry>
<entry>standardize differences that do not affect the
  text content, such as the above-mentioned accent representation.
</entry>
</row>
<row>
<entry><literal>G_NORMALIZE_NFD</literal></entry>
<entry>another name for <literal>G_NORMALIZE_DEFAULT</literal>.
</entry>
</row>
<row>
<entry><literal>G_NORMALIZE_DEFAULT_COMPOSE</literal></entry>
<entry>like <literal>G_NORMALIZE_DEFAULT</literal>, but with composed
  forms rather than a maximally decomposed form.
</entry>
</row>
<row>
<entry><literal>G_NORMALIZE_NFC</literal></entry>
<entry>another name for <literal>G_NORMALIZE_DEFAULT_COMPOSE</literal>.
</entry>
</row>
<row>
<entry><literal>G_NORMALIZE_ALL</literal></entry>
<entry>beyond <literal>G_NORMALIZE_DEFAULT</literal> also standardize 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.
</entry>
</row>
<row>
<entry><literal>G_NORMALIZE_NFKD</literal></entry>
<entry>another name for <literal>G_NORMALIZE_ALL</literal>.
</entry>
</row>
<row>
<entry><literal>G_NORMALIZE_ALL_COMPOSE</literal></entry>
<entry>like <literal>G_NORMALIZE_ALL</literal>, but with composed
  forms rather than a maximally decomposed form.
</entry>
</row>
<row>
<entry><literal>G_NORMALIZE_NFKC</literal></entry>
<entry>another name for <literal>G_NORMALIZE_ALL_COMPOSE</literal>.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-collate">g_utf8_collate ()</title>
<programlisting><link linkend="gint">gint</link>        g_utf8_collate                  (const <link linkend="gchar">gchar</link> *str1,
                                             const <link linkend="gchar">gchar</link> *str2);</programlisting>
<para>
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 <link linkend="g-utf8-collate-key">g_utf8_collate_key</link>() and 
compare the keys with <function><link linkend="strcmp">strcmp</link>()</function> when 
sorting instead of sorting the original strings.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str1</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>str2</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> -1 if <parameter>str1</parameter> compares before <parameter>str2</parameter>, 0 if they
  compare equal, 1 if <parameter>str1</parameter> compares after <parameter>str2</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-collate-key">g_utf8_collate_key ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf8_collate_key              (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len);</programlisting>
<para>
Converts a string into a collation key that can be compared
with other collation keys using <function><link linkend="strcmp">strcmp</link>()</function>. 
The results of comparing the collation keys of two strings 
with <function><link linkend="strcmp">strcmp</link>()</function> will always be the same as 
comparing the two original keys with <link linkend="g-utf8-collate">g_utf8_collate</link>().</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string.
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> length of <parameter>str</parameter>, in bytes, or -1 if <parameter>str</parameter> is nul-terminated.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a newly allocated string. This string should
  be freed with <link linkend="g-free">g_free</link>() when you are done with it.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-to-utf16">g_utf8_to_utf16 ()</title>
<programlisting><link linkend="gunichar2">gunichar2</link>*  g_utf8_to_utf16                 (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Convert a string from UTF-8 to UTF-16. A 0 word will be
added to the result after the converted text.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>str</parameter> to use. If <parameter>len</parameter> < 0, then
      the string is nul-terminated.
</entry></row>
<row><entry align="right"><parameter>items_read</parameter>&nbsp;:</entry>
<entry> location to store number of bytes read, or <literal>NULL</literal>.
             If <literal>NULL</literal>, then <literal>G_CONVERT_ERROR_PARTIAL_INPUT</literal> will be
             returned in case <parameter>str</parameter> contains a trailing partial
             character. If an error occurs then the index of the
             invalid input is stored here.
</entry></row>
<row><entry align="right"><parameter>items_written</parameter>&nbsp;:</entry>
<entry> location to store number of words written, or <literal>NULL</literal>.
                The value stored here does not include the trailing
                0 word.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> other than
        <literal>G_CONVERT_ERROR_NO_CONVERSION</literal> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to a newly allocated UTF-16 string.
              This value must be freed with <link linkend="g-free">g_free</link>(). If an
              error occurs, <literal>NULL</literal> will be returned and
              <parameter>error</parameter> set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-to-ucs4">g_utf8_to_ucs4 ()</title>
<programlisting><link linkend="gunichar">gunichar</link>*   g_utf8_to_ucs4                  (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Convert a string from UTF-8 to a 32-bit fixed width
representation as UCS-4. A trailing 0 will be added to the
string after the converted text.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>str</parameter> to use. If <parameter>len</parameter> < 0, then
      the string is nul-terminated.
</entry></row>
<row><entry align="right"><parameter>items_read</parameter>&nbsp;:</entry>
<entry> location to store number of bytes read, or <literal>NULL</literal>.
             If <literal>NULL</literal>, then <literal>G_CONVERT_ERROR_PARTIAL_INPUT</literal> will be
             returned in case <parameter>str</parameter> contains a trailing partial
             character. If an error occurs then the index of the
             invalid input is stored here.
</entry></row>
<row><entry align="right"><parameter>items_written</parameter>&nbsp;:</entry>
<entry> location to store number of characters written or <literal>NULL</literal>.
                The value here stored does not include the trailing 0
                character. 
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> other than
        <literal>G_CONVERT_ERROR_NO_CONVERSION</literal> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to a newly allocated UCS-4 string.
              This value must be freed with <link linkend="g-free">g_free</link>(). If an
              error occurs, <literal>NULL</literal> will be returned and
              <parameter>error</parameter> set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf8-to-ucs4-fast">g_utf8_to_ucs4_fast ()</title>
<programlisting><link linkend="gunichar">gunichar</link>*   g_utf8_to_ucs4_fast             (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_written);</programlisting>
<para>
Convert a string from UTF-8 to a 32-bit fixed width
representation as UCS-4, assuming valid UTF-8 input.
This function is roughly twice as fast as <link linkend="g-utf8-to-ucs4">g_utf8_to_ucs4</link>()
but does no error checking on the input.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-8 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>str</parameter> to use. If <parameter>len</parameter> < 0, then
      the string is nul-terminated.
</entry></row>
<row><entry align="right"><parameter>items_written</parameter>&nbsp;:</entry>
<entry> location to store the number of characters in the
                result, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to a newly allocated UCS-4 string.
              This value must be freed with <link linkend="g-free">g_free</link>().
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf16-to-ucs4">g_utf16_to_ucs4 ()</title>
<programlisting><link linkend="gunichar">gunichar</link>*   g_utf16_to_ucs4                 (const <link linkend="gunichar2">gunichar2</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Convert a string from UTF-16 to UCS-4. The result will be
terminated with a 0 character.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-16 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>str</parameter> to use. If <parameter>len</parameter> < 0, then
      the string is terminated with a 0 character.
</entry></row>
<row><entry align="right"><parameter>items_read</parameter>&nbsp;:</entry>
<entry> location to store number of words read, or <literal>NULL</literal>.
             If <literal>NULL</literal>, then <literal>G_CONVERT_ERROR_PARTIAL_INPUT</literal> will be
             returned in case <parameter>str</parameter> contains a trailing partial
             character. If an error occurs then the index of the
             invalid input is stored here.
</entry></row>
<row><entry align="right"><parameter>items_written</parameter>&nbsp;:</entry>
<entry> location to store number of characters written, or <literal>NULL</literal>.
                The value stored here does not include the trailing
                0 character.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> other than
        <literal>G_CONVERT_ERROR_NO_CONVERSION</literal> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to a newly allocated UCS-4 string.
              This value must be freed with <link linkend="g-free">g_free</link>(). If an
              error occurs, <literal>NULL</literal> will be returned and
              <parameter>error</parameter> set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-utf16-to-utf8">g_utf16_to_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_utf16_to_utf8                 (const <link linkend="gunichar2">gunichar2</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Convert a string from UTF-16 to UTF-8. The result will be
terminated with a 0 byte.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UTF-16 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>str</parameter> to use. If <parameter>len</parameter> < 0, then
      the string is terminated with a 0 character.
</entry></row>
<row><entry align="right"><parameter>items_read</parameter>&nbsp;:</entry>
<entry> location to store number of words read, or <literal>NULL</literal>.
             If <literal>NULL</literal>, then <literal>G_CONVERT_ERROR_PARTIAL_INPUT</literal> will be
             returned in case <parameter>str</parameter> contains a trailing partial
             character. If an error occurs then the index of the
             invalid input is stored here.
</entry></row>
<row><entry align="right"><parameter>items_written</parameter>&nbsp;:</entry>
<entry> location to store number of bytes written, or <literal>NULL</literal>.
                The value stored here does not include the trailing
                0 byte.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> other than
        <literal>G_CONVERT_ERROR_NO_CONVERSION</literal> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to a newly allocated UTF-8 string.
              This value must be freed with <link linkend="g-free">g_free</link>(). If an
              error occurs, <literal>NULL</literal> will be returned and
              <parameter>error</parameter> set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ucs4-to-utf16">g_ucs4_to_utf16 ()</title>
<programlisting><link linkend="gunichar2">gunichar2</link>*  g_ucs4_to_utf16                 (const <link linkend="gunichar">gunichar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Convert a string from UCS-4 to UTF-16. A 0 word will be
added to the result after the converted text.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UCS-4 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>str</parameter> to use. If <parameter>len</parameter> < 0, then
      the string is terminated with a 0 character.
</entry></row>
<row><entry align="right"><parameter>items_read</parameter>&nbsp;:</entry>
<entry> location to store number of bytes read, or <literal>NULL</literal>.
             If an error occurs then the index of the invalid input
             is stored here.
</entry></row>
<row><entry align="right"><parameter>items_written</parameter>&nbsp;:</entry>
<entry> location to store number of words written, or <literal>NULL</literal>.
                The value stored here does not include the trailing
                0 word.
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> other than
        <literal>G_CONVERT_ERROR_NO_CONVERSION</literal> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to a newly allocated UTF-16 string.
              This value must be freed with <link linkend="g-free">g_free</link>(). If an
              error occurs, <literal>NULL</literal> will be returned and
              <parameter>error</parameter> set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-ucs4-to-utf8">g_ucs4_to_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_ucs4_to_utf8                  (const <link linkend="gunichar">gunichar</link> *str,
                                             <link linkend="glong">glong</link> len,
                                             <link linkend="glong">glong</link> *items_read,
                                             <link linkend="glong">glong</link> *items_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Convert a string from a 32-bit fixed width representation as UCS-4.
to UTF-8. The result will be terminated with a 0 byte.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry> a UCS-4 encoded string
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry> the maximum length of <parameter>str</parameter> to use. If <parameter>len</parameter> < 0, then
      the string is terminated with a 0 character.
</entry></row>
<row><entry align="right"><parameter>items_read</parameter>&nbsp;:</entry>
<entry> location to store number of characters read read, or <literal>NULL</literal>.
</entry></row>
<row><entry align="right"><parameter>items_written</parameter>&nbsp;:</entry>
<entry> location to store number of bytes written or <literal>NULL</literal>.
                The value here stored does not include the trailing 0
                byte. 
</entry></row>
<row><entry align="right"><parameter>error</parameter>&nbsp;:</entry>
<entry> location to store the error occuring, or <literal>NULL</literal> to ignore
        errors. Any of the errors in <link linkend="GConvertError">GConvertError</link> other than
        <literal>G_CONVERT_ERROR_NO_CONVERSION</literal> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a pointer to a newly allocated UTF-8 string.
              This value must be freed with <link linkend="g-free">g_free</link>(). If an
              error occurs, <literal>NULL</literal> will be returned and
              <parameter>error</parameter> set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-unichar-to-utf8">g_unichar_to_utf8 ()</title>
<programlisting><link linkend="gint">gint</link>        g_unichar_to_utf8               (<link linkend="gunichar">gunichar</link> c,
                                             <link linkend="gchar">gchar</link> *outbuf);</programlisting>
<para>
Converts a single character to UTF-8.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>c</parameter>&nbsp;:</entry>
<entry> a ISO10646 character code
</entry></row>
<row><entry align="right"><parameter>outbuf</parameter>&nbsp;:</entry>
<entry> output buffer, must have at least 6 bytes of space.
      If <literal>NULL</literal>, the length will be computed and returned
      and nothing will be written to <parameter>outbuf</parameter>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> number of bytes written
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
<para>
<variablelist>

<varlistentry>
<term><link linkend="g-locale-to-utf8">g_locale_to_utf8</link>(), <link linkend="g-locale-from-utf8">g_locale_from_utf8</link>()</term>
<listitem><para>
Convenience functions for converting between UTF-8 and the locale encoding. 
</para></listitem>
</varlistentry>

</variablelist>
</para>
</refsect1>

</refentry>
