Encode#

📦 std

Convert between Perl character strings and byte encodings.

use Encode qw(decode encode from_to find_encoding FB_CROAK);

my $chars = decode('UTF-8', "caf\xc3\xa9");          # bytes in, characters out
printf "%d characters, U+%04X last\n", length $chars, ord substr $chars, -1;
# 4 characters, U+00E9 last
printf "latin-1: %vX\n", encode('iso-8859-1', $chars);   # latin-1: 63.61.66.E9
printf "shiftjis: %vX\n", encode('shiftjis', "\x{65e5}\x{672c}");   # shiftjis: 93.FA.96.7B

my $data = "\xe9t\xe9";
from_to($data, 'iso-8859-1', 'utf8');                 # converts in place
printf "from_to: %vX\n", $data;                       # from_to: C3.A9.74.C3.A9
print eval { decode('UTF-8', "\xff", FB_CROAK); 1 } ? "decoded\n" : "malformed: dies\n";
print find_encoding('latin1')->name, "\n";            # iso-8859-1

A string read from a file or socket is bytes; decode turns it into characters, and encode turns characters back into bytes for output. The third argument of either, CHECK, says what to do with something that cannot be converted: substitute (the default), die (FB_CROAK), warn, or stop and leave the rest (FB_QUIET). encode_utf8 and decode_utf8 are the UTF-8 shortcuts; find_encoding returns the encoding object, and Encode->encodings(':all') names every encoding available - 124 here, as in perl 5.44.

The encodings are perl 5.44’s, from the same tables: ascii, iso-8859-1, cp1252 and UTF-8 are built in; the others are in Encode::Byte, CN, JP, KR, TW, Symbol, EBCDIC and Encode::Unicode, which Encode loads the first time one of their encodings is named.

This is a native implementation of the XS half of Encode 3.24; Encode.pm and its Perl modules (Encode::Alias, Encode::Encoding, the MIME, Guess, JIS7, HZ and UTF-7 encodings) are used unchanged. use Encode exports decode, encode, decode_utf8, encode_utf8, str2bytes, bytes2str, encodings, find_encoding, find_mime_encoding and clone_encoding; from_to, is_utf8 and the FB_* constants are imported by name, the constants also with :fallbacks.

Differences from upstream#

None.

Modules#

Functions#

Other Functions#

is_utf8#

is_utf8($string [, $check]) - whether the string’s UTF-8 flag is on; with a true $check, also whether its bytes are well-formed.

_utf8_on#

_utf8_on($string) - turn the UTF-8 flag on without changing the bytes; returns the previous state, or undef for a tainted value or a non-string.

_utf8_off#

_utf8_off($string) - turn the UTF-8 flag off without changing the bytes; returns the previous state, or undef for a tainted value or a non-string.

decode#

decode($encoding, $octets [, CHECK]) (also bytes2str) - decode bytes in the named encoding into a character string.

Also available as Encode::bytes2str.

encode#

encode($encoding, $string [, CHECK]) (also str2bytes) - encode a character string into bytes in the named encoding.

Also available as Encode::str2bytes.

decode_utf8#

decode_utf8($octets [, CHECK]) - decode UTF-8 octets (lax utf8).

encode_utf8#

encode_utf8($string) - the string’s characters as UTF-8 octets.

from_to#

from_to($octets, $from, $to [, CHECK]) - convert $octets in place from one encoding to another; returns the length of the result in bytes, or undef on failure.

onBOOT#

Encode::onBOOT - register the built-in table encodings (ascii, iso-8859-1, cp1252, null, ascii-ctrl); Encode.pm calls it once, after define_encoding exists.

encodings#

Return the list of encoding names the registry knows about.

find_encoding#

Look up an encoding by name and return an object you can call methods on.

resolve_alias#

Return the canonical encoding name for an alias, or undef if unknown.