glib-character-set-conversion.html

最新gtk中文资料集

	      <code class="function">fopen(3)</code> &#8212; those are "raw"
	      file names which the file system understands.
	    </p></li>
<li><p>
	      If you need to display a file name, convert it to UTF-8
	      first by using <code class="function"><a class="link" href="glib-Character-Set-Conversion.html#g-filename-to-utf8"><code class="function">g_filename_to_utf8()</code></a></code>.
	      If conversion fails, display a string like
	      "<code class="literal">Unknown file name</code>".  <span class="emphasis"><em>Do
	      not</em></span> convert this string back into the
	      encoding used for file names if you wish to pass it to
	      the file system; use the original file name instead.
	      For example, the document window of a word processor
	      could display "Unknown file name" in its title bar but
	      still let the user save the file, as it would keep the
	      raw file name internally.  This can happen if the user
	      has not set the <code class="envar">G_FILENAME_ENCODING</code>
	      environment variable even though he has files whose
	      names are not encoded in UTF-8.
	    </p></li>
<li><p>
	      If your user interface lets the user type a file name
	      for saving or renaming, convert it to the encoding used
	      for file names in the file system by using <code class="function"><a class="link" href="glib-Character-Set-Conversion.html#g-filename-from-utf8"><code class="function">g_filename_from_utf8()</code></a></code>.
	      Pass the converted file name to functions like
	      <code class="function">fopen(3)</code>.  If conversion fails, ask
	      the user to enter a different file name.  This can
	      happen if the user types Japanese characters when
	      <code class="envar">G_FILENAME_ENCODING</code> is set to
	      <code class="literal">ISO-8859-1</code>, for example.
	    </p></li>
</ol></div>
</div>
</div>
</div>
<div class="refsect1" lang="en">
<a name="id2989769"></a><h2>Details</h2>
<div class="refsect2" lang="en">
<a name="id2989780"></a><h3>
<a name="g-convert"></a>g_convert ()</h3>
<a class="indexterm" name="id2989792"></a><pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar">gchar</a>*              g_convert                           (const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *str,
                                                         <a class="link" href="glib-Basic-Types.html#gssize">gssize</a> len,
                                                         const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *to_codeset,
                                                         const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *from_codeset,
                                                         <a class="link" href="glib-Basic-Types.html#gsize">gsize</a> *bytes_read,
                                                         <a class="link" href="glib-Basic-Types.html#gsize">gsize</a> *bytes_written,
                                                         <a class="link" href="glib-Error-Reporting.html#GError">GError</a> **error);</pre>
<p>
Converts a string from one character set to another.
</p>
<p>
Note that you should use <a class="link" href="glib-Character-Set-Conversion.html#g-iconv"><code class="function">g_iconv()</code></a> for streaming 
conversions<sup>[<a href="glib-Character-Set-Conversion.html#ftn.streaming-state" class="footnoteref">2</a>]</sup>.</p>
<p>

</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>str</code></em>&#160;:</span></p></td>
<td>           the string to convert
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>len</code></em>&#160;:</span></p></td>
<td>           the length of the string, or -1 if the string is 
                nul-terminated<sup>[<a name="nul-unsafe" href="#ftn.nul-unsafe" class="footnote">1</a>]</sup>. 
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>to_codeset</code></em>&#160;:</span></p></td>
<td>    name of character set into which to convert <em class="parameter"><code>str</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>from_codeset</code></em>&#160;:</span></p></td>
<td>  character set of <em class="parameter"><code>str</code></em>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em>&#160;:</span></p></td>
<td>    location to store the number of bytes in the
                input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
                Even if the conversion was successful, this may be 
                less than <em class="parameter"><code>len</code></em> if there were partial characters
                at the end of the input. If the error
                <a class="link" href="glib-Character-Set-Conversion.html#G-CONVERT-ERROR-ILLEGAL-SEQUENCE:CAPS"><span class="type">G_CONVERT_ERROR_ILLEGAL_SEQUENCE</span></a> occurs, the value
                stored will the byte offset after the last valid
                input sequence.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em>&#160;:</span></p></td>
<td> the number of bytes stored in the output buffer (not 
                including the terminating nul).
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em>&#160;:</span></p></td>
<td>         location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore
                errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError"><span class="type">GConvertError</span></a> may occur.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</span></p></td>
<td> If the conversion was successful, a newly allocated
              nul-terminated string, which must be freed with
              <a class="link" href="glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>. Otherwise <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and <em class="parameter"><code>error</code></em> will be set.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2990113"></a><h3>
<a name="g-convert-with-fallback"></a>g_convert_with_fallback ()</h3>
<a class="indexterm" name="id2990126"></a><pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar">gchar</a>*              g_convert_with_fallback             (const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *str,
                                                         <a class="link" href="glib-Basic-Types.html#gssize">gssize</a> len,
                                                         const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *to_codeset,
                                                         const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *from_codeset,
                                                         <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *fallback,
                                                         <a class="link" href="glib-Basic-Types.html#gsize">gsize</a> *bytes_read,
                                                         <a class="link" href="glib-Basic-Types.html#gsize">gsize</a> *bytes_written,
                                                         <a class="link" href="glib-Error-Reporting.html#GError">GError</a> **error);</pre>
<p>
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 <em class="parameter"><code>fallback</code></em> will be honored. Some
systems may do an approximate conversion from <em class="parameter"><code>from_codeset</code></em>
to <em class="parameter"><code>to_codeset</code></em> in their <code class="function">iconv()</code> functions, 
in which case GLib will simply return that approximate conversion.
</p>
<p>
Note that you should use <a class="link" href="glib-Character-Set-Conversion.html#g-iconv"><code class="function">g_iconv()</code></a> for streaming 
conversions<sup>[<a href="glib-Character-Set-Conversion.html#ftn.streaming-state" class="footnoteref">2</a>]</sup>.</p>
<p>

</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><em class="parameter"><code>str</code></em>&#160;:</span></p></td>
<td>          the string to convert
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>len</code></em>&#160;:</span></p></td>
<td>          the length of the string, or -1 if the string is 
               nul-terminated<sup>[<a href="glib-Character-Set-Conversion.html#ftn.nul-unsafe" class="footnoteref">1</a>]</sup>. 
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>to_codeset</code></em>&#160;:</span></p></td>
<td>   name of character set into which to convert <em class="parameter"><code>str</code></em>
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>from_codeset</code></em>&#160;:</span></p></td>
<td> character set of <em class="parameter"><code>str</code></em>.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>fallback</code></em>&#160;:</span></p></td>
<td>     UTF-8 string to use in place of character not
               present in the target encoding. (The string must be
               representable in the target encoding). 
                  If <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, characters not in the target encoding will 
                  be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes_read</code></em>&#160;:</span></p></td>
<td>   location to store the number of bytes in the
               input string that were successfully converted, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.
               Even if the conversion was successful, this may be 
               less than <em class="parameter"><code>len</code></em> if there were partial characters
               at the end of the input.
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>bytes_written</code></em>&#160;:</span></p></td>
<td> the number of bytes stored in the output buffer (not 
               including the terminating nul).
</td>
</tr>
<tr>
<td><p><span class="term"><em class="parameter"><code>error</code></em>&#160;:</span></p></td>
<td>        location to store the error occuring, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> to ignore
               errors. Any of the errors in <a class="link" href="glib-Character-Set-Conversion.html#GConvertError"><span class="type">GConvertError</span></a> may occur.
</td>
</tr>
<tr>
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span>&#160;:</span></p></td>
<td> If the conversion was successful, a newly allocated
              nul-terminated string, which must be freed with
              <a class="link" href="glib-Memory-Allocation.html#g-free"><code class="function">g_free()</code></a>. Otherwise <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a> and <em class="parameter"><code>error</code></em> will be set.
</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2990498"></a><h3>
<a name="GIConv"></a>GIConv</h3>
<a class="indexterm" name="id2990511"></a><pre class="programlisting">typedef struct _GIConv GIConv;</pre>
<p>
The <span class="structname">GIConv</span> struct wraps an
<code class="function"><code class="function">iconv()</code></code> conversion descriptor. It contains private data
and should only be accessed using the following functions.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id2990545"></a><h3>
<a name="g-convert-with-iconv"></a>g_convert_with_iconv ()</h3>
<a class="indexterm" name="id2990559"></a><pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar">gchar</a>*              g_convert_with_iconv                (const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *str,
                                                         <a class="link" href="glib-Basic-Types.html#gssize">gssize</a> len,