lib/bytes.pm

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