Core Function Unpack

Revision as of 12:45, 17 November 2011 (view source) UberFoX (Talk | contribs) (→Remarks) ← Older edit		Latest revision as of 12:38, 14 June 2015 (view source) UberFoX (Talk | contribs) m (1 revision)
(15 intermediate revisions by one user not shown)
Line 1:		Line 1:
	<pre>		<pre>
−	Unpack( <expression>, <binary-array/string>, <flag> )	+	Unpack( <format>, <data/binary-array>, <flag> )
	</pre>		</pre>
	=== Description ===		=== Description ===
−	Unpack data from a binary array	+	Unpack data from a binary array
−	==== expression ====	+	Unpacks from a binary array into a normal array according to the given format.
−	The format string to use.	+	The unpacked data is stored in an associative array.
−	==== binary-array/string ====	+	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.
−	An binary array of bytes such as one produced by the Pack function.	+	==== format ====
−	OR	+	See [[Core Function Pack|Pack( )]] for an explanation of the format codes.
−	A string to be converted into a binary array of bytes (z0 ASCII encoding).	+	==== data/binary-array ====
−	==== flag ====	+	An binary array of bytes such as one produced by the Pack function.
−	Optional; Control what is returned options are:	+	OR
−	0 = Return an array	+	A variable that will be converted to a binary array.
−	1 = Return a string	+	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.
−	=== Return Value ===	+	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.
−	Success: Returns the array of data (Even if its only 1 item) unless the flag is set to 1 then it will return a string.	+	To force a string to be ASCII you could use [[Core Function BinaryFromStr|BinaryFromStr( )]].
−	Failure: Returns empty array.	+	==== flag ====
−	=== Remarks ===	+	Optional; Control what is returned options are:
−	Go see [[Core Function Pack|Pack( <expression>, <expressions> )]] for a list of formats and examples.	+	0 = Return an associative array containing unpacked elements of binary array
−	=== Example ===	+	1 = Return a string (Regardless of how many items are to be returned it will just append them)
−	Convert a string into a binary array and back again:	+	2 = Force return of single item as is (string, int, float etc) regardless if (key) etc was used
−	<syntaxhighlight lang="sputnik">	+	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)
−	$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:	+	Default: 0
−	<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:	+	=== Return Value ===
−	<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:	+	Success: Depends on flag see table below
−	<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:	+	<pre>
−	<syntaxhighlight lang="sputnik">	+	Flag 0 = Return an associative array containing unpacked elements of binary array
−	$bytes = Pack ("^ii", 1234, 4542);	+	Flag 1 = Returns a string containing all the elements of the array joined together with no separator
−	</syntaxhighlight>	+	Flag 2 = Return the first element of the array (if one exists otherwise return null)
		+	</pre>
−	More Examples:	+	Failure: Returns null
−	<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)	+	=== Remarks ===
−	println($bytes) ; Prints 4-byte sequence for "ABCD"	+
−	$bytes = Pack("4C", 65, 66, 67, 68)	+	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.
−	println($bytes) ; Prints 4-byte sequence for "ABCD"	+
−	$bytes = Pack("*C", 65, 66, 67, 68)	+	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.
−	println($bytes) ; Prints 4-byte sequence for "ABCD"	+
−	$bytes = Pack("^ii", 0x1234abcd, 0x7fadb007)	+	=== Example ===
−	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	+	Go see [[Core Function Pack|Pack( )]] for examples.
−	$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.