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

Description

Appends an unsigned integer value to the end of a binary string using the specified size and endian.

Parameters

<binary> A binary string to read fromo.
<pos> The position to read from.
<size> Size SizeCode to read with.
[<endian>] The endian to read with. (Default: @EndianNative)

Return Value

Success: Returns the read value as an unsigned integer.
Failure: Returns null.

Remarks

The BinaryAppendValue function allows you to add an unsigned integer value to the end of a binary string. The size parameter determines the size of the value to be appended, 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.

Related

BinaryWriteValue, BinaryAppendValue

Example

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);

// PRINTS
// 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);

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

 


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