encode.html

perl教程

success, <em>undef</em> on error.</p>
</dd>
<dd>
<p><strong>CAVEAT</strong>: The following operations look the same but are not quite so;</p>
</dd>
<dd>
<pre>
  <span class="variable">from_to</span><span class="operator">(</span><span class="variable">$data</span><span class="operator">,</span> <span class="string">"iso-8859-1"</span><span class="operator">,</span> <span class="string">"utf8"</span><span class="operator">);</span> <span class="comment">#1</span>
  <span class="variable">$data</span> <span class="operator">=</span> <span class="variable">decode</span><span class="operator">(</span><span class="string">"iso-8859-1"</span><span class="operator">,</span> <span class="variable">$data</span><span class="operator">);</span>  <span class="comment">#2</span>
</pre>
</dd>
<dd>
<p>Both #1 and #2 make $data consist of a completely valid UTF-8 string
but only #2 turns utf8 flag on.  #1 is equivalent to</p>
</dd>
<dd>
<pre>
  <span class="variable">$data</span> <span class="operator">=</span> <span class="variable">encode</span><span class="operator">(</span><span class="string">"utf8"</span><span class="operator">,</span> <span class="variable">decode</span><span class="operator">(</span><span class="string">"iso-8859-1"</span><span class="operator">,</span> <span class="variable">$data</span><span class="operator">));</span>
</pre>
</dd>
<dd>
<p>See <a href="#the_utf8_flag">The UTF-8 flag</a> below.</p>
</dd>
</li>
<dt><strong><a name="item_encode_utf8">$octets = encode_utf8($string);</a></strong>

<dd>
<p>Equivalent to <a href="#item_encode"><code>$octets = encode(&quot;utf8&quot;, $string);</code></a> The characters
that comprise $string are encoded in Perl's internal format and the
result is returned as a sequence of octets. All possible
characters have a UTF-8 representation so this function cannot fail.</p>
</dd>
</li>
<dt><strong><a name="item_decode_utf8">$string = decode_utf8($octets [, CHECK]);</a></strong>

<dd>
<p>equivalent to <a href="#item_decode"><code>$string = decode(&quot;utf8&quot;, $octets [, CHECK])</code></a>.
The sequence of octets represented by
$octets is decoded from UTF-8 into a sequence of logical
characters. Not all sequences of octets form valid UTF-8 encodings, so
it is possible for this call to fail.  For CHECK, see
<a href="#handling_malformed_data">Handling Malformed Data</a>.</p>
</dd>
</li>
</dl>
<p>
</p>
<h2><a name="listing_available_encodings">Listing available encodings</a></h2>
<pre>
  <span class="keyword">use</span> <span class="variable">Encode</span><span class="operator">;</span>
  <span class="variable">@list</span> <span class="operator">=</span> <span class="variable">Encode</span><span class="operator">-&gt;</span><span class="variable">encodings</span><span class="operator">();</span>
</pre>
<p>Returns a list of the canonical names of the available encodings that
are loaded.  To get a list of all available encodings including the
ones that are not loaded yet, say</p>
<pre>
  <span class="variable">@all_encodings</span> <span class="operator">=</span> <span class="variable">Encode</span><span class="operator">-&gt;</span><span class="variable">encodings</span><span class="operator">(</span><span class="string">":all"</span><span class="operator">);</span>
</pre>
<p>Or you can give the name of a specific module.</p>
<pre>
  <span class="variable">@with_jp</span> <span class="operator">=</span> <span class="variable">Encode</span><span class="operator">-&gt;</span><span class="variable">encodings</span><span class="operator">(</span><span class="string">"Encode::JP"</span><span class="operator">);</span>
</pre>
<p>When &quot;::&quot; is not in the name, &quot;Encode::&quot; is assumed.</p>
<pre>
  <span class="variable">@ebcdic</span> <span class="operator">=</span> <span class="variable">Encode</span><span class="operator">-&gt;</span><span class="variable">encodings</span><span class="operator">(</span><span class="string">"EBCDIC"</span><span class="operator">);</span>
</pre>
<p>To find out in detail which encodings are supported by this package,
see <a href="../lib/Encode/Supported.html">the Encode::Supported manpage</a>.</p>
<p>
</p>
<h2><a name="defining_aliases">Defining Aliases</a></h2>
<p>To add a new alias to a given encoding, use:</p>
<pre>
  <span class="keyword">use</span> <span class="variable">Encode</span><span class="operator">;</span>
  <span class="keyword">use</span> <span class="variable">Encode::Alias</span><span class="operator">;</span>
  <span class="variable">define_alias</span><span class="operator">(</span><span class="string">newName</span> <span class="operator">=&gt;</span> <span class="variable">ENCODING</span><span class="operator">);</span>
</pre>
<p>After that, newName can be used as an alias for ENCODING.
ENCODING may be either the name of an encoding or an
<em>encoding object</em></p>
<p>But before you do so, make sure the alias is nonexistent with
<code>resolve_alias()</code>, which returns the canonical name thereof.
i.e.</p>
<pre>
  <span class="variable">Encode::resolve_alias</span><span class="operator">(</span><span class="string">"latin1"</span><span class="operator">)</span> <span class="keyword">eq</span> <span class="string">"iso-8859-1"</span> <span class="comment"># true</span>
  <span class="variable">Encode::resolve_alias</span><span class="operator">(</span><span class="string">"iso-8859-12"</span><span class="operator">)</span>   <span class="comment"># false; nonexistent</span>
  <span class="variable">Encode::resolve_alias</span><span class="operator">(</span><span class="variable">$name</span><span class="operator">)</span> <span class="keyword">eq</span> <span class="variable">$name</span>  <span class="comment"># true if $name is canonical</span>
</pre>
<p><code>resolve_alias()</code> does not need <code>use Encode::Alias</code>; it can be
exported via <code>use Encode qw(resolve_alias)</code>.</p>
<p>See <a href="../lib/Encode/Alias.html">the Encode::Alias manpage</a> for details.</p>
<p>
</p>
<hr />
<h1><a name="encoding_via_perlio">Encoding via PerlIO</a></h1>
<p>If your perl supports <em>PerlIO</em> (which is the default), you can use a PerlIO layer to decode
and encode directly via a filehandle.  The following two examples
are totally identical in their functionality.</p>
<pre>
  <span class="comment"># via PerlIO</span>
  <span class="keyword">open</span> <span class="keyword">my</span> <span class="variable">$in</span><span class="operator">,</span>  <span class="string">"&lt;:encoding(shiftjis)"</span><span class="operator">,</span> <span class="variable">$infile</span>  <span class="keyword">or</span> <span class="keyword">die</span><span class="operator">;</span>
  <span class="keyword">open</span> <span class="keyword">my</span> <span class="variable">$out</span><span class="operator">,</span> <span class="string">"&gt;:encoding(euc-jp)"</span><span class="operator">,</span>   <span class="variable">$outfile</span> <span class="keyword">or</span> <span class="keyword">die</span><span class="operator">;</span>
  <span class="keyword">while</span><span class="operator">(&lt;</span><span class="variable">$in</span><span class="operator">&gt;){</span> <span class="keyword">print</span> <span class="variable">$out</span> <span class="variable">$_</span><span class="operator">;</span> <span class="operator">}</span>
</pre>
<pre>
  <span class="comment"># via from_to</span>
  <span class="keyword">open</span> <span class="keyword">my</span> <span class="variable">$in</span><span class="operator">,</span>  <span class="string">"&lt;"</span><span class="operator">,</span> <span class="variable">$infile</span>  <span class="keyword">or</span> <span class="keyword">die</span><span class="operator">;</span>
  <span class="keyword">open</span> <span class="keyword">my</span> <span class="variable">$out</span><span class="operator">,</span> <span class="string">"&gt;"</span><span class="operator">,</span> <span class="variable">$outfile</span> <span class="keyword">or</span> <span class="keyword">die</span><span class="operator">;</span>
  <span class="keyword">while</span><span class="operator">(&lt;</span><span class="variable">$in</span><span class="operator">&gt;){</span>
    <span class="variable">from_to</span><span class="operator">(</span><span class="variable">$_</span><span class="operator">,</span> <span class="string">"shiftjis"</span><span class="operator">,</span> <span class="string">"euc-jp"</span><span class="operator">,</span> <span class="number">1</span><span class="operator">);</span>
    <span class="keyword">print</span> <span class="variable">$out</span> <span class="variable">$_</span><span class="operator">;</span>
  <span class="operator">}</span>
</pre>
<p>Unfortunately, it may be that encodings are PerlIO-savvy.  You can check
if your encoding is supported by PerlIO by calling the <code>perlio_ok</code>
method.</p>
<pre>
  <span class="variable">Encode::perlio_ok</span><span class="operator">(</span><span class="string">"hz"</span><span class="operator">);</span>             <span class="comment"># False</span>
  <span class="variable">find_encoding</span><span class="operator">(</span><span class="string">"euc-cn"</span><span class="operator">)-&gt;</span><span class="variable">perlio_ok</span><span class="operator">;</span>  <span class="comment"># True where PerlIO is available</span>
</pre>
<pre>
  <span class="keyword">use</span> <span class="variable">Encode</span> <span class="string">qw(perlio_ok)</span><span class="operator">;</span>            <span class="comment"># exported upon request</span>
  <span class="variable">perlio_ok</span><span class="operator">(</span><span class="string">"euc-jp"</span><span class="operator">)</span>
</pre>
<p>Fortunately, all encodings that come with Encode core are PerlIO-savvy
except for hz and ISO-2022-kr.  For gory details, see
<a href="../lib/Encode/Encoding.html">the Encode::Encoding manpage</a> and <a href="../lib/Encode/PerlIO.html">the Encode::PerlIO manpage</a>.</p>
<p>
</p>
<hr />
<h1><a name="handling_malformed_data">Handling Malformed Data</a></h1>
<p>The optional <em>CHECK</em> argument tells Encode what to do when it
encounters malformed data.  Without CHECK, Encode::FB_DEFAULT ( == 0 )
is assumed.</p>
<p>As of version 2.12 Encode supports coderef values for CHECK.  See below.</p>
<dl>
<dt><strong><a name="item_note_3a_not_all_encoding_support_this_feature"><strong>NOTE:</strong> Not all encoding support this feature</a></strong>

<dd>
<p>Some encodings ignore <em>CHECK</em> argument.  For example,
<a href="../lib/Encode/Unicode.html">the Encode::Unicode manpage</a> ignores <em>CHECK</em> and it always croaks on error.</p>
</dd>
</li>
</dl>
<p>Now here is the list of <em>CHECK</em> values available</p>
<dl>
<dt><strong><a name="item_fb_default"><em>CHECK</em> = Encode::FB_DEFAULT ( == 0)</a></strong>

<dd>
<p>If <em>CHECK</em> is 0, (en|de)code will put a <em>substitution character</em> in
place of a malformed character.  When you encode, &lt;subchar&gt;
will be used.  When you decode the code point <code>0xFFFD</code> is used.  If
the data is supposed to be UTF-8, an optional lexical warning
(category utf8) is given.</p>
</dd>
</li>
<dt><strong><a name="item_fb_croak"><em>CHECK</em> = Encode::FB_CROAK ( == 1)</a></strong>

<dd>
<p>If <em>CHECK</em> is 1, methods will die on error immediately with an error
message.  Therefore, when <em>CHECK</em> is set to 1,  you should trap the
error with eval{} unless you really want to let it die.</p>
</dd>
</li>
<dt><strong><a name="item_check__3d_encode_3a_3afb_quiet"><em>CHECK</em> = Encode::FB_QUIET</a></strong>

<dd>
<p>If <em>CHECK</em> is set to Encode::FB_QUIET, (en|de)code will immediately
return the portion of the data that has been processed so far when an
error occurs. The data argument will be overwritten with everything
after that point (that is, the unprocessed part of data).  This is
handy when you have to call decode repeatedly in the case where your
source data may contain partial multi-byte character sequences,
(i.e. you are reading with a fixed-width buffer). Here is a sample
code that does exactly this:</p>
</dd>
<dd>
<pre>
  <span class="keyword">my</span> <span class="variable">$buffer</span> <span class="operator">=</span> <span class="string">''</span><span class="operator">;</span> <span class="keyword">my</span> <span class="variable">$string</span> <span class="operator">=</span> <span class="string">''</span><span class="operator">;</span>
  <span class="keyword">while</span><span class="operator">(</span><span class="keyword">read</span> <span class="variable">$fh</span><span class="operator">,</span> <span class="variable">$buffer</span><span class="operator">,</span> <span class="number">256</span><span class="operator">,</span> <span class="keyword">length</span><span class="operator">(</span><span class="variable">$buffer</span><span class="operator">)){</span>
    <span class="variable">$string</span> <span class="operator">.=</span> <span class="variable">decode</span><span class="operator">(</span><span class="variable">$encoding</span><span class="operator">,</span> <span class="variable">$buffer</span><span class="operator">,</span> <span class="variable">Encode::FB_QUIET</span><span class="operator">);</span>
    <span class="comment"># $buffer now contains the unprocessed partial character</span>
  <span class="operator">}</span>
</pre>
</dd>
</li>
<dt><strong><a name="item_check__3d_encode_3a_3afb_warn"><em>CHECK</em> = Encode::FB_WARN</a></strong>

<dd>
<p>This is the same as above, except that it warns on error.  Handy when
you are debugging the mode above.</p>
</dd>
</li>
<dt><strong><a name="item_mode">perlqq mode (<em>CHECK</em> = Encode::FB_PERLQQ)</a></strong>

<dt><strong>HTML charref mode (<em>CHECK</em> = Encode::FB_HTMLCREF)</strong>

<dt><strong>XML charref mode (<em>CHECK</em> = Encode::FB_XMLCREF)</strong>

<dd>
<p>For encodings that are implemented by Encode::XS, CHECK ==
Encode::FB_PERLQQ turns (en|de)code into <code>perlqq</code> fallback mode.</p>
</dd>
<dd>
<p>When you decode, <code>\xHH</code> will be inserted for a malformed character,
where <em>HH</em> is the hex representation of the octet  that could not be
decoded to utf8.  And when you encode, <code>\x{HHHH}</code> will be inserted,
where <em>HHHH</em> is the Unicode ID of the character that cannot be found
in the character repertoire of the encoding.</p>
</dd>
<dd>
<p>HTML/XML character reference modes are about the same, in place of
<code>\x{HHHH}</code>, HTML uses <code>&amp;#NNN;</code> where <em>NNN</em> is a decimal number and
XML uses <code>&amp;#xHHHH;</code> where <em>HHHH</em> is the hexadecimal number.</p>
</dd>
<dd>
<p>In Encode 2.10 or later, <code>LEAVE_SRC</code> is also implied.</p>
</dd>
</li>
<dt><strong><a name="item_the_bitmask">The bitmask</a></strong>

<dd>
<p>These modes are actually set via a bitmask.  Here is how the FB_XX