"Sputnik" help  
Sputnik Help
BinaryReadSlice(<binary>, [<offset>], [<end>], [<step>])

Description

Reads a slice of bytes from a binary string and returns the resulting slice as a new binary string. The BinaryReadSlice function allows you to extract a portion of the binary string using slice-like syntax.

Parameters

<binary> The binary string from which to read the slice.
<start> Optional starting index of the slice. If not specified, the slice will start from the beginning of the binary string. Negative values are supported, indicating an offset from the end of the string.
<stop> Optional ending index of the slice. If not specified, the slice will extend to the end of the binary string. Negative values are supported, indicating an offset from the end of the string.
<step> Optional step size for the slice. If not specified, the default step size of 1 will be used, meaning every byte will be included in the slice. Negative values are supported for reverse traversal of the string.

Return Value

Success: Returns a new binary string representing the slice of bytes read from the input binary string.
Failure: Returns null if the position is out of bounds or an error occurs during reading.

Remarks

The BinaryReadSlice function operates on the byte level, treating the binary string as a sequence of bytes. It does not interpret or modify the data in any specific format.
If the specified start or stop indices are out of bounds of the binary string, the function will return an empty binary string.
If the step size is positive, the start index should be less than the stop index for the slice to be valid. If the step size is negative, the start index should be greater than the stop index for the slice to be valid.
Negative indices, offset, and step allow for convenient slicing and traversal of binary strings.

Related

BinaryWriteSlice

Example

Example of usage:

my $a = BinNew(16);

my $bin = bin("Hello!");
BinaryWriteSlice($a, $bin, 4, 0, 1);

say BinaryExpand($a, false);

say "Slice:";
say BinaryExpand(BinaryReadSlice($a, 4, 10), false);
    
// PRINTS
// 00 00 00 00 48 65 6C 6C 6F 21 00 00 00 00 00 00 ....Hello!......
// Slice:
// 48 65 6C 6C 6F 21 -- -- -- -- -- -- -- -- -- -- Hello!

Stepping example:

my $a = BinNew(16);

my $bin = bin("Hello!");
BinaryWriteSlice($a, $bin, 4, 0, 2);

say BinaryExpand($a, false);

say "Slice:";
say BinaryExpand(BinaryReadSlice($a, 4, 16), false);
    
// PRINTS
// 00 00 00 00 48 00 65 00 6C 00 6C 00 6F 00 21 00 ....H.e.l.l.o.!.
// Slice:
// 48 00 65 00 6C 00 6C 00 6F 00 21 00 -- -- -- -- H.e.l.l.o.!.

Reverse example:

my $a = BinNew(16);

my $bin = bin("Hello!");
BinaryWriteSlice($a, $bin, 8, 0, -1);

say BinaryExpand($a, false);

say "Slice:";
say BinaryExpand(BinaryReadSlice($a, 4, 10), false);
    
// PRINTS
// 00 00 00 21 6F 6C 6C 65 48 00 00 00 00 00 00 00 ...!olleH.......
// Slice:
// 6F 6C 6C 65 48 00 -- -- -- -- -- -- -- -- -- -- olleH.

 


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