Summary

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

	File:     bitstrm.icn

	Subject:  Procedures to read and write strings of bits in files

	Author:   Robert J. Alexander

	Date:     August 14, 1996

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

   This file is in the public domain.

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

  Procedures for reading and writing integer values made up of an
  arbitrary number of bits, stored without regard to character
  boundaries.

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

  Usage of BitStreamWrite, by example:

       record bit_value(value, nbits)
       ...
       BitStreamWrite()                        #initialize
       while value := get_new_value() do       # loop to output values
               BitStreamWrite(outfile, value.nbits, value.value)
       BitStreamWrite(outfile)                 # output any buffered bits

  Note the interesting effect that BitStreamWrite(outproc), as well as
  outputting the complete string, pads the output to an even character
  boundary.  This can be dune during construction of a bit string if
  the effect is desired.

  The "value" argument defaults to zero.

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

  Usage of BitStreamRead, by example:

       BitStreamRead()
       while value := BitStreamRead(infile, nbits) do
               # do something with value

  BitStringRead fails when too few bits remain to satisfy a request.

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

  See also: bitstr.icn

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

This file is part of the (main) package.

BitStreamRead(infile, bits, inproc)

BitStreamWrite(outfile, bits, value, outproc)