This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Bram pointed out the new tests hang if the fix for #72878 isn't in place.
[perl5.git] / lib / bytes.pm
CommitLineData
657b208b 1package bytes;
5bc28da9 2
79077e6c 3our $VERSION = '1.03';
b75c8c73 4
d5448623
GS
5$bytes::hint_bits = 0x00000008;
6
5bc28da9 7sub import {
d5448623 8 $^H |= $bytes::hint_bits;
5bc28da9
NIS
9}
10
11sub unimport {
d5448623 12 $^H &= ~$bytes::hint_bits;
5bc28da9
NIS
13}
14
15sub AUTOLOAD {
657b208b 16 require "bytes_heavy.pl";
5b5a256a
TS
17 goto &$AUTOLOAD if defined &$AUTOLOAD;
18 require Carp;
19 Carp::croak("Undefined subroutine $AUTOLOAD called");
5bc28da9
NIS
20}
21
79077e6c
RGS
22sub length (_);
23sub chr (_);
24sub ord (_);
579f6b36
JH
25sub substr ($$;$$);
26sub index ($$;$);
27sub rindex ($$;$);
5bc28da9
NIS
28
291;
30__END__
31
32=head1 NAME
33
657b208b 34bytes - Perl pragma to force byte semantics rather than character semantics
5bc28da9
NIS
35
36=head1 SYNOPSIS
37
657b208b 38 use bytes;
579f6b36
JH
39 ... chr(...); # or bytes::chr
40 ... index(...); # or bytes::index
41 ... length(...); # or bytes::length
42 ... ord(...); # or bytes::ord
43 ... rindex(...); # or bytes::rindex
44 ... substr(...); # or bytes::substr
657b208b 45 no bytes;
5bc28da9 46
579f6b36 47
5bc28da9
NIS
48=head1 DESCRIPTION
49
657b208b
GS
50The C<use bytes> pragma disables character semantics for the rest of the
51lexical scope in which it appears. C<no bytes> can be used to reverse
52the effect of C<use bytes> within the current lexical scope.
393fec97 53
5de28535
SC
54Perl normally assumes character semantics in the presence of character
55data (i.e. data that has come from a source that has been marked as
56being of a particular character encoding). When C<use bytes> is in
57effect, the encoding is temporarily ignored, and each string is treated
58as a series of bytes.
59
60As an example, when Perl sees C<$x = chr(400)>, it encodes the character
c26c758b 61in UTF-8 and stores it in $x. Then it is marked as character data, so,
5de28535
SC
62for instance, C<length $x> returns C<1>. However, in the scope of the
63C<bytes> pragma, $x is treated as a series of bytes - the bytes that make
64up the UTF8 encoding - and C<length $x> returns C<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 {
579f6b36 70 use bytes; # or "require bytes; bytes::length()"
5de28535
SC
71 print "Length is ", length $x, "\n"; # "Length is 2"
72 printf "Contents are %vd\n", $x; # "Contents are 198.144"
73 }
74
579f6b36
JH
75chr(), ord(), substr(), index() and rindex() behave similarly.
76
5de28535 77For more on the implications and differences between character
579f6b36
JH
78semantics and byte semantics, see L<perluniintro> and L<perlunicode>.
79
80=head1 LIMITATIONS
81
82bytes::substr() does not work as an lvalue().
393fec97
GS
83
84=head1 SEE ALSO
85
579f6b36 86L<perluniintro>, L<perlunicode>, L<utf8>
5bc28da9
NIS
87
88=cut