"Sputnik" help  
Sputnik Help
Unpack(<formatString>, <binary>, <flags>, [<delimiter>])

Description

Unpacks binary data based on the specified format and optional flags.

The Unpack function is used to unpack binary data (a string of bytes) into variables of different types according to a specified format. It allows you to extract data from a binary string and convert it into appropriate data types, such as integers, floats, strings, and more.

By providing a format string as the first argument and the binary data as the second argument, you can define how the binary data should be interpreted and unpacked into variables.

The format string consists of format specifiers that define the type and arrangement of the unpacked variables. Each format specifier represents a specific data type and determines the number of bytes used for unpacking. For example, the format specifier "i" represents a signed integer, while "f" represents a floating-point number.

The binary data can be provided as a binary string or an array of bytes. The Unpack function reads the binary data according to the specified format and extracts the corresponding values.

The Unpack function returns the unpacked data based on the format. The return value can be a single value, an array of values, or an associative array depending on the format string and optional flags.

It's important to note that the format string and the binary data should be compatible. If the format string does not match the structure of the binary data, the unpacking operation may fail or produce unexpected results. Therefore, it's crucial to ensure that the format string accurately reflects the layout of the binary data.

In case of successful unpacking, the Unpack function returns the extracted data. However, if there are any errors or issues during the unpacking process, the function may return null or an empty result.

Overall, the Unpack function provides a convenient way to extract data from binary strings and convert them into their respective data types, enabling further processing and manipulation of the unpacked data.


Format Specifier

The Unpack function is used to extract data from a binary string and convert it into variables of different types according to a specified format. It provides the reverse operation of the Pack function, allowing you to unpack binary data into meaningful values.

The format specifier is a string pattern used in the Unpack function to define how the binary data should be interpreted and unpacked. It consists of format codes that represent specific data types and provide information about the size and endianness of the data.

Each format code within the format specifier indicates how to unpack a particular piece of data. The order of the format codes in the string should match the order of the data in the binary string.

Here are some commonly used format codes:

"a": Unpack a string (null-padded)
"A": Unpack a string (space-padded)
"c": Unpack a signed char
"C": Unpack an unsigned char
"s": Unpack a signed short (16-bit)
"S": Unpack an unsigned short (16-bit)
"i": Unpack a signed integer (32-bit)
"I": Unpack an unsigned integer (32-bit)
"l": Unpack a signed long (32 or 64-bit, depending on the platform)
"L": Unpack an unsigned long (32 or 64-bit)
"f": Unpack a float (single-precision)
"d": Unpack a double (double-precision)
In addition to the basic format codes, you can use modifiers to specify the size and endianness of the unpacked data. For example, "n" indicates a short (16-bit) in network byte order (big-endian), and "v" indicates a short in little-endian byte order.

The Unpack function reads the binary string according to the specified format and extracts the corresponding values. It returns the unpacked data, which can be a single value, an array of values, or an associative array depending on the format and optional flags.

It's important to ensure that the format specifier accurately reflects the structure of the binary data to avoid errors or unexpected results during the unpacking process.

Here is the complete listing of format specifiers:
(Bare in mind these format specifiers are specific to Unpack make sure to read Pack to get its specifiers)

X: Decreases the position in the buffer by one byte without storing a value.
x: Advances the position in the buffer by one byte without storing a value.
u: Unpacks a uuencoded string.
b: Unpacks a bit string with ascending bit order inside each byte.
B: Unpacks a bit string with descending bit order inside each byte.
a: Unpacks a NUL-padded ASCII string.
A: Unpacks a SPACE-padded ASCII string.
Z: Unpacks a NUL-padded ASCII string with NUL-terminator.
h: Unpacks a hex string with low/high nibble first.
H: Unpacks a hex string with high/low nibble first.
c: Unpacks a signed ASCII character.
C: Unpacks an unsigned ASCII character.
U: Unpacks a signed Unicode character.
W: Unpacks an unsigned Unicode character.
s: Unpacks a signed short (16-bit, machine byte order).
S: Unpacks an unsigned short (16-bit, machine byte order).
n: Unpacks an unsigned short (16-bit, big endian byte order).
v: Unpacks an unsigned short (16-bit, little endian byte order).
G: Unpacks a signed short (16-bit, big endian byte order).
g: Unpacks a signed short (16-bit, little endian byte order).
k: Unpacks a signed quad (64-bit, big endian byte order).
j: Unpacks a signed quad (64-bit, little endian byte order).
i: Unpacks a signed integer (32-bit, machine byte order).
l: Unpacks a signed long (32-bit, machine byte order).
I: Unpacks an unsigned integer (32-bit, machine byte order).
L: Unpacks an unsigned long (32-bit, machine byte order).
E: Unpacks a signed long (32-bit, big endian byte order).
e: Unpacks a signed long (32-bit, little endian byte order).
q: Unpacks a signed quad (64-bit, machine byte order).
Q: Unpacks an unsigned quad (64-bit, machine byte order).
N: Unpacks an unsigned long (32-bit, big endian byte order).
V: Unpacks an unsigned long (32-bit, little endian byte order).
K: Unpacks an unsigned quad (64-bit, big endian byte order).
J: Unpacks an unsigned quad (64-bit, little endian byte order).
f: Unpacks a float (32-bit, machine dependent size and representation).
d: Unpacks a double (64-bit, machine dependent size and representation).
p: Unpacks a pointer to a null-terminated string.
P: Unpacks a pointer to a fixed-length string.
t: Unpacks a signed pointer.
T: Unpacks an unsigned pointer.
z: Unpacks a string with various encoding options.

Note: In Sputnik, the Pack function provides flexibility in matching format specifiers with the actual packing variables. Sputnik dynamically converts the variables to match the specified format specifier, even if they do not match in their original form.

For example, you can pack a string representation of an integer, such as "777," using the format specifier "i" for integer. Sputnik will automatically convert the string to an integer during the packing process, ensuring compatibility between the format specifier and the variable.

While this dynamic conversion feature can be convenient, it is essential to ensure that the chosen format specifier accurately represents the intended data type and format of the packed variable. Using incompatible or incorrect format specifiers may lead to unexpected results or errors during the packing process.

Therefore, it is recommended to use format specifiers that best match the intended data type and adhere to proper data conversion practices. This ensures that the packed binary data reflects the desired format and can be correctly interpreted during subsequent unpacking or processing operations.

By understanding the dynamic conversion capabilities of Sputnik and selecting appropriate format specifiers, you can effectively utilize the Pack function to pack variables of different types into binary representations, accommodating the dynamic nature of the language and enabling versatile data manipulation tasks

Parameters

<formatString> The format string for unpacking.
<binary> The binary data to be unpacked.
<flags> Optional flags for unpacking.
[<delimiter>] Optional delimiter for string unpacking. (Default: empty string)

Return Value

Success: Returns the unpacked data based on the format and flags.
Failure: Returns null.

Remarks

The Unpack function unpacks binary data according to the specified format string. The format string defines the structure of the binary data and determines how it is interpreted and converted into appropriate data types.

The <format> parameter follows a syntax similar to Perl/PHP's unpack function. It consists of format specifiers that represent the desired data types and their arrangement in the binary data.

For string unpacking, an optional <delimiter> can be provided to join the unpacked string elements. If no delimiter is specified, the unpacked string elements are joined without any separation.

The optional <flags> parameter allows additional control over the unpacking process. Currently supported flags include:

@Array: Unpacks the data as an associative array.
@String: Unpacks the data as a string, using the specified <delimiter> for joining string elements.
@Single: Unpacks a single value from the binary data.
@SingleOrArray: Unpacks a single value if the binary data contains only one element, or returns an array if multiple elements are present.
@Variables: This is an addition flag to

The flags can be found in the Macro section.

Related

UnpackSingle, Pack, PackSingle

Example

Unpacking a string and an integer from a binary string:

my $data = (Binary)"Hello\x03\x00\x00\x00";
my list($str, $num) = Unpack("a5/i", $data);
say $str;
say $num;
// PRINTS
// Hello
// 3

Packing and Unpacking floats:

my $data = Pack("f*", 777.42, 12.7, 313.37);
my $floats = Unpack("f*", $data);
foreach (my $float in $floats)
    say $float;
// PRINTS
// 777.42
// 12.7
// 313.37

Packing and Unpacking an IP address with a port:

my $data = pack("C5", 192, 168, 0, 1, 80);
my list($ip1, $ip2, $ip3, $ip4, $port) = Unpack("C5", $data);
say "$ip1.$ip2.$ip3.$ip4:$port";
// PRINTS
// 192.168.0.1:80

Unpacking to keys:

my $data = "\x01\x02\x03\x04\x05\x06\x07\x08";
my $result = unpack("C2chars/Sint/Nlong", $data);
printr($result);
// PRINTS
// Array
// (
//     [chars1] => 1
//     [chars2] => 2
//     [int] => 1027
//     [long] => 84281096
// )

Using the Variables flag:

my $data = "\x01\x02\x03\x04\x05\x06\x07\x08";
unpack("C2chars/Sint/Nlong", $data, @UnpackArray | @UnpackVariables);
say $chars1;
say $chars2;
say $int;
say $long;
// // PRINTS
// 1
// 2
// 1027
// 84281096

Technically we could have just used the Variables flag by itself since Array is default but it was added just to show you how to combine them.

Of course the normal way to get the variables is to do this:

my $data = "\x01\x02\x03\x04\x05\x06\x07\x08";
my list($chars1, $chars2, $int, $long) = unpack("C2/S/N", $data);
say $chars1;
say $chars2;
say $int;
say $long;
// // PRINTS
// 1
// 2
// 1027
// 84281096
However the Variables flag provides a shorter and easier way.

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