Provided by: libvistaio-dev_1.2.19-1_amd64 
NAME
VistaIOPackData, VistaIOUnpackData - pack or unpack a vector of values
SYNOPSIS
typedef enum { VistaIOLsbFirst, VistaIOMsbFirst } VistaIOPackOrder;
void VistaIOPackData (repn, nels, unpacked, order, plength, ppacked, palloced)
VistaIORepnKind repn;
size_t nels, *plength;
VistaIOPointer unpacked, *ppacked;
VistaIOPackOrder order;
VistaIOBoolean *palloced;
void VistaIOUnpackData (repn, nels, packed, order, plength, punpacked, palloced)
VistaIORepnKind repn;
size_t nels, *plength;
VistaIOPointer packed, *punpacked;
VistaIOPackOrder order;
VistaIOBoolean *palloced;
ARGUMENTS
repn Specifies the representation of the values to be packed or unpacked.
nels Specifies the number of values to be packed or unpacked.
unpacked Specifies the location of the values to be packed.
packed Specifies the location of the values to be unpacked.
order Specifies the order in which values smaller than a byte are packed into a single
byte, or values larger than a byte are split among multiple bytes.
plength Specifies and returns the length of the (un)packed data, in bytes. The length is
rounded up to the next whole byte.
ppacked Specifies or returns the location of the packed data.
punpacked Specifies or returns the location of the unpacked data.
palloced If NULL, specifies that a buffer is being supplied to contain the results of
(un)packing. Otherwise, returns TRUE if memory was allocated by the routine to
contain the results, and FALSE otherwise.
DESCRIPTION
VistaIOPackData packs a vector of values into a block of contiguous bytes. Typically, it
is used when preparing to output a series of values to a Vista data file.
VistaIOUnpackData performs the inverse, unpacking a vector of values from a block of
contiguous bytes. It is used when decoding a series of values read from a Vista data file.
Unpacked values reside in memory in a form dependent upon machine architecture. Packed
values, on the other hand, are represented in a machine-independent manner using the
fewest bits possible. If the values are of type VistaIOBit, for example, they might occupy
one byte each in unpacked form, but in packed form each occupies a single bit. The types
of values that can be (un)packed, and their form when packed, is as follows:
VistaIOBit is packed as a single bit.
VistaIOUByte
is packed as an unsigned integer in a single 8-bit byte.
VistaIOSByte
is packed as a two's-complement integer in a single 8-bit byte.
VistaIOShort
is packed as a two's-complement integer in two 8-bit bytes.
VistaIOLong is packed as a two's-complement integer in four 8-bit bytes.
VistaIOFloat
is packed as an IEEE-format floating-point number in four 8-bit bytes.
VistaIODouble
is packed as an IEEE-format floating-point number in eight 8-bit bytes.
VistaIOBoolean
is packed as a single bit.
The values to be (un)packed must all have one of these types, as specified by the repn
argument.
The order argument specifies the order with which bits are packed into a byte, or multi-
byte, packed values are separated into bytes. If the packed values each require a single
bit, order specifies whether successive values are to be packed into a byte from least-
significant bit to most significant (VistaIOLsbFirst), or vice versa (VistaIOMsbFirst). If
the packed values each require multiple bytes, order specifies whether those bytes are to
be packed from least-significant byte to most significant (VistaIOLsbFirst), or vice versa
(VistaIOMsbFirst). Data in Vista data files is packed with order = VistaIOMsbFirst.
For a call to VistaIOPackData, nels specifies the number of values to be packed and
unpacked points to a vector containing them. You can specify where to place the packed
values in either of two ways:
• You can supply your own buffer for the packed values by passing NULL in palloced,
passing a pointer to the address of your buffer in ppacked, and passing a pointer to
the length of your buffer in plength. On return, the actual length of the packed
values will have been stored at *plength.
• You can let VistaIOPackData determine the location of the packed values by passing in
palloced a pointer to a VistaIOBoolean variable. VistaIOPackData then returns, via
ppacked and plength, the location and length of the packed data. Depending on the type
of values to be packed, their arrangement in memory, and order, actual packing may or
may not be needed. That is, the packed and unpacked forms of the value may actually be
identical. In this case, the returned location and length refer to the unpacked data,
and palloced returns FALSE to indicate that no separate buffer for the packed data was
allocated. If, however, the packed form differs from the unpacked form,
VistaIOPackData will allocate memory for the packed data. The location and length of
this memory are returned instead, and palloced returns TRUE to indicate that this
memory should be freed when the packed values are no longer needed.
VistaIOUnpackData is called in an analogous manner. The nels argument specifies the number
of values to be unpacked and packed points to a vector containing them. As for
VistaIOPackData, you can specify where to place the unpacked values in either of two ways
indicated by palloced.
RETURN VALUES
Both routines return TRUE if successful, and FALSE otherwise. In addition, they may set
*plength, *ppacked, *punpacked, and *palloced as described above.
EXAMPLES
Here we pack a vector of bits, write the packed bits to a file, and free any storage used
to represent the packed bits:
size_t nbits, length;
VistaIOBit *bits;
VistaIOPointer packed;
VistaIOBoolean alloced;
FILE *file;
...
VistaIOPackData (VistaIOBitRepn, nbits, bits, VistaIOMsbFirst, & length, & packed, & alloced);
fwrite ((char *) packed, 1, length, file);
if (alloced)
VistaIOFree (packed);
NOTES
Packing or unpacking can be done in place. For example, in a call to VistaIOPackData,
unpacked and *ppacked can point to the same storage.
LIMITATIONS
The present implementation cannot pack values of type VistaIOUByte, VistaIOSByte,
VistaIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble if their packed and unpacked
sizes differ.
DIAGNOSTICS
``Byte order not recognized.''
The routines trie to automatically detect whether the present machine stores multi-
byte values from most-to-least significant byte, or vice versa. If this message is
issued it means that a port to a new machine architecture was unsuccessful, in
which case some additional programming is needed to support the new architecture.
``Insufficient space for (un)packed data.''
A buffer was supplied for the results of (un)packing, but the buffer is too small.
``(Un)packing type from mbits to nbits bits is not supported.''
The present implementation cannot (un)pack values of type VistaIOUByte,
VistaIOSByte, VistaIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble if their
packed and unpacked sizes differ. If asked to do so the routine will abort the
program with this message.
AUTHOR
Art Pope <pope@cs.ubc.ca>
Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>