/ 
Encode-0.94
River stage five • 1105 direct dependents • 33721 total dependents
/ Encode

NAME

Encode - character encodings

SYNOPSIS

use Encode;

DESCRIPTION

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

To find more about character encodings, please consult Encode::Description . This document focuses on programming references.

PERL ENCODING API

Generic Encoding Interface

  • $bytes  = encode(ENCODING, $string[, CHECK])

    Encodes string from Perl's internal form into ENCODING and returns a sequence of octets. For CHECK see "Handling Malformed Data".

    For example to convert (internally UTF-8 encoded) Unicode data to octets:

    $octets = encode("utf8", $unicode);

  • $string = decode(ENCODING, $bytes[, CHECK])

    Decode sequence of octets assumed to be in ENCODING into Perl's internal form and returns the resulting string. For CHECK see "Handling Malformed Data".

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

    $utf8 = decode("latin1", $latin1);

  • 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 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.

Handling Malformed Data

If CHECK is not set, undef is returned. 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.

It would desirable to have a way to indicate that transform should use the encodings "replacement character" - no such mechanism is defined yet.

It is also planned to allow CHECK to be a code reference.

This is not yet implemented as there are design issues with what its arguments should be and how it returns its results.

Scheme 1

Passed remaining fragment of string being processed. Modifies it in place to remove bytes/characters it can understand and returns a string used to represent them. e.g.

sub fixup {
  my $ch = substr($_[0],0,1,'');
  return sprintf("\x{%02X}",ord($ch);
}

This scheme is close to how underlying C code for Encode works, but gives the fixup routine very little context.

Scheme 2

Passed original string, and an index into it of the problem area, and output string so far. Appends what it will to output string and returns new index into original string. For example:

sub fixup {
  # my ($s,$i,$d) = @_;
  my $ch = substr($_[0],$_[1],1);
  $_[2] .= sprintf("\x{%02X}",ord($ch);
  return $_[1]+1;
}

This scheme gives maximal control to the fixup routine but is more complicated to code, and may need internals of Encode to be tweaked to keep original string intact.

Other Schemes

Hybrids of above.

Multiple return values rather than in-place modifications.

Index into the string could be pos($str) allowing s/\G...//.

UTF-8 / utf8

The Unicode consortium defines the UTF-8 standard as a way of encoding the entire Unicode repertiore as sequences of octets. This encoding is expected to become very widespread. Perl can use this form internaly 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).

  • $bytes = 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($bytes [,CHECK]);

    The sequence of octets represented by $bytes 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 qw(encodings);
@list = encodings();

Returns a list of the canonical names of the available encodings.

Defining Aliases

use Encode qw(define_alias);
define_alias( newName => ENCODING);

Allows newName to be used as am alias for ENCODING. ENCODING may be either the name of an encoding or and encoding object (as above).

Currently newName can be specified in the following ways:

As a simple string.
As a qr// compiled regular expression, e.g.:
define_alias( qr/^iso8859-(\d+)$/i => '"iso-8859-$1"' );

In this case if ENCODING is not a reference it is eval-ed to allow $1 etc. to be subsituted. The example is one way to names as used in X11 font names to alias the MIME names for the iso-8859-* family. Note the double quote inside the single quote. If you are using regex here, you have to do so or it won't work in this case.

As a code reference, e.g.:
define_alias( sub { return /^iso8859-(\d+)$/i ? "iso-8859-$1" : undef } , '');

In this case $_ will be set to the name that is being looked up and ENCODING is passed to the sub as its first argument. The example is another way to names as used in X11 font names to alias the MIME names for the iso-8859-* family.

Defining Encodings

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

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

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.

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

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