add vec() example from Chaim Frenkel <chaimf@pobox.com>
Gurusamy Sarathy [Mon, 11 Oct 1999 23:11:57 +0000 (23:11 +0000)]
p4raw-id: //depot/perl@4348

pod/perlfunc.pod

index 2dde78d..9105108 100644 (file)
@@ -5084,11 +5084,12 @@ See also C<keys>, C<each>, and C<sort>.
 
 =item vec EXPR,OFFSET,BITS
 
-Treats the string in EXPR as a vector of unsigned integers, and
-returns the value of the bit field specified by OFFSET.  BITS
-specifies the number of bits that are reserved for each entry in the
-bit vector.  This must be a power of two from 1 to 32 (or 64, if your
-platform supports that).
+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).
 
 C<vec> may also be assigned to, in which case parentheses are needed
 to give the expression the correct precedence as in
@@ -5106,6 +5107,10 @@ 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'
@@ -5125,6 +5130,171 @@ 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 C<*>.
 
+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 is run, the above
+example 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
+
 =item wait
 
 Behaves like the wait(2) system call on your system: it waits for a child