conversions.sgml

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

<refentry id="glib-Character-Set-Conversion">
<refmeta>
<refentrytitle>Character Set Conversion</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Character Set Conversion</refname><refpurpose>convert strings between different character sets using <function><link linkend="iconv">iconv</link>()</function>.</refpurpose>
</refnamediv>

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

#include &lt;glib.h&gt;


<link linkend="gchar">gchar</link>*      <link linkend="g-convert">g_convert</link>                       (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-convert-with-fallback">g_convert_with_fallback</link>         (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gchar">gchar</link> *fallback,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-convert-with-iconv">g_convert_with_iconv</link>            (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="GIConv">GIConv</link> converter,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
#define     <link linkend="G-CONVERT-ERROR-CAPS">G_CONVERT_ERROR</link>
<link linkend="GIConv">GIConv</link>      <link linkend="g-iconv-open">g_iconv_open</link>                    (const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset);
<link linkend="size-t">size_t</link>      <link linkend="g-iconv">g_iconv</link>                         (<link linkend="GIConv">GIConv</link> converter,
                                             <link linkend="gchar">gchar</link> **inbuf,
                                             <link linkend="gsize">gsize</link> *inbytes_left,
                                             <link linkend="gchar">gchar</link> **outbuf,
                                             <link linkend="gsize">gsize</link> *outbytes_left);
<link linkend="gint">gint</link>        <link linkend="g-iconv-close">g_iconv_close</link>                   (<link linkend="GIConv">GIConv</link> converter);
<link linkend="gchar">gchar</link>*      <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>                (const <link linkend="gchar">gchar</link> *opsysstring,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-to-utf8">g_filename_to_utf8</link>              (const <link linkend="gchar">gchar</link> *opsysstring,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-from-utf8">g_filename_from_utf8</link>            (const <link linkend="gchar">gchar</link> *utf8string,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-from-uri">g_filename_from_uri</link>             (const char *uri,
                                             char **hostname,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-filename-to-uri">g_filename_to_uri</link>               (const char *filename,
                                             const char *hostname,
                                             <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link>*      <link linkend="g-locale-from-utf8">g_locale_from_utf8</link>              (const <link linkend="gchar">gchar</link> *utf8string,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);
enum        <link linkend="GConvertError">GConvertError</link>;

<link linkend="gboolean">gboolean</link>    <link linkend="g-get-charset">g_get_charset</link>                   (G_CONST_RETURN char **charset);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-convert">g_convert ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_convert                       (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a string from one character set to another.</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>           the string to convert
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string
</entry></row>
<row><entry align="right"><parameter>to_codeset</parameter>&nbsp;:</entry>
<entry>    name of character set into which to convert <parameter>str</parameter>
</entry></row>
<row><entry align="right"><parameter>from_codeset</parameter>&nbsp;:</entry>
<entry>  character set of <parameter>str</parameter>.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>    location to store the number of bytes in the
                input string that were successfully converted, or <literal>NULL</literal>.
                Even if the conversion was successful, this may be 
                less than <parameter>len</parameter> if there were partial characters
                at the end of the input. If the error
                <link linkend="G-CONVERT-ERROR-ILLEGAL-SEQUENCE-CAPS">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</link> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</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> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If the conversion was successful, a newly allocated
              nul-terminated string, which must be freed with
              <link linkend="g-free">g_free</link>(). Otherwise <literal>NULL</literal> and <parameter>error</parameter> will be set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-convert-with-fallback">g_convert_with_fallback ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_convert_with_fallback         (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset,
                                             <link linkend="gchar">gchar</link> *fallback,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a string from one character set to another, possibly
including fallback sequences for characters not representable
in the output. Note that it is not guaranteed that the specification
for the fallback sequences in <parameter>fallback</parameter> will be honored. Some
systems may do a approximate conversion from <parameter>from_codeset</parameter>
to <parameter>to_codeset</parameter> in their <function><link linkend="iconv">iconv</link>()</function> functions, 
in which case GLib will simply return that approximate conversion.</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>          the string to convert
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>          the length of the string
</entry></row>
<row><entry align="right"><parameter>to_codeset</parameter>&nbsp;:</entry>
<entry>   name of character set into which to convert <parameter>str</parameter>
</entry></row>
<row><entry align="right"><parameter>from_codeset</parameter>&nbsp;:</entry>
<entry> character set of <parameter>str</parameter>.
</entry></row>
<row><entry align="right"><parameter>fallback</parameter>&nbsp;:</entry>
<entry>     UTF-8 string to use in place of character not
               present in the target encoding. (This must be
               in the target encoding), if <literal>NULL</literal>, characters
               not in the target encoding will be represented
               as Unicode escapes \x{XXXX} or \x{XXXXXX}.
</entry></row>
<row><entry align="right"><parameter>bytes_read</parameter>&nbsp;:</entry>
<entry>   location to store the number of bytes in the
               input string that were successfully converted, or <literal>NULL</literal>.
               Even if the conversion was successful, this may be 
               less than <parameter>len</parameter> if there were partial characters
               at the end of the input.
</entry></row>
<row><entry align="right"><parameter>bytes_written</parameter>&nbsp;:</entry>
<entry> the number of bytes stored in the output buffer (not 
               including the terminating nul).
</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> may occur.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> If the conversion was successful, a newly allocated
              nul-terminated string, which must be freed with
              <link linkend="g-free">g_free</link>(). Otherwise <literal>NULL</literal> and <parameter>error</parameter> will be set.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-convert-with-iconv">g_convert_with_iconv ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_convert_with_iconv            (const <link linkend="gchar">gchar</link> *str,
                                             <link linkend="gssize">gssize</link> len,
                                             <link linkend="GIConv">GIConv</link> converter,
                                             <link linkend="gsize">gsize</link> *bytes_read,
                                             <link linkend="gsize">gsize</link> *bytes_written,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts a string from one character set to another.</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>           the string to convert
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>