Module description

bis -- Bit Input Stream Module
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.

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

\ ==============================================================================
\
\           bis_expl - the bit input stream example in the ffl
\
\               Copyright (C) 2008  Dick van Oudheusden
\  
\ This library is free software; you can redistribute it and/or
\ modify it under the terms of the GNU General Public
\ License as published by the Free Software Foundation; either
\ version 2 of the License, or (at your option) any later version.
\
\ This library is distributed in the hope that it will be useful,
\ but WITHOUT ANY WARRANTY; without even the implied warranty of
\ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
\ General Public License for more details.
\
\ You should have received a copy of the GNU General Public
\ License along with this library; if not, write to the Free
\ Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
\
\ ==============================================================================
\ 
\  $Date: 2008-09-07 06:52:17 $ $Revision: 1.1 $
\
\ ==============================================================================

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 by fsdocgen 0.1.0