vec
EXPR
,
OFFSET
,
BITS
This function treats a string (the value of
EXPR
) as a vector of
unsigned integers, and returns the value of the element specified by
OFFSET
and
BITS
.
The function may also be assigned to, which causes the element to be
modified.
The purpose of the function is to provide very compact storage of lists of
small integers. The integers may be very small  vectors can hold
numbers that are as small as one bit, resulting in a bitstring.
The
OFFSET
specifies how many elements to skip over to find the one you
want.
BITS
is the number of bits per element in the vector, so each
element can contain an unsigned integer in the range
0..(2**
BITS
)
1
.
BITS
must be one of
1
,
2
,
4
,
8
,
16
, or
32
. As many elements as possible are packed into each byte, and
the ordering is such that
vec($vectorstring,0,1)
is guaranteed
to go into the lowest bit of the first byte of the string. To find
out the position of the byte in which an element is going to be put,
you have to multiply the
OFFSET
by the number of elements per
byte. When
BITS
is 1, there are eight elements per byte. When
BITS
is 2,
there are four elements per byte. When
BITS
is 4, there are two elements (called nybbles)
per byte. And so on.
Regardless of whether your machine is bigendian or littleendian,
vec($foo, 0, 8)
always refers to the first byte of string
$foo
. See
select
for
examples of bitmaps generated with
vec
.
Vectors created with
vec
can also be
manipulated with the logical operators

,
&
,
^
, and
~
, which
will assume a bit vector operation is desired when the operands are strings.
A bit vector (
BITS == 1
) can be translated to or from
a string of 1s and 0s by supplying a
b*
template to
unpack
or
pack
. Similarly, a vector of nybbles (
BITS ==
4
) can be translated with an
h*
template.