"Sputnik" help  
Sputnik Help
PackSingle(<formatString>, <variable>)

Description

The UnpackSingle function is a highly optimized version of the Unpack function, specifically designed for unpacking a single element from a binary representation. It is particularly useful when you only need to extract a single value, such as integers or floats, from a binary string without the need to parse a format string. This optimized approach ensures efficient and fast extraction of the desired element.

To use UnpackSingle, you need to provide the appropriate format specifier as the first argument, the position of the element within the binary string as the second argument, and the binary string itself as the third argument. By specifying the format specifier that corresponds to the data type of the element you want to extract, you can quickly retrieve the desired value from the binary string.

The UnpackSingle function returns the unpacked value as an object of the appropriate data type. It is crucial to ensure the success of the unpacking operation and the validity of the format specifier and binary string. In case of any errors or unsupported format specifiers, it is recommended to implement proper error handling and validation. Additionally, checking the returned value for null or empty data can help identify potential issues during the unpacking process.

In summary, the UnpackSingle function provides a highly efficient and optimized solution for extracting a single element, such as integers or floats, from a binary representation. It enables swift and accurate retrieval of data, making it ideal for scenarios that require high-performance unpacking of individual elements from binary strings.


Format Specifier

See Pack for a full explanation of the format specifier.
(Bare in mind these format specifiers are specific to PackSingle make sure to read UnpackSingle to get its specifiers)

a	NUL-padded ASCII string
A SPACE-padded ASCII string
Z NUL-padded ASCII string with NUL-terminator
u UU-encoded string
b Bit string (ascending bit order inside each byte)
B Bit string (descending bit order inside each byte)
h Hex string (low nibble first)
H Hex string (high nibble first)
c Signed ASCII char
C Unsigned ASCII char
U Signed Unicode char (16-bit, machine byte order)
W Unsigned Unicode char (16-bit, machine byte order)
i Signed integer (32-bit, machine byte order)
I Unsigned integer (32-bit, machine byte order)
s Signed short (16-bit, machine byte order)
G Signed short (always 16-bit, big endian byte order)
g Signed short (always 16-bit, little endian byte order)
S Unsigned short (16-bit, machine byte order)
n Unsigned short (16-bit, big endian byte order)
v Unsigned short (16-bit, little endian byte order)
l Signed long (32-bit, machine byte order)
E Signed long (always 32-bit, big endian byte order)
e Signed long (always 32-bit, little endian byte order)
L Unsigned long (32-bit, machine byte order)
N Unsigned long (32-bit, big endian byte order)
V Unsigned long (32-bit, little endian byte order)
Q Unsigned quad (64-bit) value (machine byte order)
K Unsigned quad (64-bit) value (big endian byte order)
J Unsigned quad (64-bit) value (little endian byte order)
q Signed quad (64-bit) value (machine byte order)
k Signed quad (64-bit) value (big endian byte order)
j Signed quad (64-bit) value (little endian byte order)
f Float (machine dependent size and representation)
Y Float (big endian byte order)
y Float (little endian byte order)
d Double (machine dependent size and representation)
R Double (big endian byte order)
r Double (little endian byte order)
t Signed pointer
T Unsigned pointer
z7 String encoded as UTF8 with 1-byte null terminator
z6 String encoded as UTF7 with 1-byte null terminator
z5 String encoded as UTF16 with 2-byte null terminator
z4 String encoded as BigEndianUnicode with 2-byte null terminator
z3 String encoded as UTF32 big endian with 4-byte null terminator
z2 String encoded as UTF32 with 4-byte null terminator
z1 String encoded as ASCII with 1-byte null terminator
z0 String encoded as ASCII without a null terminator

The PackSingle function offers a user-friendly and straightforward approach for efficiently packing a single element into a binary representation. With its optimized design and elimination of the format string parsing, it provides a simple and intuitive solution for converting variables into binary strings. If you're new to binary packing or looking for a quick and easy way to pack a single element, PackSingle is the ideal choice. To see practical examples and understand how to use this function effectively, refer to the documentation or sample code, which will demonstrate its simplicity and convenience.

Parameters

<formatString> A string specifying the format of the packing. It consists of format specifiers that define how each variable should be packed.
<variable> A variable to be packed into binary data according to the format string.

Return Value

Success: Returns the packed binary data as a binary string if the packing operation was successful.
Failure: Returns empty binary data if an error occurred during the packing process.

Remarks

This is almost the same as Pack( ) but designed to only do one operation thus avoiding the need for excessive parsing and what not as a result it is faster.

Related

UnpackSingle, Pack, Unpack

Example

Basic example:

// Pack 1337 into binary
my $a = PackSingle("i", 1337);
// Pack 777 into binary
my $b = PackSingle("i", 777);
// Combine them into a single binary
my $c = bin($a, $b); // We could use $a . $b
// Read the first number
say UnpackSingle("i", $c);
// Read the first number (must use index)
say UnpackSingle("i", $c, 4);
 
// PRINTS
// 1337
// 777

This time the binary is built up over time using the .= operator then the finished binary is looped over and it's values printed

// Pack numbers
my $bin = BinNew();
$bin .= PackSingle("i", 1337);
$bin .= PackSingle("i", 777);
$bin .= PackSingle("i", 42);
// Read the numbers
for(my $i = 0; $i < -c $bin; $i += @Int32Size)
    say UnpackSingle("i", $bin, $i);
 
// PRINTS
// 1337
// 777
// 42

Don't forget to see Pack.


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