The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Encode-1.32
River stage five • 1091 direct dependents • 33185 total dependents
63 ++
/ Encode

NAME

Encode - character encodings

SYNOPSIS

    use Encode;

Table of Contents

Encode consists of a collection of modules which details are too big to fit in one document. This POD itself explains the top-level APIs and general topics at a glance. For other topics and more details, see the PODs below;

  Name                          Description
  --------------------------------------------------------
  Encode::Alias         Alias defintions to encodings
  Encode::Encoding      Encode Implementation Base Class
  Encode::Supported     List of Supported Encodings
  Encode::CN            Simplified Chinese Encodings
  Encode::JP            Japanese Encodings
  Encode::KR            Korean Encodings
  Encode::TW            Traditional Chinese Encodings
  --------------------------------------------------------

DESCRIPTION

The Encode module provides the interfaces between Perl's strings and the rest of the system. Perl strings are sequences of characters.

The repertoire of characters that Perl can represent is at least that defined by the Unicode Consortium. On most platforms the ordinal values of the characters (as returned by ord(ch)) is the "Unicode codepoint" for the character (the exceptions are those platforms where the legacy encoding is some variant of EBCDIC rather than a super-set of ASCII - see perlebcdic).

Traditionally computer data has been moved around in 8-bit chunks often called "bytes". These chunks are also known as "octets" in networking standards. Perl is widely used to manipulate data of many types - not only strings of characters representing human or computer languages but also "binary" data being the machines representation of numbers, pixels in an image - or just about anything.

When Perl is processing "binary data" the programmer wants Perl to process "sequences of bytes". This is not a problem for Perl - as a byte has 256 possible values it easily fits in Perl's much larger "logical character".

TERMINOLOGY

  • character: a character in the range 0..(2**32-1) (or more). (What Perl's strings are made of.)

  • byte: a character in the range 0..255 (A special case of a Perl character.)

  • octet: 8 bits of data, with ordinal values 0..255 (Term for bytes passed to or from a non-Perl context, e.g. disk file.)

The marker [INTERNAL] marks Internal Implementation Details, in general meant only for those who think they know what they are doing, and such details may change in future releases.

PERL ENCODING API

$octets = encode(ENCODING, $string[, CHECK])

Encodes string from Perl's internal form into ENCODING and returns a sequence of octets. ENCODING can be either a canonical name or alias. For encoding names and aliases, see "Defining Aliases". For CHECK see "Handling Malformed Data".

For example to convert (internally UTF-8 encoded) Unicode string to iso-8859-1 (also known as Latin1),

  $octets = encode("iso-8859-1", $unicode);
$string = decode(ENCODING, $octets[, CHECK])

Decode sequence of octets assumed to be in ENCODING into Perl's internal form and returns the resulting string. as in encode(), ENCODING can be either a canonical name or alias. For encoding names and aliases, see "Defining Aliases". For CHECK see "Handling Malformed Data".

For example to convert ISO-8859-1 data to UTF-8:

  $utf8 = decode("iso-8859-1", $latin1);
[$length =] from_to($string, FROM_ENCODING, TO_ENCODING [,CHECK])

Convert in-place the data between two encodings. How did the data in $string originally get to be in FROM_ENCODING? Either using encode() or through PerlIO: See "Encoding and IO". For encoding names and aliases, see "Defining Aliases". For CHECK see "Handling Malformed Data".

For example to convert ISO-8859-1 data to UTF-8:

        from_to($data, "iso-8859-1", "utf-8");

and to convert it back:

        from_to($data, "utf-8", "iso-8859-1");

Note that because the conversion happens in place, the data to be converted cannot be a string constant, it must be a scalar variable.

from_to() return the length of the converted string on success, undef otherwise.

UTF-8 / utf8

The Unicode consortium defines the UTF-8 standard as a way of encoding the entire Unicode repertoire as sequences of octets. This encoding is expected to become very widespread. Perl can use this form internally to represent strings, so conversions to and from this form are particularly efficient (as octets in memory do not have to change, just the meta-data that tells Perl how to treat them).

$octets = encode_utf8($string);

The characters that comprise string are encoded in Perl's superset of UTF-8 and the resulting octets returned as a sequence of bytes. All possible characters have a UTF-8 representation so this function cannot fail.

$string = decode_utf8($octets [, CHECK]);

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 "Handling Malformed Data".

Listing available encodings

  use Encode;
  @list = Encode->encodings();

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

  @all_encodings = Encode->encodings(":all");

Or you can give the name of specific module.

  @with_jp = Encode->encodings("Encode::JP");

When "::" is not in the name, "Encode::" is assumed.

  @ebcdic = Encode->encodings("EBCDIC");

To find which encodings are supported by this package in details, see Encode::Supported.

Defining Aliases

To add new alias to a given encoding, Use;

  use Encode;
  use Encode::Alias;
  define_alias(newName => ENCODING);

After that, newName can be used as an alias for ENCODING. ENCODING may be either the name of an encoding or an encoding object

But before you do so, make sure the alias is nonexistent with resolve_alias(), which returns the canonical name thereof. i.e.

  Encode::resolve_alias("latin1") eq "iso-8859-1" # true
  Encode::resolve_alias("iso-8859-12")   # false; nonexistent
  Encode::resolve_alias($name) eq $name  # true if $name is canonical

This resolve_alias() does not need use Encode::Alias and is exported via use encode qw(resolve_alias).

See Encode::Alias on details.

Encoding and IO

It is very common to want to do encoding transformations when reading or writing files, network connections, pipes etc. If Perl is configured to use the new 'perlio' IO system then Encode provides a "layer" (See perliol) which can transform data as it is read or written.

Here is how the blind poet would modernise the encoding:

    use Encode;
    open(my $iliad,'<:encoding(iso-8859-7)','iliad.greek');
    open(my $utf8,'>:utf8','iliad.utf8');
    my @epic = <$iliad>;
    print $utf8 @epic;
    close($utf8);
    close($illiad);

In addition the new IO system can also be configured to read/write UTF-8 encoded characters (as noted above this is efficient):

    open(my $fh,'>:utf8','anything');
    print $fh "Any \x{0021} string \N{SMILEY FACE}\n";

Either of the above forms of "layer" specifications can be made the default for a lexical scope with the use open ... pragma. See open.

Once a handle is open is layers can be altered using binmode.

Without any such configuration, or if Perl itself is built using system's own IO, then write operations assume that file handle accepts only bytes and will die if a character larger than 255 is written to the handle. When reading, each octet from the handle becomes a byte-in-a-character. Note that this default is the same behaviour as bytes-only languages (including Perl before v5.6) would have, and is sufficient to handle native 8-bit encodings e.g. iso-8859-1, EBCDIC etc. and any legacy mechanisms for handling other encodings and binary data.

In other cases it is the programs responsibility to transform characters into bytes using the API above before doing writes, and to transform the bytes read from a handle into characters before doing "character operations" (e.g. lc, /\W+/, ...).

You can also use PerlIO to convert larger amounts of data you don't want to bring into memory. For example to convert between ISO-8859-1 (Latin 1) and UTF-8 (or UTF-EBCDIC in EBCDIC machines):

    open(F, "<:encoding(iso-8859-1)", "data.txt") or die $!;
    open(G, ">:utf8",                 "data.utf") or die $!;
    while (<F>) { print G }

    # Could also do "print G <F>" but that would pull
    # the whole file into memory just to write it out again.

More examples:

    open(my $f, "<:encoding(cp1252)")
    open(my $g, ">:encoding(iso-8859-2)")
    open(my $h, ">:encoding(latin9)")       # iso-8859-15

See PerlIO for more information.

See also encoding for how to change the default encoding of the data in your script.

Handling Malformed Data

If CHECK is not set, (en|de)code will put substitution character in place of the malformed character. for UCM-based encodings, <subchar> will be used. For Unicode, \xFFFD is used. If the data is supposed to be UTF-8, an optional lexical warning (category utf8) is given.

If CHECK is true but not a code reference, dies with an error message.

In future you will be able to use a code reference to a callback function for the value of CHECK but its API is still undecided.

Defining Encodings

To define a new encoding, use:

    use Encode qw(define_alias);
    define_encoding($object, 'canonicalName' [, alias...]);

canonicalName will be associated with $object. The object should provide the interface described in Encode::Encoding If more than two arguments are provided then additional arguments are taken as aliases for $object as for define_alias.

See Encode::Encoding for more details.

Messing with Perl's Internals

The following API uses parts of Perl's internals in the current implementation. As such they are efficient, but may change.

is_utf8(STRING [, CHECK])

[INTERNAL] Test whether the UTF-8 flag is turned on in the STRING. If CHECK is true, also checks the data in STRING for being well-formed UTF-8. Returns true if successful, false otherwise.

_utf8_on(STRING)

[INTERNAL] Turn on the UTF-8 flag in STRING. The data in STRING is not checked for being well-formed UTF-8. Do not use unless you know that the STRING is well-formed UTF-8. Returns the previous state of the UTF-8 flag (so please don't test the return value as not success or failure), or undef if STRING is not a string.

_utf8_off(STRING)

[INTERNAL] Turn off the UTF-8 flag in STRING. Do not use frivolously. Returns the previous state of the UTF-8 flag (so please don't test the return value as not success or failure), or undef if STRING is not a string.

SEE ALSO

Encode::Encoding, Encode::Supported, PerlIO, encoding, perlebcdic, "open" in perlfunc, perlunicode, utf8, the Perl Unicode Mailing List <perl-unicode@perl.org>