Summary

###########################################################################

	File:     binary.icn

	Subject:  Procedures to pack and unpack values

	Author:   Robert J. Alexander

	Date:     August 14, 1996

###########################################################################

   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.

###########################################################################

This file is part of the (main) package.

UUDecodeChar(s)

  Get a binary value from a uu-encoded character.

UUDecodeQuad(s)

  Decode 4-byte encoded string to 3-bytes of binary data.

UUDecodeString(s)

 Decode a uu-encoded string.

UUEncodeChar(i)

 Get the ascii character for uu-encoding "i".

UUEncodeString(s)

 Convert "s" to uu-encoded format.

UUEncodeTriple(s)

  Encode to 3-bytes of binary data into 4-byte uu-encoded string.

pack(template, values)

: pack values into a string

pack_big_endian()

pack_bits_high_to_low(v)

 "B"

pack_bits_low_to_high(v)

 "b"

pack_char(v)

 "c" and "C"

pack_double_float(v)

 "d"

pack_extended96_float(v)

 "E"

pack_extended_float(v)

 "e"

pack_hex_digit(s)

pack_hex_high_to_low(v)

 "H"

pack_hex_low_to_high(v)

 "h"

pack_int(v)

 "i" and "I"

pack_int_as_long()

pack_int_as_short()

pack_little_endian()

pack_nlong(v)

 "l" and "L" (big-endian)

pack_nshort(v)

 "s" and "S" (big-endian)

pack_parse_space()

pack_parse_template(template)

pack_single_float(v)

 "f"

pack_uuencoded_string(v)

 "u"

pack_vlong(v)

 "l" and "L" (little-endian)

pack_vshort(v)

 "s" and "S" (little-endian)

pack_x80tox96(s)

pack_x96tox80(s)

unpack(template, binaryString)

: unpack values from string

unpack_bits_high_to_low(n)

 "B"

unpack_bits_low_to_high(n)

 "b"

unpack_char()

 "c"

unpack_double_float()

 "d"

unpack_extended96_float()

 "E"

unpack_extended_float(s)

 "e"

unpack_hex_digit(i)

unpack_hex_high_to_low(n)

 "H"

unpack_hex_low_to_high(n)

 "h"

unpack_int()

 "i"

unpack_nlong()

 "N" and "l" (ell) (big-endian)

unpack_nshort()

 "n" and "s" (big-endian)

unpack_single_float()

 "f"

unpack_unsigned_char()

 "C"

unpack_unsigned_int()

 "I" (aye)

unpack_unsigned_nlong()

 "L" (big-endian)

unpack_unsigned_nshort()

 "S" (big-endian)

unpack_unsigned_vlong()

 "L" (little-endian)

unpack_unsigned_vshort()

 "S" (little-endian)

unpack_uuencoded_string()

 "u"

unpack_vlong()

 "V" and "l" (ell) (little-endian)

unpack_vshort()

 "v" and "s" (little-endian)

pack_template_rec(conversion, count)