conversions.sgml

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

<entry>           the length of the string
</entry></row>
<row><entry align="right"><parameter>converter</parameter>&nbsp;:</entry>
<entry>     conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>()
</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-ERROR-CAPS">G_CONVERT_ERROR</title>
<programlisting>#define G_CONVERT_ERROR g_convert_error_quark()
</programlisting>
<para>
Error domain for character set conversions. Errors in this domain will
be from the <link linkend="GConvertError">GConvertError</link> enumeration. See <link linkend="GError">GError</link> for information on 
error domains.
</para></refsect2>
<refsect2>
<title><anchor id="g-iconv-open">g_iconv_open ()</title>
<programlisting><link linkend="GIConv">GIConv</link>      g_iconv_open                    (const <link linkend="gchar">gchar</link> *to_codeset,
                                             const <link linkend="gchar">gchar</link> *from_codeset);</programlisting>
<para>
Same as the standard UNIX routine <function><link linkend="iconv-open">iconv_open</link>()</function>, but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.
</para>
<para>
GLib provides <link linkend="g-convert">g_convert</link>() and <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() which are likely
more convenient than the raw iconv wrappers.</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>to_codeset</parameter>&nbsp;:</entry>
<entry> destination codeset
</entry></row>
<row><entry align="right"><parameter>from_codeset</parameter>&nbsp;:</entry>
<entry> source codeset
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> a "conversion descriptor"
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-iconv">g_iconv ()</title>
<programlisting><link linkend="size-t">size_t</link>      g_iconv                         (<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);</programlisting>
<para>
Same as the standard UNIX routine <function><link linkend="iconv">iconv</link>()</function>, but
may be implemented via libiconv on UNIX flavors that lack
a native implementation.
</para>
<para>
GLib provides <link linkend="g-convert">g_convert</link>() and <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() which are likely
more convenient than the raw iconv wrappers.</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>converter</parameter>&nbsp;:</entry>
<entry> conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>()
</entry></row>
<row><entry align="right"><parameter>inbuf</parameter>&nbsp;:</entry>
<entry> bytes to convert
</entry></row>
<row><entry align="right"><parameter>inbytes_left</parameter>&nbsp;:</entry>
<entry> inout parameter, bytes remaining to convert in <parameter>inbuf</parameter>
</entry></row>
<row><entry align="right"><parameter>outbuf</parameter>&nbsp;:</entry>
<entry> converted output bytes
</entry></row>
<row><entry align="right"><parameter>outbytes_left</parameter>&nbsp;:</entry>
<entry> inout parameter, bytes available to fill in <parameter>outbuf</parameter>
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> count of non-reversible conversions, or -1 on error
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-iconv-close">g_iconv_close ()</title>
<programlisting><link linkend="gint">gint</link>        g_iconv_close                   (<link linkend="GIConv">GIConv</link> converter);</programlisting>
<para>
Same as the standard UNIX routine <function><link linkend="iconv-close">iconv_close</link>()</function>, but
may be implemented via libiconv on UNIX flavors that lack
a native implementation. Should be called to clean up
the conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>() when
you are done converting things.
</para>
<para>
GLib provides <link linkend="g-convert">g_convert</link>() and <link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() which are likely
more convenient than the raw iconv wrappers.</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>converter</parameter>&nbsp;:</entry>
<entry> a conversion descriptor from <link linkend="g-iconv-open">g_iconv_open</link>()
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> -1 on error, 0 on success
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-locale-to-utf8">g_locale_to_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_locale_to_utf8                (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);</programlisting>
<para>
Converts a string which is in the encoding used for strings by
the C runtime (usually the same as that used by the operating
system) in the current locale into a UTF-8 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>opsysstring</parameter>&nbsp;:</entry>
<entry>   a string in the encoding of the current locale
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string, or -1 if the string is
                nul-terminated.
</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> The converted string, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-to-utf8">g_filename_to_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_to_utf8              (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);</programlisting>
<para>
Converts a string which is in the encoding used for filenames
into a UTF-8 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>opsysstring</parameter>&nbsp;:</entry>
<entry>   a string in the encoding for filenames
</entry></row>
<row><entry align="right"><parameter>len</parameter>&nbsp;:</entry>
<entry>           the length of the string, or -1 if the string is
                nul-terminated.
</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> The converted string, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-from-utf8">g_filename_from_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_from_utf8            (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);</programlisting>
<para>
Converts a string from UTF-8 to the encoding used for filenames.</para>