digitalbazaar / bitstring Goto Github PK

View Code? Open in Web Editor NEW

3.0 12.0 4.0 46 KB

A Bitstring module for universal JavaScript

License: BSD 3-Clause "New" or "Revised" License

JavaScript 100.00%

bitstring's Introduction

Bitstring

A Bitstring module for universal JavaScript.

Install

To install get the latest version from NPM:

npm install @digitalbazaar/bitstring

To install locally for development:

git clone https://github.com/digitalbazaar/bitstring.git
cd bitstring
npm install

Usage

import {Bitstring} from '@digitalbazaar/bitstring';

// You can make a new instance by passing in a length
const bitstring = new Bitstring({length: 10});

// OR by passing in a buffer
const buffer = Uint8Array.from([255]);
const bitstring = new Bitstring({buffer});

API

set(position, on)

Sets the value of a bit for the given position to the given boolean.

bitstring.set(1, true);

get(position)

Gets the value of a bit for the given position.

bitstring.get(3);

encodeBits()

Compresses and encodes bits to a base64url encoded string.

await bitstring.encodeBits();

decodeBits({encoded})

Decodes and uncompresses a given base64url encoded string to a Uint8Array.

await Bitstring.decodeBits({encoded});

compressBits()

Compresses bits to a Uint8Array.

await bitstring.compressBits();

uncompressBits({compressed})

Uncompresses compressed bits.

await Bitstring.uncompressBits({compressed});

Contribute

Please follow the existing code style.

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: [email protected]

License

BSD-3-Clause © Digital Bazaar

bitstring's People

Contributors

Stargazers

Watchers

Forkers

yengas digitalcredentials blockchain-certificates techsavvyash

bitstring's Issues

Use native gzip `CompressionStream`/`DecompressionStream` primitives when available

https://caniuse.com/?search=compressionstream

Hey team,
I was trying to use yours vc-status-list package, but when I tried to create a list I got fallowing error TypeError: Bitstring is not a constructor. I create a separate project to check what is exported from @digitalbazaar/bitstring package, I got empty object when it should be a Bitstring class.

Here is my script:

import Bitstring from '@digitalbazaar/bitstring';

console.log(Bitstring);

Expected: [class Bitstring]
Received: {}

I've installed the latest version of package. Tested on Node 16.10.0

Do not use class for assertions

See late comments on #5.

Change `littleEndianBits` option name to `leftToRightIndexing`

Using big / little endian terminology for bits instead of bytes leads to confusion. And, ultimately, all that is used at this layer is indexing / addressing of particular bits, not an interpretation of the meaning of those bits.

The wikipedia definition for endianness for bits can be found here. It implies that "big endian" means the most significant bits are transmitted first -- presumably meaning the "smallest address" or "lowest index" is the left most bit. This means that "little endian" would have the least significant bits transferred first and the most significant bit would be at the right most address.

Its source for this is RFC1700. The "big endian bit order" matches the so-described "big-endian" Internet Binary in the table in that RFC. The "bit transmission order" that IEEE uses in that table is reversed from this and is the implied "little endian order", where the leftmost bit is the least significant bit. This is what is implemented in this module as the default indexing.

However, people have become confused about "big endian" when setting the bit with a bit index of 0, either it means:

The least significant bit (right most) should be set because of the above.
The most significant bit (left most) should be set because the index value is the lowest possible bit index in the byte and "big endian" stores the least significant value at the largest memory address.

But the second interpretation would mean that "littleEndianBits = true" actually means "big endian"! Again, what is implemented in this module is that the left most address is the lowest index into the bitstring (or into any given byte of the bitstring).

Therefore, using leftToRightIndexing is hopefully a better name when referring to bit indexing. When this is set to true, it means that the byte value 0x80 (0b10000000) means the first index is set in a given byte of the bitstring. When indexing bits, left to right uses the indexes 01234567 and right to left uses 76543210 within a byte.

Add an optional endian flag to allow conversion from default big endian to little endian if desired

Add Validation

Add validation using assert-plus on input parameters of bitstring methods.