"Sputnik" help  
Sputnik Help
BinaryWalk(<binary>, <flags>, <callback>, [<checkCallback>])

Description

Iterates over a binary string and performs manipulations based on a specified callback function.

Parameters

<binary> The binary string to iterate over.
<flags> The flags that control the behavior of the iteration. It is an value of BinWalkTypes.
<callback> The callback function that will be invoked for each iteration. It takes three parameters: index (current index in the binary string), type (current data type of the value), and value (current value at the index). The callback function should return the modified value.
<checkCallback> Optional check callback function that determines whether the callback function should be executed for each iteration. If not specified, all iterations will execute the callback function.

Return Value

Success: If the @BinWalkClone flag is set in the flags parameter, the function returns a modified copy of the binary string, preserving the original.
If the @BinWalkClone flag is not set, the function modifies the binary string in-place and returns nothing.
Failure: Returns null.

Remarks

The BinaryWalk function allows you to iterate over a binary string and perform manipulations on it using a callback function. You can use the flags parameter to control the behavior of the iteration, such as changing the index or data type. The callback function is called for each iteration, providing the current index, data type, and value. The callback function should modify the value and return the modified value. If a check callback function is provided, it determines whether the callback function should be executed for each iteration.

When using an anonymous code block as the callback in the BinaryWalk function, you can access the values of the index, type, and value of each iteration. The names to refer to these values are "index", "type", and "value", respectively. However, please note that "index" and "type" will only exist if the corresponding flags for index and type (@BinWalkIndex/@BinWalkIndexChg and @BinWalkType/@BinWalkTypeChg) are specified. You can include these names in your anonymous code block to manipulate the binary string based on the current index, type, and value.

Related

Example

A basic example:

my $bin = bin("Hello World");
say $bin;
BinaryWalk($bin, @BinWalkNone,
Function ($v)
{
    if ($v != ' ')
        $v += 1;
    return $v;
});
say $bin;

// PRINTS
// Hello World
// Ifmmp Xpsme

The code uses the BinaryWalk function to iterate over a binary string representation of "Hello World". Inside the iteration, a callback function increments each character by 1, excluding spaces. The resulting modified binary string, "Ifmmp Xpsme", is then printed. This demonstrates how BinaryWalk allows for custom modifications to be applied to binary strings during iteration.

Same as above but shorter:

my $bin = bin("Hello World");
say $bin;
BinaryWalk($bin, @BinWalkNone, {{ return $value != ' ' ? $value + 1 : $value; }});
say $bin;

// PRINTS
// Hello World
// Ifmmp Xpsme

The code defines a binary string $bin using the bin() function with the value "Hello World". The initial value of $bin is printed. Then, the BinaryWalk function is called on $bin with the @BinWalkNone flag and an anonymous code block as the callback. Inside the code block, each character in the binary string is incremented by 1 if it is not a space character. The modified binary string, "Ifmmp Xpsme", is then printed. This example showcases the use of anonymous code blocks in Sputnik for customizing the behavior of the BinaryWalk function.

A complex example:

my $bin = Pack("iiff", 777, 4242, 13.77, 44.22);
BinaryWalk($bin, @BinWalkIndexChg | @BinWalkTypeChg | @BinWalkAsInt32,
Function ($idx, $type, $v)
{
    if (*$idx == 4)
        *$type = @TypeFloat;
    *$idx += 4;
    $v *= 2;
    return $v;
});
say (^Int32)$bin[0:4];
say (^Int32)$bin[4:8];
say (^Float)$bin[8:12];
say (^Float)$bin[12:16];

// PRINTS
// 1554
// 8484
// 26
// 88

The code demonstrates the usage of the BinaryWalk function to iterate over a binary string and modify its values based on specific conditions. Here's a breakdown of what's happening:

The printed values demonstrate the modifications made during the iteration, showing the updated values as 1554, 8484, 26, and 88.
In summary, the BinaryWalk function allows you to iterate over a binary string, modify values based on specific conditions, and interpret the values as different types during iteration. The example showcases how the callback function can change the type and modify the values in the binary string.


Contact
Cheryl (uberfox@hotmail.com)
Homepage
http://ubersoft.org