Core Function Unpack

Revision as of 23:13, 11 November 2011 (view source) UberFoX (Talk | contribs) (Created page with "<pre> Unpack( <expression>, <binary-array> ) </pre> === Description === Pack data into a binary array === expression === The format string to use. ==== binary-array ==== An...")		Latest revision as of 12:38, 14 June 2015 (view source) UberFoX (Talk | contribs) m (1 revision)
(28 intermediate revisions by one user not shown)
Line 1:		Line 1:
	<pre>		<pre>
−	Unpack( <expression>, <binary-array> )	+	Unpack( <format>, <data/binary-array>, <flag> )
	</pre>		</pre>
	=== Description ===		=== Description ===
−	Pack data into a binary array	+	Unpack data from a binary array
−		+
−	=== expression ===	+
−		+
−	The format string to use.	+
−		+
−	==== binary-array ====	+
−		+
−	An array of bytes such as one provided by the Pack function.	+
−		+
−	=== Return Value ===	+
−		+
−	Success: Returns the data requested as a int, double, string or an array of data.	+
−	Failure: Returns empty array.	+
−		+
−	=== Remarks ===	+
−		+
−	==== Control Specifiers ====	+
−		+
−	{| border="1" align="left" style="text-align:center;"	+
−	|Character	+
−	|Description	+
−	|-	+
−	|^	+
−	|Switch to big endian encoding	+
−	|-	+
−	|_	+
−	|Switch to little endian encoding	+
−	|-	+
−	|%	+
−	|Switch to host (native) encoding	+
−	|-	+
−	|!	+
−	|Aligns the next data type to its natural boundary, for example for a double that would be 8 bytes, for a 32-bit int, that would be 4 bytes. For strings this is set to 4.	+
−	|-	+
−	|N	+
−	|A number between 1 and 9, indicates a repeat count (process N items with the following datatype	+
−	|-	+
−	|[N]	+
−	|For numbers larger than 9, use brackets, for example [20]	+
−	|-	+
−	|*	+
−	|Repeat the next data type until the arguments are exhausted	+
−	|}	+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−	==== Data Encoding ====	+
−		+
−	{| border="1" align="left" style="text-align:center;"	+
−	|Character	+
−	|Description	+
−	|-	+
−	|s	+
−	|Int16	+
−	|-	+
−	|S	+
−	|UInt16	+
−	|-	+
−	|i	+
−	|Int32	+
−	|-	+
−	|I	+
−	|UInt32	+
−	|-	+
−	|l	+
−	|Int64	+
−	|-	+
−	|L	+
−	|UInt64	+
−	|-	+
−	|f	+
−	|float	+
−	|-	+
−	|d	+
−	|double	+
−	|-	+
−	|b	+
−	|byte	+
−	|-	+
−	|c	+
−	|1-byte signed character	+
−	|-	+
−	|C	+
−	|1-byte unsigned character	+
−	|-	+
−	|z8	+
−	|string encoded as UTF8 with 1-byte null terminator	+
−	|-	+
−	|z6	+
−	|string encoded as UTF16 with 2-byte null terminator	+
−	|-	+
−	|z7	+
−	|string encoded as UTF7 with 1-byte null terminator	+
−	|-	+
−	|zb	+
−	|string encoded as BigEndianUnicode with 2-byte null terminator	+
−	|-	+
−	|z3	+
−	|string encoded as UTF32 with 4-byte null terminator	+
−	|-	+
−	|z4	+
−	|string encoded as UTF32 big endian with 4-byte null terminator	+
−	|-	+
−	|z0	+
−	|ASCII string without a null terminator	+
−	|-	+
−	|z1	+
−	|ASCII string with 1-byte terminator	+
−	|-	+
−	|$8	+
−	|string encoded as UTF8	+
−	|-	+
−	|$6	+
−	|string encoded as UTF16	+
−	|-	+
−	|$7	+
−	|string encoded as UTF7	+
−	|-	+
−	|$b	+
−	|string encoded as BigEndianUnicode	+
−	|-	+
−	|$3	+
−	|string encoded as UTF32	+
−	|-	+
−	|$4	+
−	|string encoded as UTF-32 big endian encoding	+
−	|-	+
−	|x	+
−	|null byte	+
−	|}	+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
−		+
		+	Unpacks from a binary array into a normal array according to the given format.
		+	The unpacked data is stored in an associative array.
		+	To accomplish this you have to name the different format codes and separate them by a slash /. If a repeater argument is present, then each of the array keys will have a sequence number behind the given name.
		+	==== format ====
		+	See [[Core Function Pack|Pack( )]] for an explanation of the format codes.
		+	==== data/binary-array ====
		+	An binary array of bytes such as one produced by the Pack function.
		+	OR
		+	A variable that will be converted to a binary array.
		+	If you provide a string to this parameter it will be converted to bytes using either ASCII or UNICODE depending on the values the strings characters contain for example none of the strings characters go higher than 255 you will get pure ASCII bytes of the string (so it will be same length as the string). However if some of the strings characters have a numeric code higher than 255 they will be considered Unicode and you will get more than one byte for each character that goes over the 255 limit, Which could be a big problem as the bytes you will get will not be the same size you was expecting.
		+	You can read/write binary data to/from strings as often as you like and it will not make the string become Unicode it will act as pure ASCII the only time that will ever change is if you explicitly write a character value over 255 to one of the strings characters.
		+	To force a string to be ASCII you could use [[Core Function BinaryFromStr|BinaryFromStr( )]].
		+	==== flag ====
		+	Optional; Control what is returned options are:
		+	0 = Return an associative array containing unpacked elements of binary array
		+	1 = Return a string (Regardless of how many items are to be returned it will just append them)
		+	2 = Force return of single item as is (string, int, float etc) regardless if (key) etc was used
		+	3 = Return an associative array (same as 0) UNLESS there is only one item in the array and the key is numeric (not named) then it will return just that single item only (and not return an array)
		+	Default: 0
		+	=== Return Value ===
		+	Success: Depends on flag see table below
		+	<pre>
		+	Flag 0 = Return an associative array containing unpacked elements of binary array
		+	Flag 1 = Returns a string containing all the elements of the array joined together with no separator
		+	Flag 2 = Return the first element of the array (if one exists otherwise return null)
		+	</pre>
		+	Failure: Returns null
		+	=== Remarks ===
		+	Be aware that if you do not name an element, it will use an index like 0 1 2 3 4. If you do not name more than one element, Unlike PHP Sputnik will insert the items into the array similar to Push() so you will get element 0 1 2 3 4 etc rather than everything replacing the element at index 1.
		+	Also PHP users must note Sputnik returns an array starting at index 0 where as PHP starts at index 1 this may be a cause for confusion.
	=== Example ===		=== Example ===
−	Convert a string into a binary array and back again:	+	Go see [[Core Function Pack|Pack( )]] for examples.
−		+
−	<syntaxhighlight lang="sputnik">	+
−	$arr = Pack("z0", "Hello World!")	+
−	For $i In $arr	+
−	println($i)	+
−	Next	+
−	$str = Unpack("z0", $arr)	+
−	println($str)	+
−	</syntaxhighlight>	+
−		+
−	Convert a dobule into a binary array and back again:	+
−	<syntaxhighlight lang="sputnik">	+
−	$arr = Pack("d", 777.42)	+
−	For $i In $arr	+
−	println($i)	+
−	Next	+
−	$str = Unpack("d", $arr)	+
−	println($str)	+
−	</syntaxhighlight>	+
−		+
−	Convert a int into a binary array and back again:	+
−	<syntaxhighlight lang="sputnik">	+
−	$arr = Pack("d", (int)777)	+
−	For $i In $arr	+
−	println($i)	+
−	Next	+
−	$str = Unpack("d", $arr)	+
−	println($str)	+
−	</syntaxhighlight>	+
−		+
−	Convert a string into a hex and back again:	+
−	<syntaxhighlight lang="sputnik">	+
−	$hex = Join(Unpack("*H", Pack("z0", "Hello World!")), '')	+
−	println("Hex String: " . $hex)	+
−	$str = Unpack("z0", Pack("h", $hex))	+
−	println("Normal String: " . $str)	+
−	</syntaxhighlight>	+
−		+
−	To pack two integers in big endian format, you would use this:	+
−	<syntaxhighlight lang="sputnik">	+
−	$bytes = Pack ("^ii", 1234, 4542);	+
−	</syntaxhighlight>	+
−		+
−	More Examples:	+
−	<syntaxhighlight lang="sputnik">	+
−	; The following means:	+
−	; Little endian encoding of a Int16, followed by an aligned	+
−	; int32 value.	+
−	$r = Pack("_s!i", 0x7b, 0x12345678);	+
−	For $i In $r	+
−	print(Hex($i) . " ")	+
−	Next	+
−	; Prints 7B 0 0 0 80 56 34 12	+
−		+
−	$bytes = Pack("CCCC", 65, 66, 67, 68)	+
−	println($bytes) ; Prints 4-byte sequence for "ABCD"	+
−		+
−	$bytes = Pack("4C", 65, 66, 67, 68)	+
−	println($bytes) ; Prints 4-byte sequence for "ABCD"	+
−		+
−	$bytes = Pack("*C", 65, 66, 67, 68)	+
−	println($bytes) ; Prints 4-byte sequence for "ABCD"	+
−		+
−	$bytes = Pack("^ii", 0x1234abcd, 0x7fadb007)	+
−	For $i In $bytes	+
−	print(Hex($i) . " ")	+
−	Next	+
−	println("") ; Result: 12 34 ab cd 7f ad b0 07	+
−		+
−	; Encode 3 integers as big-endian, but only provides two as arguments,	+
−	; this defaults to zero for the last value.	+
−	$bytes = Pack("^iii", 0x1234abcd, 0x7fadb007)	+
−	For $i In $bytes	+
−	print(Hex($i) . " ")	+
−	Next	+
−	println("") ; Result: 12 34 ab cd 7f ad b0 07 00 00 00 00	+
−		+
−	; Encode as little endian, pack 1 short, align, 1 int	+
−	$bytes = Pack("_s!i", 0x7b, 0x12345678);	+
−	For $i In $bytes	+
−	print(Hex($i) . " ")	+
−	Next	+
−	println("") ; Result: 7b 00 00 00 78 56 34 12	+
−		+
−	; Encode a string in utf-8 with a null terminator	+
−	$bytes = Pack("z8", "hello")	+
−	For $i In $bytes	+
−	print(Hex($i) . " ")	+
−	Next	+
−	println("") ; Result: 68 65 6c 6c 6f 00 00 00 00	+
−		+
−	; Little endian encoding, for Int16, followed by an aligned	+
−	; Int32	+
−	$bytes = Pack("_s!i", 0x7b, 0x12345678)	+
−	For $i In $bytes	+
−	print(Hex($i) . " ")	+
−	Next	+
−	println("") ; Result: 7b 00 00 00 78 56 34 12	+
−	</syntaxhighlight>	+
	[[Category:Core Function]]		[[Category:Core Function]]

---

Latest revision as of 12:38, 14 June 2015

Unpack( <format>, <data/binary-array>, <flag> )

Contents 1 Description 1.1 format 1.2 data/binary-array 1.3 flag 2 Return Value 3 Remarks 4 Example

Description

Unpack data from a binary array

Unpacks from a binary array into a normal array according to the given format.

The unpacked data is stored in an associative array.

To accomplish this you have to name the different format codes and separate them by a slash /. If a repeater argument is present, then each of the array keys will have a sequence number behind the given name.

format

See Pack( ) for an explanation of the format codes.

data/binary-array

An binary array of bytes such as one produced by the Pack function.

OR

A variable that will be converted to a binary array.

If you provide a string to this parameter it will be converted to bytes using either ASCII or UNICODE depending on the values the strings characters contain for example none of the strings characters go higher than 255 you will get pure ASCII bytes of the string (so it will be same length as the string). However if some of the strings characters have a numeric code higher than 255 they will be considered Unicode and you will get more than one byte for each character that goes over the 255 limit, Which could be a big problem as the bytes you will get will not be the same size you was expecting.

You can read/write binary data to/from strings as often as you like and it will not make the string become Unicode it will act as pure ASCII the only time that will ever change is if you explicitly write a character value over 255 to one of the strings characters.

To force a string to be ASCII you could use BinaryFromStr( ).

flag

Optional; Control what is returned options are:

0 = Return an associative array containing unpacked elements of binary array

1 = Return a string (Regardless of how many items are to be returned it will just append them)

2 = Force return of single item as is (string, int, float etc) regardless if (key) etc was used

3 = Return an associative array (same as 0) UNLESS there is only one item in the array and the key is numeric (not named) then it will return just that single item only (and not return an array)

Default: 0

Return Value

Success: Depends on flag see table below

Flag 0 = Return an associative array containing unpacked elements of binary array
Flag 1 = Returns a string containing all the elements of the array joined together with no separator
Flag 2 = Return the first element of the array (if one exists otherwise return null)

Failure: Returns null

Remarks

Be aware that if you do not name an element, it will use an index like 0 1 2 3 4. If you do not name more than one element, Unlike PHP Sputnik will insert the items into the array similar to Push() so you will get element 0 1 2 3 4 etc rather than everything replacing the element at index 1.

Also PHP users must note Sputnik returns an array starting at index 0 where as PHP starts at index 1 this may be a cause for confusion.

Example

Go see Pack( ) for examples.