procedure pack: pack values into a string procedure unpack: unpack values from string
link binary
August 14, 1996; Robert J. Alexander
This file is in the public domain.
This is a collection of procedures that support conversion of Icon
data elements to and from binary data formats. The purpose is to
facilitate dealing with binary data files.
The procedures can be used individually or via the "control"
procedures pack() and unpack().
____________________________________________________________
The individual conversion functions are prefixed by either "pack_" or
"unpack_" and are identified in comments by their format character(s).
The "pack_" procedures convert from Icon to binary and take a single
argument: the value to be converted. The "unpack_" procedures
convert from binary to Icon and usually take no parameters -- they are
executed within a string-scanning context and scan the necessary
amount from the &subject string. Some of the "unpack_" functions take
a parameter that specifies the length of the output string. The
individual conversion procedures are minimally commented, but their
action is apparent from their procedure names and the documentation
of the pack() and unpack() procedures.
The control procedures pack() and unpack() take a format string that
controls conversions of several values (similar to the "printf" C
library function). pack() and unpack() are patterned after the Perl
(programming language) functions of the same names, and are documented
below.
pack(template,value1,...) : packed_binary_string
------------------------------------------------
This procedure packs the "values" into a binary structure, returning
the string containing the structure. The elements of any lists in the
"value" parameters are processed individually as if they were
"spliced" into the "value" parameter list. The "template" is a
sequence of characters that give the order and type of values, as
follows" (using C language terminology):
a An ascii string, will be null padded (unstripped for unpack()).
A An ascii string, will be space padded (trailing nulls and
spaces will be stripped for unpack()).
b A bit string, low-to-high order.
B A bit string, high-to-low order.
h A hexadecimal string, low-nybble-first.
H A hexadecimal string, high-nybble-first.
c A signed char value.
C An unsigned char value.
s A signed short value.
S An unsigned short value.
i A signed int value.
I An unsigned int value.
l A signed long value.
L An unsigned long value.
n A short in "network" order (big-endian).
N A long in "network" order (big-endian).
v A short in "vax" order (little-endian).
V A long in "vax" order (little-endian).
f A single-precision float in IEEE Motorola format.
d A double-precision float in IEEE Motorola format.
e An extended-precision float in IEEE Motorola format 80-bit.
E An extended-precision float in IEEE Motorola format 96-bit.
x Skip forward a byte (null-fill for pack()).
X Back up a byte.
@ Go to absolute position (null-fill if necessary for pack()).
u A uu-encoded/decoded string.
Each letter may optionally be followed by a number which gives a
count. Together the letter and the count make a field specifier.
Letters and numbers can be separated by white space which will be
ignored. Types A, a, B, b, H, and h consume one value from the
"value" list and produce a string of the length given as the
field-specifier-count. The other types consume
"field-specifier-count" values from the "value" list and append the
appropriate data to the packed string.
unpack(template,string) : value_list
------------------------------------
This procedure does the reverse of pack(): it takes a string
representing a structure and expands it out into a list of values.
The template has mostly the same format as for pack() -- see pack(),
above.
Endianicity of integers
-----------------------
Integer values can be packed and unpacked in either big-endian
(Motorola) or little-endian (Intel) order. The default is big-endian.
Procedures pack_little_endian() and pack_big_endian() set the
mode for future packs and unpacks.
Size of ints
------------
The "i" (signed int) and "I" (unsigned int) types can pack and unpack
either 16-bit or 32-bit values. 32-bit is the default. Procedures
pack_int_as_short() and pack_int_as_long() change the mode for
future packs and unpacks.