unicode.sgml

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

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,