Core Function Unpack
Unpack( <format>, <data/binary-array>, <flag> )
Contents |
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.
