conversions.sgml

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

<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>utf8string</parameter>&nbsp;:</entry>
<entry>    a UTF-8 encoded string.
</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-uri">g_filename_from_uri ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_from_uri             (const char *uri,
                                             char **hostname,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts an escaped UTF-8 encoded URI to a local filename in the
encoding used for filenames.</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>uri</parameter>&nbsp;:</entry>
<entry> a uri describing a filename (escaped, encoded in UTF-8).
</entry></row>
<row><entry align="right"><parameter>hostname</parameter>&nbsp;:</entry>
<entry> Location to store hostname for the URI, or <literal>NULL</literal>.
           If there is no hostname in the URI, <literal>NULL</literal> will be
           stored in this location.
</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> a newly-allocated string holding the resulting
              filename, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-to-uri">g_filename_to_uri ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_filename_to_uri               (const char *filename,
                                             const char *hostname,
                                             <link linkend="GError">GError</link> **error);</programlisting>
<para>
Converts an absolute filename to an escaped UTF-8 encoded URI.</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>filename</parameter>&nbsp;:</entry>
<entry> an absolute filename specified in the encoding
           used for filenames by the operating system.
</entry></row>
<row><entry align="right"><parameter>hostname</parameter>&nbsp;:</entry>
<entry> A UTF-8 encoded hostname, or <literal>NULL</literal> for none.
</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> a newly-allocated string holding the resulting
              URI, or <literal>NULL</literal> on an error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-locale-from-utf8">g_locale_from_utf8 ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_locale_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 strings by
the C runtime (usually the same as that used by the operating
system) in the current locale.</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>utf8string</parameter>&nbsp;:</entry>
<entry>    a UTF-8 encoded string 
</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="GConvertError">enum GConvertError</title>
<programlisting>typedef enum 
{
  G_CONVERT_ERROR_NO_CONVERSION,
  G_CONVERT_ERROR_ILLEGAL_SEQUENCE,
  G_CONVERT_ERROR_FAILED,
  G_CONVERT_ERROR_PARTIAL_INPUT,
  G_CONVERT_ERROR_BAD_URI,
  G_CONVERT_ERROR_NOT_ABSOLUTE_PATH
} GConvertError;
</programlisting>
<para>
Error codes returned by character set conversion routines.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_CONVERT_ERROR_NO_CONVERSION</literal></entry>
<entry>Conversion between the requested character sets
is not supported.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_ILLEGAL_SEQUENCE</literal></entry>
<entry>Invalid byte sequence in conversion input.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_FAILED</literal></entry>
<entry>Conversion failed for some reason.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_PARTIAL_INPUT</literal></entry>
<entry>Partial character sequence at end of input.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_BAD_URI</literal></entry>
<entry>URI is invalid.
</entry>
</row>
<row>
<entry><literal>G_CONVERT_ERROR_NOT_ABSOLUTE_PATH</literal></entry>
<entry>Pathname is not an absolute path.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-charset">g_get_charset ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_get_charset                   (G_CONST_RETURN char **charset);</programlisting>
<para>
Obtains the character set for the current locale; you might use
this character set as an argument to <link linkend="g-convert">g_convert</link>(), to convert from
the current locale's encoding to some other encoding. (Frequently
<link linkend="g-locale-to-utf8">g_locale_to_utf8</link>() and <link linkend="g-locale-from-utf8">g_locale_from_utf8</link>() are nice shortcuts,
though.)
</para>
<para>
The return value is <literal>TRUE</literal> if the locale's encoding is UTF-8, in that
case you can perhaps avoid calling <link linkend="g-convert">g_convert</link>().
</para>
<para>
The string returned in <parameter>charset</parameter> is not allocated, and should not be
freed.</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>charset</parameter>&nbsp;:</entry>
<entry> return location for character set name
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> <literal>TRUE</literal> if the returned charset is UTF-8
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>