Treats the string in EXPR as a bit vector made up of elements of width BITS and returns the value of the element specified by OFFSET as an unsigned integer. BITS therefore specifies the number of bits that are reserved for each element in the bit vector. This must be a power of two from 1 to 32 (or 64, if your platform supports that).
If BITS is 8, "elements" coincide with bytes of the input string.
If BITS is 16 or more, bytes of the input string are grouped into chunks
of size BITS/8, and each group is converted to a number as with
pack/unpack with
big-endian formats n
/N
(and analogously for BITS==64). See
pack for details.
If bits is 4 or less, the string is broken into bytes, then the bits
of each byte are broken into 8/BITS groups. Bits of a byte are
numbered in a little-endian-ish way, as in 0x01
, 0x02
,
0x04
, 0x08
, 0x10
, 0x20
, 0x40
, 0x80
. For example,
breaking the single input byte chr(0x36) into two groups gives a list
(0x6, 0x3)
; breaking it into 4 groups gives (0x2, 0x1, 0x3, 0x0)
.
vec may also be assigned to, in which case parentheses are needed to give the expression the correct precedence as in
- vec($image, $max_x * $x + $y, 8) = 3;
If the selected element is outside the string, the value 0 is returned. If an element off the end of the string is written to, Perl will first extend the string with sufficiently many zero bytes. It is an error to try to write off the beginning of the string (i.e., negative OFFSET).
If the string happens to be encoded as UTF-8 internally (and thus has
the UTF8 flag set), vec tries to convert it
to use a one-byte-per-character internal representation. However, if the
string contains characters with values of 256 or higher, that conversion
will fail. In that situation, vec will operate on the underlying buffer
regardless, in its internal UTF-8 representation.
Strings created with vec can also be
manipulated with the logical
operators |, &
, ^, and ~
. These operators will assume a bit
vector operation is desired when both operands are strings.
See Bitwise String Operators in perlop.
The following code will build up an ASCII string saying 'PerlPerlPerl'
.
The comments show the string after each step. Note that this code works
in the same way on big-endian or little-endian machines.
- my $foo = '';
- vec($foo, 0, 32) = 0x5065726C; # 'Perl'
- # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
- print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
- vec($foo, 2, 16) = 0x5065; # 'PerlPe'
- vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
- vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
- vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
- vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
- vec($foo, 21, 4) = 7; # 'PerlPerlPer'
- # 'r' is "\x72"
- vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
- vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
- vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
- # 'l' is "\x6c"
To transform a bit vector into a string or list of 0's and 1's, use these:
If you know the exact length in bits, it can be used in place of the *
.
Here is an example to illustrate how the bits actually fall in place:
- #!/usr/bin/perl -wl
- print <<'EOT';
- 0 1 2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- EOT
- for $w (0..3) {
- $width = 2**$w;
- for ($shift=0; $shift < $width; ++$shift) {
- for ($off=0; $off < 32/$width; ++$off) {
- $str = pack("B*", "0"x32);
- $bits = (1<<$shift);
- vec($str, $off, $width) = $bits;
- $res = unpack("b*",$str);
- $val = unpack("V", $str);
- write;
- }
- }
- }
- format STDOUT =
- vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
- $off, $width, $bits, $val, $res
- .
- __END__
Regardless of the machine architecture on which it runs, the example above should print the following table:
- 0 1 2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
- vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
- vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
- vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
- vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
- vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
- vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
- vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
- vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
- vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
- vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
- vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
- vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
- vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
- vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
- vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
- vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
- vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
- vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
- vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
- vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
- vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
- vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
- vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
- vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
- vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
- vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
- vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
- vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
- vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
- vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
- vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
- vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
- vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
- vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
- vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
- vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
- vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
- vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
- vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
- vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
- vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
- vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
- vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
- vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
- vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
- vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
- vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
- vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
- vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
- vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
- vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
- vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
- vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
- vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
- vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
- vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
- vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
- vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
- vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
- vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
- vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
- vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
- vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
- vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
- vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
- vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
- vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
- vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
- vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
- vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
- vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
- vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
- vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
- vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
- vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
- vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
- vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
- vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
- vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
- vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
- vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
- vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
- vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
- vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
- vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
- vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
- vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
- vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
- vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
- vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
- vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
- vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
- vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
- vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
- vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
- vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
- vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
- vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
- vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
- vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
- vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
- vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001