Summary

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

	File:     outbits.icn

	Subject:  Procedure to write variable-length characters

	Author:   Richard L. Goerwitz

	Date:     November 3, 1991

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

   This file is in the public domain.

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

	Version:  1.5

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

  In any number of instances (e.g. when outputting variable-length
  characters or fixed-length encoded strings), the programmer must
  fit variable and/or non-byte-sized blocks into standard 8-bit
  bytes.  Outbits() performs this task.

  Pass to outbits(i, len) an integer i, and a length parameter (len),
  and outbits will suspend byte-sized chunks of i converted to
  characters (most significant bits first) until there is not enough
  left of i to fill up an 8-bit character.  The remaining portion is
  stored in a buffer until outbits() is called again, at which point
  the buffer is combined with the new i and then output in the same
  manner as before.  The buffer is flushed by calling outbits() with
  a null i argument.  Note that len gives the number of bits there
  are in i (or at least the number of bits you want preserved; those
  that are discarded are the most significant ones). 

  A trivial example of how outbits() might be used:

      outtext := open("some.file.name","w")
      l := [1,2,3,4]
      every writes(outtext, outbits(!l,3))
      writes(outtext, outbits(&null,3))           # flush buffer

  List l may be reconstructed with inbits() (see inbits.icn):

      intext := open("some.file.name")
      l := []
      while put(l, inbits(intext, 3))

  Note that outbits() is a generator, while inbits() is not.

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

  See also: inbits.icn

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

This file is part of the (main) package.

outbits(i, len)