thi.ng/bitstream
Overview
ES6 iterator based, seekable read/write bit streams. Written in TypeScript, distributed in ES6.
Installation
npm i thing-bitstream
API
let bits = ;
BitOutputStream
Uint8Array
backed, bitwise output stream abstraction (big endian order).
Individual word sizes can range between 1-52 bits (in practice) and are not
fixed (each word can have a different size).
The constructor accepts an optional initial Uint8Array
buffer or buffer size
(in bytes) and an optional write start position (in bits). The buffer will
only be written to starting from the given bit position (even if in the middle
of a byte). Default buffer size is 16 bytes, but the array is resized (x2)
automatically each time capacity is reached.
Note: The max. word size of 52 bits is not enforced by the library, but JS
can only represent integers (w/o loss of precision) up to 2^53-1
. If you're
willing to accept lossy precision for larger values, technically the max.
supported word width is 64 bits.
out = ;// write 3-bit number (only the lowest 3 bits are used, here 0x05)out;// write 7-bit numberout;// write 32-bit numberout; // write values from given iterable (w/ fixed word size, here 16 bits)out; // get bytes (only up to current write position)out// Uint8Array [ 185, 183, 178, 190, 235, 106, 170, 149, 85, 64 ]
In addition to the generic write()
method, there's also the slightly faster
writeBit()
for writing single bits (the arg MUST be 0
or 1
only).
Using seek(pos)
, the write position can be repositioned within current limits
(does not attempt to resize backing buffer).
BitInputStream
Uint8Array
backed bitwise input stream abstraction (big endian order) with
optional start position and read limit (both in bits). All readers are
independent instances, but if obtained from BitOutputStream
will share the
same backing buffer as the writer. An auto-configured input stream can be
obtained via output.reader()
. The class too implements the ES6 Iterator API
for bitwise read access (see below), as well as a
read()
method to read bitfields.
Note: Attempting to read beyond capacity will throw an EOF error.
Using input.seek(pos)
, the read position can be repositioned within stream
limits.
// get input from output stream...// (for reference, the ^ indicate the start of each bit field)...out// "10111001101101111011001010111110111010110110101010101010100101010101010101"// ^ ^ ^ ^ ^ // obtain new readerinput = out;// sqeuentially read bit fields of varying sizesout// [ "5", "66", "decafbad", "aaaa", "5555" ] // or read fields into objectout;// { a: 5, b: 102, c: 3737844653, d: 43690, e: 21845 } // or read a number of fixed size words (here also from given pos)out;// [ 'deca', 'fbad', 'aaaa', '5555' ] src = 0xf10xe20xd30xc40xb50xa60x970x88;// create stream from bit 36input = src 36;input;// 5a6input// 9input// 7input // or use input.readBit()// 1 => msb of last byte (0x88)input// 8 => low nibble of last byte
In addition to the generic read()
method, there's also the slightly faster
readBit()
for reading single bits.
Building
Build requirements
Building & testing this project requires Typescript 2.1+ and Mocha globally installed:
npm i typescript mocha -g
cd thing-bitstream
npm up
npm run build
Testing
npm link mocha
npm run test
Authors
- Karsten Schmidt
License
Apache Software License 2.0