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

Description

Writes a slice of bytes from a given value to a binary string. The BinaryWriteSlice function allows you to overwrite a portion of a binary string with the bytes from the specified value.

Parameters

<binary> The binary string to write the slice to.
<value> The value from which to extract the slice.
<offset> Optional starting index of the slice. If not specified, the slice starts at the beginning of the binary string. Negative values are supported, indicating an offset from the end of the string.
<end> Optional ending index of the slice. If not specified, the slice extends 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 is used, meaning every byte is included in the slice. Negative values are supported for reverse traversal of the string.

Return Value

Success: Returns true of the slice was written correctly.
Failure: Returns null if the position is out of bounds or an error occurs during writing.

Remarks

The BinaryWriteSlice function operates on the byte level, treating the binary string as a sequence of bytes. It allows you to replace a portion of the binary string with the bytes from another value.
If the specified <offset> or <end> indices are out of bounds of the binary string, the function does not modify the string.
If the <step> size is positive, the <offset> index should be less than the <end> index for the slice to be valid. If the <step> size is negative, the <offset> index should be greater than the <end> index for the slice to be valid.
Negative indices, offsets, and steps allow for convenient slicing and traversal of binary strings.

Related

BinaryReadSlice

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