Provided by: libvistaio-dev_1.2.16-1_amd64 bug

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>