BIT ARRAYS - bit-packed array accessor words for Forth ============================================ Robert Dickow <> Package bit-arrays Version 3.0.0 - 2018-03-06 This is a simple word lexicon for accessing arrays of bits in memory buffers of arbitary length ( length >= CELL (1 addressing unit) ). The fetching words accept two values: the address of the buffer, and a bit-wise offset (index). The storing words expect a bit value of 1 or 0 or TRUE or FALSE value, the address of the buffer, and a bit-wise offset. The buffer size should be at least CELL bytes. ### Top level words: `BIT@` ( addr n-index -- 0|1 ) \ given a buffer addr at offset n-index, returns a value of 1 or 0. `BIT!` ( n addr n-index -- ) \ given a TRUE|FALSE or 1|0 value for n, store the bit into buffer addr at offset n-index `BOOL@` ( addr n-index -- ) \ fetch a TRUE|FALSE value given buffer addr at offset n-index `BOOL!` ( n addr n-index -- ) \ convenience word for BIT!, but accepts a value of TRUE as equally valid as a bit value 1. ### Include file bit_arrays.f ### Dependencies none ### Internal public words: `_BIT@` \ a shared code factoring, probably only useful in the top-level words ### Usage Example (shown for 32 bit address unit Forth) Store a 0 into the 34th bit position in a 64 bit (2 CELLS) long array: \ ************ DECIMAL \ create the buffer: CREATE bitbuffer 2 CELLS ALLOT \ initialize buffer to all on bits: 4294967295 DUP bitbuffer DUP ROT ROT ! CELL+ ! \ store a bit at position 34 0 bitbuffer 34 BIT! \ test it: (DU. is unsigned double print ) bitbuffer 2@ BINARY DU. DECIMAL \ displays: 1111111111111111111111111111111111011111111111111111111111111111 \ ************ ## Tests DECIMAL 2VARIABLE buffer 0 0 buffer 2! \ 64 bits, all 0s T{ -1 buffer 63 BIT! buffer 2@ -> 1 0 }T \ rightmost (64th) bit now 1 T{ 1 buffer 63 BIT! buffer 2@ -> 1 0 }T \ do again. T{ buffer 63 BIT@ -> 1 }T \ read the bit T{ 0 buffer 63 BIT! buffer 2@ -> 0 0 }T \ set the bit back to 0 0 0 buffer 2! \ 64 bits, all 0s T{ -1 buffer 63 BIT! buffer 2@ -> 1 0 }T \ -1 value parameter ok, rightmost (64th) bit now 1 4294967295 buffer 2DUP CELL+ ! ! \ set 64 bits, all 1s T{ FALSE buffer 0 BOOL! buffer 2@ -> -1 2147483647 }T \ leftmost bit off T{ buffer 0 BOOL@ -> FALSE }T \ read the bit. \ ************ ## Changes Simplified code by removing some internal words, inlining. Speed improvements and more memory efficient. Added conditional compilation of NOOP as a do-nothing word if not found in dictionary. ## Bug Reports Please send suggestions, comments, or bug reports Bob Dickow <> ## Compatibility This lexicon is thought to conform to most Forth standards. It was tested on SwiftForth 3.7.1