Summary

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

	File:     bitstr.icn

	Subject:  Procedures for bits in Icon strings

	Author:   Robert J. Alexander

	Date:     August 14, 1996

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

   This file is in the public domain.

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

  Procedures for working with strings made up of numeric values
  represented by strings of an arbitrary number of bits, stored without
  regard to character boundaries.

  In conjunction with the "large integers" feature of Icon, this
  facility can deal with bitstring segments of arbitrary size.  If
  "large integers" are not supported, bitstring segments (i.e.  the
  nbits parameter of BitStringGet and BitStringPut) wider that the
  integer size of the platform are likely to produce incorrect results.

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

  Usage of BitStringPut, by example:

       record bit_value(value, nbits)
       ...
       bitString := BitString("")
       while value := get_new_value() do       # loop to append to string
               BitStringPut(bitString, value.nbits, value.value)
       resultString := BitStringPut(bitString) # output any buffered bits

  Note the interesting effect that BitStringPut(bitString), as well as
  producing the complete string, pads the buffered string 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 BitStringGet, by example:

       record bit_value(value, nbits)
       ...
       bitString := BitString(string_of_bits)
       while value := BitStringGet(bitString, nbits) do
               # do something with value

  BitStringGet fails when too few bits remain to satisfy a request.
  However, if bits remain in the string, subsequent calls with fewer
  bits requested may succeed.  A negative "nbits" value gets the value
  of the entire remainder of the string, to the byte boundary at its
  end.

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

  See also: bitstrm.icn

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

This file is part of the (main) package.

BitStringGet(bitString, nbits)

BitStringPut(bitString, nbits, value)

BitString(s, buffer, bufferBits)