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

Description

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

Parameters

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

Return Value

Success: Returns true.
Failure: Returns false.

Remarks

The BinaryReadValue function allows you to retrieve an unsigned integer value from a binary string at a specified position. The size parameter determines the size of the value to be read, 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, BinaryReadValue, 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