Unpack

(Engine-Level Function)

Description:	Unpacks a set of values from a stream into a single dimensional array or a set of variables referenced by object parameters, and returns the number of items unpacked.
Returns:	Numeric
Usage:	Script Only.
Function Groups:	Array,  Stream and Socket
Related to:	Pack
Format:	Unpack(Data, Start, End, Stream[, TruncateAt, DataLength, MirrorKey])
Parameters:

Data

Required. An object value or an array containing the data or the object value of the module whose parameters address variables into which to store the data. For example, if you have 5 numeric values to unpack, you would allocate a 1-dimensional array, 5 elements in length. You would pass this array to Unpack's Data parameter, and specify that you wish to unpack from subscript 1 to 5. Refer to the example section for more information.

Start

Required. The starting array index (zero-based), or parameter number (one-based) of the data to unpack.

End

Required. The last array index, or parameter number of the data to unpack.

Stream

Required. A variable holding the stream that contains the data to be unpacked. The stream must have been generated with the Pack function.

TruncateAt

An optional parameter. If present specifies that all text values and stream values unpacked from the stream will be truncated after the number of bytes specified in this parameter.

DataLength

An optional parameter. If present, specifies an array into which will be stored the length of each text and stream value unpacked from the source stream. Each length is stored at the array index corresponding to the index of the value itself. For example, if the value that would go in the destination array at index 5 were a text value, its length would be stored at index 5 in the array addressed by this parameter. Unpacked values of numeric type have Invalid stored in their entry in this array.

MirrorKey

Optional. A dictionary mapping integers to structure names. Must be used if the data was packed using a KeyDictionary.   There is no requirement for the Pack KeyDictionary parameter and the Unpack MirrorKey parameter to have the same number of elements. All that is required is that the Unpack MirrorKey dictionary has all of the structures that are in that particular packed stream. If the KeyDictionary doesn’t have the structure that was packed, the returned data is a simple array rather than a structure.

Comments:

This function returns the number of values unpacked. If the Data parameter is an array, the data from the stream will be unpacked into that array. If the Data parameter is an object value, the parameters of that object must contain pointers to variables into which the data from the stream will be unpacked. If the Pack function used the optional parameter, Key, to pack a record into a smaller stream, then Unpack must be able to provide a mirrored version of that dictionary to access the data in the structure.

Example:

If you wish to pack 2 3-dimensional arrays, you would allocate a 1-dimensional array, 2 elements in length. You would then assign the 3-dimensional arrays to the 1-dimensional array elements, and then Pack the 1-dimensional array.

For example:

Array1D = New(2);
Array1D[0] = Array3D_1;
Array1D[1] = Array3D_2;
Pack(Array1D, 0, 1, &Stream);

Unpacking this is almost an identical operation:

Array1D = New(2);
UnPack(Array1D, 0, 1, Stream);
Array3D_1 = Array1D[0];
Array3D_2 = Array1D[1];

All you need to know is how many things you wish to pack and unpack, not the sizes or types of the things (a ValueType(Array1D[0]) will tell you the type). As the stream position is moved after each pack or unpack, you can simply unpack one item at a time and check the return value of UnPack.

Example 2:

In this example, the presence of a Key parameter allows the example to be packed into a stream that is less than half the size that would be obtained without the Key parameter. (Exact number depending on the names used in the structure definitions.)

"Record", "Values", and "AA_Info" are all STRUCTs.

Rec = Record( GetGUID(1)             { GUID       },
              1                      { Priority   },
              Values(87, 54, "feet") { Values     },
              System.MakeDictionary("AA", 
                             AA_Info("AAData1", 2)) { Extensions });

{ Omitted: Place record in ArrayToPack }

Key = System.MakeDictionary("Record", 0,
                             "Values", 1,
                             "AA_Info", "AA")

Pack(ArrayToPack, 0, 0, &PackStream, Key);

{ Omitted: Rewind stream }

MirrorKey = System.MakeDictionary("0", Record,
                                   "1", Values,
                                   "AA", AA_Info));

UnPack(UnpackedArray, 0, 0, PackStream, Invalid, Invalid, MirrorKey);