VistaIOPackData(3)

💖 NAME 💖

VistaIOPackData, VistaIOUnpackData — pack or unpack a vector of values

okay bestie so this is VistaIOPackData(3) from the Library Functions Manual and it's literally the duo that squeezes your values into a tight little byte blob and then gets them back out again. two functions, one glow-up. 🫶

---

🎀 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 — says what kind of values we're packing or unpacking. the representation. the vibe check for the data type. ✨
• nels — how many values are getting packed or unpacked. the count, the headcount, the roster.
• unpacked — where the values that are about to be packed are chilling in memory.
• packed — where the values that are about to be unpacked are chilling.
• order — the order in which values smaller than a byte get packed into one byte, or values bigger than a byte get split across several bytes. (byte endianness, basically, but for bits too 💅)
• plength — you give it the length of the (un)packed data in bytes, and it hands the length back to you. the length gets rounded up to the next whole byte. no half-bytes here, we don't do crumbs. 🍓
• ppacked — you give it the location of the packed data, or it gives the location back to you. depends on the mode, iykyk.
• punpacked — same deal but for the unpacked data. give it a location, or get one back.
• palloced — if it's NULL, that means you're supplying the buffer that holds the results of (un)packing. otherwise it returns TRUE if the routine allocated memory for the results, and FALSE if it didn't. no cap. 🧚

---

👑 DESCRIPTION 👑

VistaIOPackData packs a vector of values into a block of contiguous bytes. typically you reach for it when you're getting ready to output a series of values to a Vista data file. VistaIOUnpackData does the inverse — it unpacks a vector of values out of a block of contiguous bytes. that one's for decoding a series of values you read from a Vista data file. 🔥

Unpacked values sit in memory in a form that depends on your machine architecture. packed values though? they're represented in a machine-independent way, using the fewest bits possible. like, if the values are type VistaIOBit, they might take up a whole byte each unpacked, but packed, each one is literally a single bit. the way that compression ate. 💅

here's the full list of what types can be (un)packed, and how they look when packed:

• VistaIOBit — packed as a single bit.
• VistaIOUByte — packed as an unsigned integer in a single 8-bit byte.
• VistaIOSByte — packed as a two's-complement integer in a single 8-bit byte.
• VistaIOShort — packed as a two's-complement integer in two 8-bit bytes.
• VistaIOLong — packed as a two's-complement integer in four 8-bit bytes.
• VistaIOFloat — packed as an IEEE-format floating-point number in four 8-bit bytes.
• VistaIODouble — packed as an IEEE-format floating-point number in eight 8-bit bytes.
• VistaIOBoolean — packed as a single bit.

all the values you're (un)packing have to be one of these types, and you tell it which one through the repn argument. periodt.

The order argument specifies the order bits get packed into a byte, or the order multi-byte packed values get split into bytes. if the packed values each only need a single bit, order says whether successive values go into a byte from least-significant bit to most significant (VistaIOLsbFirst), or the other way around (VistaIOMsbFirst). if the packed values each need multiple bytes, order says whether those bytes go from least-significant byte to most significant (VistaIOLsbFirst), or the other way around (VistaIOMsbFirst). 🦋

Data in Vista data files is packed with order = VistaIOMsbFirst. remember that. it's the house style.

For a call to VistaIOPackData, nels is the number of values to pack and unpacked points at a vector containing them. now, where do the packed values go? you've got two ways to say it:

• You can supply your own buffer for the packed values: pass NULL in palloced, pass a pointer to the address of your buffer in ppacked, and pass 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. very DIY, very demure. 🎀
• You can let VistaIOPackData figure out the location for you: pass in palloced a pointer to a VistaIOBoolean variable. VistaIOPackData then returns, through ppacked and plength, the location and length of the packed data. depending on the type of values, their arrangement in memory, and order, actual packing may or may not even be needed — like, the packed and unpacked forms might literally be identical. in that case the returned location and length refer to the unpacked data, and palloced returns FALSE to say no separate buffer was allocated, bestie, don't worry about it. but if the packed form does differ from the unpacked form, VistaIOPackData will allocate memory for the packed data. the location and length of that memory get returned instead, and palloced returns TRUE to tell you that memory should be freed once you're done with the packed values. 👑

VistaIOUnpackData is called in an analogous way. the nels argument is the number of values to unpack and packed points at a vector containing them. just like with VistaIOPackData, you've got two ways to say where the unpacked values go, and palloced is the thing that tells you which one you're doing. 💜

---

⭐ RETURN VALUES ⭐

Both routines return TRUE if it all worked out, and FALSE otherwise. plus they may set *plength, *ppacked, *punpacked, and *palloced as described up above. icon behavior. ✨

---

🌈 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);

look at her go 😭 she packs, she writes, she cleans up after herself. main character energy fr fr.

---

🫶 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. same address, no copies, no drama. 🔥

---

💀 LIMITATIONS 💀

The present implementation cannot pack values of type VistaIOUByte, VistaIOSByte, VistaIOShort, VistaIOLong, VistaIOFloat, or VistaIODouble if their packed and unpacked sizes differ. yeah. that's just how it is right now. 🙈

---

🙈 DIAGNOSTICS 🙈

• ``Byte order not recognized.'' The routines try to automatically detect whether the present machine stores multi-byte values from most-to-least significant byte, or vice versa. if you see this message it means a port to a new machine architecture was unsuccessful — in which case some additional programming is needed to support that new architecture. not a vibe. 😭
• ``Insufficient space for (un)packed data.'' A buffer was supplied for the results of (un)packing, but the buffer is too small. she's stuffed. she cannot fit. 💀
• ``(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 you ask it to do that anyway, the routine will abort the program with this message. so like... don't. 🚨

---

💅 AUTHOR 💅

Art Pope <pope@cs.ubc.ca>

Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>

---

okay that's the whole page, bestie, you're officially educated 💖 this was VistaIO Version 1.2.14, dated 21 January 1994 (yes she's vintage, vintage is iconic, we love her), and the manual entry is VistaIOPackData(3). go forth and pack responsibly. 🎀✨🦋