bytes(3pm)

1bytes(3pm)             Perl Programmers Reference Guide             bytes(3pm)
2
3
4

NAME

6       bytes - Perl pragma to expose the individual bytes of characters
7

NOTICE

9       Because the bytes pragma breaks encapsulation (i.e. it exposes the
10       innards of how the perl executable currently happens to store a
11       string), the byte values that result are in an unspecified encoding.
12
13       Use of this module for anything other than debugging purposes is
14       strongly discouraged.  If you feel that the functions here within might
15       be useful for your application, this possibly indicates a mismatch
16       between your mental model of Perl Unicode and the current reality. In
17       that case, you may wish to read some of the perl Unicode documentation:
18       perluniintro, perlunitut, perlunifaq and perlunicode.
19

SYNOPSIS

21           use bytes;
22           ... chr(...);       # or bytes::chr
23           ... index(...);     # or bytes::index
24           ... length(...);    # or bytes::length
25           ... ord(...);       # or bytes::ord
26           ... rindex(...);    # or bytes::rindex
27           ... substr(...);    # or bytes::substr
28           no bytes;
29

DESCRIPTION

31       Perl's characters are stored internally as sequences of one or more
32       bytes.  This pragma allows for the examination of the individual bytes
33       that together comprise a character.
34
35       Originally the pragma was designed for the loftier goal of helping
36       incorporate Unicode into Perl, but the approach that used it was found
37       to be defective, and the one remaining legitimate use is for debugging
38       when you need to non-destructively examine characters' individual
39       bytes.  Just insert this pragma temporarily, and remove it after the
40       debugging is finished.
41
42       The original usage can be accomplished by explicit (rather than this
43       pragma's implict) encoding using the Encode module:
44
45           use Encode qw/encode/;
46
47           my $utf8_byte_string   = encode "UTF8",   $string;
48           my $latin1_byte_string = encode "Latin1", $string;
49
50       Or, if performance is needed and you are only interested in the UTF-8
51       representation:
52
53           use utf8;
54
55           utf8::encode(my $utf8_byte_string = $string);
56
57       "no bytes" can be used to reverse the effect of "use bytes" within the
58       current lexical scope.
59
60       As an example, when Perl sees "$x = chr(400)", it encodes the character
61       in UTF-8 and stores it in $x. Then it is marked as character data, so,
62       for instance, "length $x" returns 1. However, in the scope of the
63       "bytes" pragma, $x is treated as a series of bytes - the bytes that
64       make up the UTF8 encoding - and "length $x" returns 2:
65
66        $x = chr(400);
67        print "Length is ", length $x, "\n";     # "Length is 1"
68        printf "Contents are %vd\n", $x;         # "Contents are 400"
69        {
70            use bytes; # or "require bytes; bytes::length()"
71            print "Length is ", length $x, "\n"; # "Length is 2"
72            printf "Contents are %vd\n", $x;     # "Contents are 198.144 (on
73                                                 # ASCII platforms)"
74        }
75
76       "chr()", "ord()", "substr()", "index()" and "rindex()" behave
77       similarly.
78
79       For more on the implications, see perluniintro and perlunicode.
80
81       "bytes::length()" is admittedly handy if you need to know the byte
82       length of a Perl scalar.  But a more modern way is:
83
84          use Encode 'encode';
85          length(encode('UTF-8', $scalar))
86

LIMITATIONS

88       "bytes::substr()" does not work as an lvalue().
89

NAME

NOTICE

SYNOPSIS

DESCRIPTION

LIMITATIONS

SEE ALSO