"Sputnik" help  
Sputnik Help
BinaryWriteValue(<binary>, <pos>, <size>, <value>, [<endian>])


Writes an unsigned integer value to a binary string at a specified position using the specified size and endian.


<binary> A binary string to write to.
<pos> The position to write to.
<size> Size SizeCode to write with.
<value> The value to write. It will be written as an unsigned integer.
[<endian>] The endian to append as. (Default: @EndianNative)

Return Value

Success: Returns true.
Failure: Returns false.


The BinaryWriteValue function allows you to write an unsigned integer value to a binary string at a specific position. The size parameter determines the size of the value to be written, while the optional endian parameter specifies the byte order. If the endian parameter is not provided, the native endian format is used.

The use of direct casting and unsigned integers is crucial to ensure proper manipulation and interpretation of binary data. Direct casting allows for the reinterpretation of the underlying bits of a value as an unsigned integer, without performing any conversion or interpretation. By utilizing unsigned integers, these functions offer a generic approach to working with binary data, allowing for flexibility and compatibility across various data types. It is important to understand and correctly apply direct casting to ensure accurate reading and writing of values from and to the binary string.


BinaryReadValue, BinaryAppendValue


A large example where integers are appended onto a new binary string then read back then finally a value is written at a specific position and read back to demonstrate read/write/append:

my $bin = bin();

BinaryAppendValue($bin, @SizeCodeDWord, (^UInt32)777);
BinaryAppendValue($bin, @SizeCodeDWord, (^UInt32)-74242);
BinaryAppendValue($bin, @SizeCodeDWord, (^UInt32)@Int32Min);
BinaryAppendValue($bin, @SizeCodeDWord, (^UInt32)@Int32Max);

say (^Int32)SignExtend(BinaryReadValue($bin, 0, @SizeCodeDWord), @SizeCodeDWord);
say (^Int32)SignExtend(BinaryReadValue($bin, 4, @SizeCodeDWord), @SizeCodeDWord);
say (^Int32)SignExtend(BinaryReadValue($bin, 8, @SizeCodeDWord), @SizeCodeDWord);
say (^Int32)SignExtend(BinaryReadValue($bin, 12, @SizeCodeDWord), @SizeCodeDWord);

BinaryWriteValue($bin, 4, @SizeCodeDWord, (^UInt32)-777);
say (^Int32)SignExtend(BinaryReadValue($bin, 4, @SizeCodeDWord), @SizeCodeDWord);

// 777
// -74242
// -2147483648
// 2147483647
// -777

The use of Direct Casting is important here since this read/write/append does not use anything but unsigned integers so to read things back properly we must cast properly.

With a few simple macros it becomes easier to make:

#define BinaryAddInt32(data, value) (BinaryAppendValue(data, @SizeCodeDWord, (^UInt32)value))
#define BinarySetInt32(data, pos, value) (BinaryWriteValue(data, pos, @SizeCodeDWord, (^UInt32)value))
#define BinaryGetInt32(data, pos) ((^Int32)SignExtend(BinaryReadValue(data, pos, @SizeCodeDWord), @SizeCodeDWord))

my $bin = bin();

BinaryAddInt32($bin, 777);
BinaryAddInt32($bin, -74242);
BinaryAddInt32($bin, @Int32Min);
BinaryAddInt32($bin, @Int32Max);

say BinaryGetInt32($bin, 0);
say BinaryGetInt32($bin, 4);
say BinaryGetInt32($bin, 8);
say BinaryGetInt32($bin, 12);

BinarySetInt32($bin, 4, -777);
say BinaryGetInt32($bin, 4);

// 777
// -74242
// -2147483648
// 2147483647
// -777


Cheryl (uberfox@hotmail.com)