BinaryIO: pure PostScript procedures to read/write integers, reals, arrays

Prior to version 0.1 8, BinaryIO could fail in interpreters where the token operator does arbitrary read-ahead. If you have downloaded an earlier version, please replace it.

BinaryIO is a small resource providing procedures for reading and writing 8, 16, and 32 bit integers and 32 bit IEEE reals in big- or little-endian order, and for reading arrays of those types. Procedures to convert between a real and its 32 bit IEEE representation in an int are also provided.

BinaryIO: reference

BinaryIO is a ProcSet resource. To make it available to your own code, include in the setup section of your file:

/net.anastigmatix.BinaryIO /ProcSet findresource

The findresource will succeed, leaving a dictionary on the operand stack, if you have made the BinaryIO resource file [download] available in any of these ways:

• You have included the resource file in the prolog of your own file, before the findresource (which belongs in the setup section)
• You downloaded the resource file to your printer's persistent memory, since it was last powered on
• You saved the resource file in your printer's (if it has a disk or flash filesystem), or ghostscript's, resource directory under the right name
• You use document manager software that recognizes the %%DocumentNeededResources and %%IncludeResource DSC comments, you include these comments at the right position in your file to specify that it needs net.anastigmatix.Order, your document manager software is configured to automatically insert needed resources in files being printed, and you have put the resource files where your document manager can find them.

BinaryIO relies on a few other resources, and you will need those files also. If you use the first method, directly including resources in your file's prolog, the prolog has to contain all of the needed resources, in any order so long as no resource comes before one it depends on, and categories come before resources that belong in them. Any of the other methods should just work as long as all the files are where they need to be. These are the resources you will need:

The resource files are in a compact form. That is for efficiency, not to keep you from viewing them; there is a script for that on the resource packaging page.

The BinaryIO dictionary may be placed on the lookup stack (with begin) for convenient access to the definitions in it, without the bother of get and exec. The dictionary is read-only, so before creating any definitions, you will want either userdict begin or your own dict begin so that you have a writable dictionary on top of the dictionary stack.

BinaryIO dictionary contents

This section describes the contents of the read-only dictionary that is returned by /net.anastigmatix.BinaryIO /ProcSet findresource. The procedures that read always assume the required number of bytes can be read, and will signal syntaxerror if not. (The exact contents of the operand stack when syntaxerror is signalled may change as the implementation evolves; see the implementation note).

intbitstoreal

int intbitstoreal real

Converts the 32 bits contained in int, which must be in the form of a 32-bit IEEE 754 real, to a typed real. It is not necessarily possible to create an infinity or NaN with this procedure; those bit patterns in int may cause an error to be signalled.

read_int8

file read_int8 int

Reads and returns an 8 bit signed integer.

read_uint8

file read_uint8 int

Reads and returns an 8 bit unsigned integer. This is just like read except no boolean result is returned and syntaxerror is signalled if a byte cannot be read.

readbe_IEEE32

file readbe_IEEE32 real

Reads and returns a 32 bit IEEE real stored highest byte first.

readbe_int16

file readbe_int16 int

Reads and returns a 16 bit signed integer stored highest byte first.

readbe_int32

file readbe_int32 int

Reads and returns a 32 bit signed integer stored highest byte first.

readbe_uint16

file readbe_uint16 int

Reads and returns a 16 bit unsigned integer stored highest byte first.

readle_IEEE32

file readle_IEEE32 real

Reads and returns a 32 bit IEEE real stored lowest byte first.

readle_int16

file readle_int16 int

Reads and returns a 16 bit signed integer stored lowest byte first.

readle_int32

file readle_int32 int

Reads and returns a 32 bit signed integer stored lowest byte first.

readle_uint16

file readle_uint16 int

Reads and returns a 16 bit unsigned integer stored lowest byte first.

readn

file string readn string

Fills string from file, signalling syntaxerror rather than returning a substring if too few bytes are read to fill the string.

readnbe_IEEE32

file n readnbe_IEEE32 array

Reads n consecutive 32 bit IEEE 754 reals stored highest byte first, and returns them in an array.

readnbe_int16

file n readnbe_int16 array

Reads n consecutive 16 bit signed integers stored highest byte first, and returns them in an array.

readnbe_int32

file n readnbe_int32 array

Reads n consecutive 32 bit signed integers stored highest byte first, and returns them in an array.

readnbe_uint16

file n readnbe_uint16 array

Reads n consecutive 16 bit unsigned integers stored highest byte first, and returns them in an array.

readnle_IEEE32

file n readnle_IEEE32 array

Reads n consecutive 32 bit IEEE 754 reals stored lowest byte first, and returns them in an array.

readnle_int16

file n readnle_int16 array

Reads n consecutive 16 bit signed integers stored lowest byte first, and returns them in an array.

readnle_int32

file n readnle_int32 array

Reads n consecutive 32 bit signed integers stored lowest byte first, and returns them in an array.

readnle_uint16

file n readnle_uint16 array

Reads n consecutive 16 bit unsigned integers stored lowest byte first, and returns them in an array.

realtointbits

real realtointbits int

Returns in int the IEEE 754 32-bit representation of real (whether or not the interpreter actually uses IEEE 754 as the internal form of real).

write_int8

file int write_int8 –

Writes a (signed or unsigned) 8 bit int onto file.

writebe_IEEE32

file real writebe_IEEE32 –

Writes real onto file as an IEEE 754 32-bit real, highest byte first.

writebe_int16

file int writebe_int16 –

Writes a (signed or unsigned) 16 bit int onto file, highest byte first.

writebe_int32

file int writebe_int32 –

Writes a 32 bit int onto file, highest byte first.

writele_IEEE32

file real writele_IEEE32 –

Writes real onto file as an IEEE 754 32-bit real, lowest byte first.

writele_int16

file int writele_int16 –

Writes a (signed or unsigned) 16 bit int onto file lowest byte first.

writele_int32

file int writele_int32 –

Writes a 32 bit int onto file, lowest byte first.

Implementation note

The aim of the implementation is to balance tolerable performance with small code size so that it is an easy decision to include the resource where it might be useful. I am not sure that the current approach is as good on either metric as I had intended, and I may try radically different approaches as time permits to see about improving it. To make any implementation changes as transparent as possible, the same API will be preserved, but there may be changes in the exact contents of the operand stack when syntaxerror is signalled.

$Id: BinaryIO.html,v 1.4 2006/10/15 19:34:35 chap Exp $