Perl 5 version 26.3 documentation

vec

  • vec EXPR,OFFSET,BITS

    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

    1. 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.

    1. my $foo = '';
    2. vec($foo, 0, 32) = 0x5065726C; # 'Perl'
    3. # $foo eq "Perl" eq "\x50\x65\x72\x6C", 32 bits
    4. print vec($foo, 0, 8); # prints 80 == 0x50 == ord('P')
    5. vec($foo, 2, 16) = 0x5065; # 'PerlPe'
    6. vec($foo, 3, 16) = 0x726C; # 'PerlPerl'
    7. vec($foo, 8, 8) = 0x50; # 'PerlPerlP'
    8. vec($foo, 9, 8) = 0x65; # 'PerlPerlPe'
    9. vec($foo, 20, 4) = 2; # 'PerlPerlPe' . "\x02"
    10. vec($foo, 21, 4) = 7; # 'PerlPerlPer'
    11. # 'r' is "\x72"
    12. vec($foo, 45, 2) = 3; # 'PerlPerlPer' . "\x0c"
    13. vec($foo, 93, 1) = 1; # 'PerlPerlPer' . "\x2c"
    14. vec($foo, 94, 1) = 1; # 'PerlPerlPerl'
    15. # 'l' is "\x6c"

    To transform a bit vector into a string or list of 0's and 1's, use these:

    1. my $bits = unpack("b*", $vector);
    2. my @bits = split(//, unpack("b*", $vector));

    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:

    1. #!/usr/bin/perl -wl
    2. print <<'EOT';
    3. 0 1 2 3
    4. unpack("V",$_) 01234567890123456789012345678901
    5. ------------------------------------------------------------------
    6. EOT
    7. for $w (0..3) {
    8. $width = 2**$w;
    9. for ($shift=0; $shift < $width; ++$shift) {
    10. for ($off=0; $off < 32/$width; ++$off) {
    11. $str = pack("B*", "0"x32);
    12. $bits = (1<<$shift);
    13. vec($str, $off, $width) = $bits;
    14. $res = unpack("b*",$str);
    15. $val = unpack("V", $str);
    16. write;
    17. }
    18. }
    19. }
    20. format STDOUT =
    21. vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
    22. $off, $width, $bits, $val, $res
    23. .
    24. __END__

    Regardless of the machine architecture on which it runs, the example above should print the following table:

    1. 0 1 2 3
    2. unpack("V",$_) 01234567890123456789012345678901
    3. ------------------------------------------------------------------
    4. vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
    5. vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
    6. vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
    7. vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
    8. vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
    9. vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
    10. vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
    11. vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
    12. vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
    13. vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
    14. vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
    15. vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
    16. vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
    17. vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
    18. vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
    19. vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
    20. vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
    21. vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
    22. vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
    23. vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
    24. vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
    25. vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
    26. vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
    27. vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
    28. vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
    29. vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
    30. vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
    31. vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
    32. vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
    33. vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
    34. vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
    35. vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
    36. vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
    37. vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
    38. vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
    39. vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
    40. vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
    41. vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
    42. vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
    43. vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
    44. vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
    45. vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
    46. vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
    47. vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
    48. vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
    49. vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
    50. vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
    51. vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
    52. vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
    53. vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
    54. vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
    55. vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
    56. vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
    57. vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
    58. vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
    59. vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
    60. vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
    61. vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
    62. vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
    63. vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
    64. vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
    65. vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
    66. vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
    67. vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
    68. vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
    69. vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
    70. vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
    71. vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
    72. vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
    73. vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
    74. vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
    75. vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
    76. vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
    77. vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
    78. vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
    79. vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
    80. vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
    81. vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
    82. vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
    83. vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
    84. vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
    85. vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
    86. vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
    87. vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
    88. vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
    89. vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
    90. vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
    91. vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
    92. vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
    93. vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
    94. vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
    95. vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
    96. vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
    97. vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
    98. vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
    99. vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
    100. vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
    101. vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
    102. vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
    103. vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
    104. vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
    105. vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
    106. vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
    107. vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
    108. vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
    109. vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
    110. vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
    111. vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
    112. vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
    113. vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
    114. vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
    115. vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
    116. vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
    117. vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
    118. vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
    119. vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
    120. vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
    121. vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
    122. vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
    123. vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
    124. vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
    125. vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
    126. vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
    127. vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
    128. vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
    129. vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
    130. vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
    131. vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001