vec

Perl 5 version 10.1 documentation

Go to top

Home > Language reference > Functions > vec

Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled, or are running a non-JavaScript capable web browser.

To get the best experience, please enable JavaScript or download a modern web browser such as Internet Explorer 8, Firefox, Safari, or Google Chrome.

vec

Perl functions A-Z | Perl functions by category | The 'perlfunc' manpage

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
```
    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), this is ignored by vec, and it operates on the internal byte string, not the conceptual character string, even if you only have characters with values less than 256.

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:
```
    $bits = unpack("b*", $vector);
    @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:
```
    #!/usr/bin/perl -wl
    print <<'EOT';
                                      0         1         2         3
                       unpack("V",$_) 01234567890123456789012345678901
    ------------------------------------------------------------------
    EOT
    for $w (0..3) {
        $width = 2**$w;
        for (="../index.html">Home >
    
      
        Language reference >
      
        Functions >
      
    
    vec
  

            
```

Please note: Many features of this site require JavaScript. You appear to have JavaScript disabled, or are running a non-JavaScript capable web browser.

To get the best experience, please enable JavaScript or download a modern web browser such as Internet Explorer 8, Firefox, Safari, or Google Chrome.

vec

Perl functions A-Z | Perl functions by category | The 'perlfunc' manpage

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
```
    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), this is ignored by vec, and it operates on the internal byte string, not the conceptual character string, even if you only have characters with values less than 256.

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:
```
    $bits = unpack("b*", $vector);
    @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:
```
    #!/usr/bin/perl -wl
    print <<'EOT';
                                      0         1         2         3
                       unpack("V",$_) 01234567890123456789012345678901
    ------------------------------------------------------------------
    EOT
    for $w (0..3) {
        $width = 2**$w;
  
```