## bis - Bit Input Stream Module

### Module Description

The bis module implements words for reading bits and bytes from a stream of bytes. The module uses a cell wide internal buffer to make it possible to keep reading from succeeding input streams. The maximum number of bits that can be read per call, is limited to the size of a cell minus one byte. So if a cell is 4 bytes wide, this maximum is 24 bit. Keep in mind that the module does not copy the data for the stream, it only stores a reference to the data.

### Module Words

#### bis structure

bis% ( -- n )
  Get the required space for a bis variable

#### Bit input stream variable creation, initialisation and destruction

bis-init ( bis -- )
  Initialise the bit input stream variable
bis-create ( "<spaces>name" -- ; -- bis )
  Create a named bit input stream variable in the dictionary
bis-new ( -- bis )
  Create a new bit input stream variable on the heap
bis-free ( bis -- )
  Free the bit input stream variable from the heap

#### Input stream words

bis-set ( c-addr u bis -- )
  Set the data string for the input stream
bis-get ( bis -- c-addr u )
  Get the data string from the input stream
bis-reset ( bis -- )
  Reset the input buffer, not the input stream

#### Read byte words

bis-bits>bytes ( bis -- )
  Start reading bytes, dropping the not-byte-aligned bits
bis-read-bytes ( n1 bis -- false | n2 true )
  Try reading n1 bytes via the buffer from the stream, return the read number, n1 <= #bytes/cell

#### Read bits words

bis-bytes>bits ( bis -- )
  Start reading bits from the stream
bis-need-bits ( n bis -- flag )
  Check if there are n bits from the stream available in the buffer
bis-fetch-bits ( u1 bis -- u2 )
  Fetch u1 bits from the buffer and return the value
bis-next-bits ( n bis -- )
  Set n bits processed in the buffer
bis-get-bit ( bis -- false | u true )
  Get a single bit u from the buffer

#### Inspection

bis-dump ( bis -- )
  Dump the bit input stream

### Examples

    include ffl/bis.fs

    \ Create an bit input stream variable bis1 in the dictionary

    bis-create bis1

    \ Give the stream some input data (note: the stream does not make a copy of the data)

    : bis-ab ( -- c-addr u ) s" ab" ;

    bis-ab bis1 bis-set

    \ Try reading 10 bits from the stream

    10 bis1 bis-need-bits [IF]
      .( There are 10 bits available in the buffer. ) cr
    [ELSE]
      .( There are not enough bits availabe in the buffer, refill.) cr
    [THEN]

    \ Read the bits from the stream

    .( The 10 bits from the stream:) 10 bis1 bis-fetch-bits . cr

    \ Indicate the the 10 bits are processed

    10 bis1 bis-next-bits

    \ Try reading another 10 bits from the stream

    10 bis1 bis-need-bits [IF]
      .( There are another 10 bits available in the buffer.) cr
    [ELSE]
      .( There are not enough bits available in the buffer, refill.) cr
    [THEN]

    \ Refill the input stream

    : bis-cd ( -- c-addr u) s" cd" ;

    bis-cd bis1 bis-set

    \ Again try reading another 10 bits from the stream

    10 bis1 bis-need-bits [IF]
      .( There are another 10 bits available in the buffer.) cr
    [ELSE]
      .( There are not enough bits available in the buffer, refill.) cr
    [THEN]

    \ Read the bits from the stream and indicate that the bits are processed

    .( The 10 bits from the stream:) 10 bis1 bis-fetch-bits . cr

    \ Indicate the the 10 bits are processed

    10 bis1 bis-next-bits

generated 03-Jun-2010 by ofcfrth-0.10.0