unicode.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<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>