@bitarray/typedarray

A bit array object exhibiting the interface of standard ecmascript TypedArray's.

Tip

If you are looking for easily applying bitwise operations, check out @bitarray/es6, which builds on top of the present library. Here, we purposely stick to methods and properties described by the ecmascript specification (there are no bitwise operations on arrays specified by ecmascript).

Rationale

The ecmascript specification has introduced TypedArrays for Int8, Uint8, Uint8Clamped, Int16, Uint16, Int32, Uint32, Float32, Float64, BigInt64 and BigUint64 types.

This library adds support for the Bit type. It provides a very memory-efficient means to store sequences of bits, while exposing the familiar, standard interface of typed arrays.

Compatibility

The library uses a Proxy object, which is an ES6 (aka ES2015) feature. It can NOT be polyfilled (to the extent it is used by the library).

Note: standard TypedArray is also a feature of ecmascript ES6.

Installation

npm install @bitarray/typedarray

or

yarn add @bitarray/typedarray

Usage

Usage is same as for any standard typed array. You may check the MDN documentation for details.

Instantiating

importBitArrayfrom"@bitarray/typedarray"constlength=32;// or whatever length valueconstbits=newBitArray(length);// Bit arrays can be created from iterables.// The following are all equivalentnewBitArray("11001010");newBitArray([1,1,0,0,1,0,1,0]);newBitArray([true,true,false,false,true,false,true,false]);BitArray.from("11001010");BitArray.from([1,1,0,0,1,0,1,0]);BitArray.from([true,true,false,false,true,false,true,false]);BitArray.of(..."11001010");BitArray.of(1,1,0,0,1,0,1,0);BitArray.of(true,true,false,false,true,false,true,false);

Reading/writing values

bits[1];// 0 by defaultbits[1]=1;bits[1];// 1bits.at(1);// 1// can also take boolean values// (will be coerced to bit)bits[1]=false;bits.at(1);// 0

Iterating

for(leti=0;i<bits.length;i++)// do something with bits[i]bits.forEach((val,i,arr)=>{/* do something */});for(letiinbits)// do something with bits[i]for(letbitofbits)// do something with bit

Indexes & values

// indexes - following two are the sameObject.keys(bits);// [0, 1, 2, ...]Object.getOwnPropertyNames(bits);// valuesObject.values(bits);// [0, 1, 0, 0, 0, ...]// entriesObject.entries(bits);// [["0", 0], ["1", 1], ["2", 0], ["3", 0], ...]

Instance properties

// propertiesbits.buffer;bits.byteLength;bits.byteOffset;bits.length;

static properties

BitArray.BYTES_PER_ELEMENT;// 0.125 == 1/8, read-onlyBitArray.name;// "BitArray", read-onlyBitArray.prototype;// Object {...}

Implementation notes

For the most part, mapping the behaviour of standard methods and properties to the case of bit arrays is obvious. There are a few caveats though.

Note: not all features of the specification are implemented yet [WIP; PRs welcome!].

Setting values

In standard typed arrays, except for the Uint8clamped type, values exceeding the limits go round. For instance, setting value 257 to a Uint8 results in the value of 1 (== 257 % 0xFF). Also, non-numerical values become 0.

With BitArray, values are first coerced to number. If the result is truthy, the bit will be set to 1; 0 otherwise.

letarr=newBitArray(2);// one would normally set values like thisarr[0]=0;arr[1]=1;// or using booleans:arr[0]=false;arr[1]=true;// this will also workarr[0]=-.000001;// arr[0] === 1, because Boolean(-.000001) === truearr[1]="a";// arr[1] === 0, because Number("a") === NaN, which is falsy

.toString() method

The standard method returns a comma-separated list of numbers. In the case of bit sequences, interleaving commas is unnecessarily heavy, for no benefit. Instead, we list 0|1 bits in sequence, grouping them by eight for better clarity (human-reading), and separating groups by a space rather than a comma, to match common practice of text representation of bit sequences.

newBitArray(20).toString();// "00000000 00000000 0000"

License