1package bytes 1.09; 2 3use v5.38; 4 5BEGIN { $bytes::hint_bits = 0x0000_0008 } 6 7sub import { $^H |= $bytes::hint_bits } 8sub unimport { $^H &= ~$bytes::hint_bits } 9 10sub chr :prototype(_) { BEGIN { import() } &CORE::chr } 11sub index :prototype($$;$) { BEGIN { import() } &CORE::index } 12sub length :prototype(_) { BEGIN { import() } &CORE::length } 13sub ord :prototype(_) { BEGIN { import() } &CORE::ord } 14sub rindex :prototype($$;$) { BEGIN { import() } &CORE::rindex } 15sub substr :prototype($$;$$) { BEGIN { import() } &CORE::substr } 16 17__END__ 18 19=head1 NAME 20 21bytes - Perl pragma to expose the individual bytes of characters 22 23=head1 NOTICE 24 25Because the bytes pragma breaks encapsulation (i.e. it exposes the innards of 26how the perl executable currently happens to store a string), the byte values 27that result are in an unspecified encoding. 28 29B<Use of this module for anything other than debugging purposes is 30strongly discouraged.> If you feel that the functions here within 31might be useful for your application, this possibly indicates a 32mismatch between your mental model of Perl Unicode and the current 33reality. In that case, you may wish to read some of the perl Unicode 34documentation: L<perluniintro>, L<perlunitut>, L<perlunifaq> and 35L<perlunicode>. 36 37=head1 SYNOPSIS 38 39 use bytes; 40 ... chr(...); # or bytes::chr 41 ... index(...); # or bytes::index 42 ... length(...); # or bytes::length 43 ... ord(...); # or bytes::ord 44 ... rindex(...); # or bytes::rindex 45 ... substr(...); # or bytes::substr 46 no bytes; 47 48 49=head1 DESCRIPTION 50 51Perl's characters are stored internally as sequences of one or more bytes. 52This pragma allows for the examination of the individual bytes that together 53comprise a character. 54 55Originally the pragma was designed for the loftier goal of helping incorporate 56Unicode into Perl, but the approach that used it was found to be defective, 57and the one remaining legitimate use is for debugging when you need to 58non-destructively examine characters' individual bytes. Just insert this 59pragma temporarily, and remove it after the debugging is finished. 60 61The original usage can be accomplished by explicit (rather than this pragma's 62implicit) encoding using the L<Encode> module: 63 64 use Encode qw/encode/; 65 66 my $utf8_byte_string = encode "UTF8", $string; 67 my $latin1_byte_string = encode "Latin1", $string; 68 69Or, if performance is needed and you are only interested in the UTF-8 70representation: 71 72 utf8::encode(my $utf8_byte_string = $string); 73 74C<no bytes> can be used to reverse the effect of C<use bytes> within the 75current lexical scope. 76 77As an example, when Perl sees C<$x = chr(400)>, it encodes the character 78in UTF-8 and stores it in C<$x>. Then it is marked as character data, so, 79for instance, C<length $x> returns C<1>. However, in the scope of the 80C<bytes> pragma, C<$x> is treated as a series of bytes - the bytes that make 81up the UTF8 encoding - and C<length $x> returns C<2>: 82 83 $x = chr(400); 84 print "Length is ", length $x, "\n"; # "Length is 1" 85 printf "Contents are %vd\n", $x; # "Contents are 400" 86 { 87 use bytes; # or "require bytes; bytes::length()" 88 print "Length is ", length $x, "\n"; # "Length is 2" 89 printf "Contents are %vd\n", $x; # "Contents are 198.144 (on 90 # ASCII platforms)" 91 } 92 93C<chr()>, C<ord()>, C<substr()>, C<index()> and C<rindex()> behave similarly. 94 95For more on the implications, see L<perluniintro> and L<perlunicode>. 96 97C<bytes::length()> is admittedly handy if you need to know the 98B<byte length> of a Perl scalar. But a more modern way is: 99 100 use Encode 'encode'; 101 length(encode('UTF-8', $scalar)) 102 103=head1 LIMITATIONS 104 105C<bytes::substr()> does not work as an I<lvalue()>. 106 107=head1 SEE ALSO 108 109L<perluniintro>, L<perlunicode>, L<utf8>, L<Encode> 110