anastigmatix.net

This document has a standard, validated CSS2 stylesheet, which your browser does not seem to display properly. In a browser supporting web standards, this table of contents would be fixed at the side of the page for easy reference.

anastigmatix home
  • Binary PostScript I/O
  • BinaryIO: reference
  • BinaryIO dictionary contents
  • intbitstoreal
  • read_int8
  • read_uint8
  • readbe_IEEE32
  • readbe_int16
  • readbe_int32
  • readbe_uint16
  • readle_IEEE32
  • readle_int16
  • readle_int32
  • readle_uint16
  • readn
  • readnbe_IEEE32
  • readnbe_int16
  • readnbe_int32
  • readnbe_uint16
  • readnle_IEEE32
  • readnle_int16
  • readnle_int32
  • readnle_uint16
  • realtointbits
  • write_int8
  • writebe_IEEE32
  • writebe_int16
  • writebe_int32
  • writele_IEEE32
  • writele_int16
  • writele_int32
  • Implementation note
  • 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:

    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:

    ResourceCategoryDescription
    net.anastigmatix.MetaPre ProcSet Staged-programming extensions for PostScript
    net.anastigmatix.filter Category Category to contain filter resources usable with StreamIO.
    net.anastigmatix.StreamIO ProcSet I/O utilities and pure PostScript definable filters.
    net.anastigmatix.BinaryIO ProcSet The main attraction.

    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.

    Valid XHTML 1.0! Valid CSS! $Id: BinaryIO.html,v 1.4 2006/10/15 19:34:35 chap Exp $