Core Function Vec

Revision as of 19:55, 24 September 2013

Vec( <expression>, <offset>, <bits>, <value> )

Description

Treats the string in EXPRESSION 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 and optionally sets BITS in the string to a given value.

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.

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, by using the value parameter example:

vec($image, $max_x * $x + $y, 8, 3); // Settting value 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, Spunik 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).

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.

Parameters

expression

The string to use.

offset

Offset is the marker for the end of the vector, and it counts back the number of bits specified to find the start.

bits

Return Value

Success: Returns a string with backslashes stripped off. (\' becomes ' and so on.) Double backslashes (\\) are made into a single backslash (\).

Failure: Returns empty string.

Remarks

This function is inspired by Perl's Vec() function and any tutorial you find on that should work on this provided you remember the difference that this uses a 4th parameter for the value instead of =.

This function is smart enough to know if it should increase the strings size or not therefor it will return/edit the parts of the string you wish to without rebuilding the string each time this is significantly faster than recreating the string every time.

In Sputnik strings are immutable and also not immutable... For most operations a new string will be returned and the old one replaced however that is not the rule there are a number of functions that will modify the string in place and Vec() is one of them.

You can also modify strings in place yourself using the Fixed() statement.

Example

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
printf "Char '%1^c' Byte '%1^d'\n", 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"
printf "\$foo is '%s'\n", $foo;
// Prints
// $foo is 'PerlPerlPerl'
 
// Lets replace the middle Perl with Lrep
vec($foo, 1, 32, 0x4C726570); # 'Perl'
printf "\$foo is '%s'\n", $foo;
// $foo is 'PerlLrepPerl'