An arbitrary size Bit-Vector implementation in JavaScript

Overview

BitSet.js

NPM Package

Build Status MIT license

BitSet.js is an infinite Bit-Array (aka bit vector, bit string, bit set) implementation in JavaScript. That means that if you invert a bit vector, the leading ones get remembered. As far as I can tell, BitSet.js is the only library which has this feature. It is also heavily benchmarked against other implementations and is the most performant implementation to date.

Examples

Basic usage

let bs = new BitSet;
bs.set(128, 1); // Set bit at position 128
console.log(bs.toString(16)); // Print out a hex dump with one bit set

Flipping bits

let bs = new BitSet;
bs
  .flip(0, 62)
  .flip(29, 35);

let str = bs.toString();

if (str === "111111111111111111111111111000000011111111111111111111111111111") {
   console.log("YES!");
}

Range Set

let bs = new BitSet;
bs.setRange(10, 18, 1); // Set a 1 between 10 and 18, inclusive

User permissions

If you want to store user permissions in your database and use BitSet for the bit twiddling, you can start with the following Linux-style snippet:

let P_READ  = 2; // Bit pos
let P_WRITE = 1;
let P_EXEC  = 0;

let user = new BitSet;
user.set(P_READ); // Give read perms
user.set(P_WRITE); // Give write perms

let group = new BitSet(P_READ);
let world = new BitSet(P_EXEC);

console.log("0" + user.toString(8) + group.toString(8) + world.toString(8));

Installation

npm install bitset

or

bower install bitset.js

Using BitSet.js with the browser

<script src="bitset.js"></script>
<script>
    console.log(BitSet("111"));
</script>

Using BitSet.js with require.js

<script src="require.js"></script>
<script>
requirejs(['bitset.js'],
function(BitSet) {
    console.log(BitSet("1111"));
});
</script>

Constructor

The default BitSet constructor accepts a single value of one the following types :

  • String
    • Binary strings : new BitSet("010101")
    • Binary strings with prefix : new BitSet("0b010101")
    • Hexadecimal strings with prefix new BitSet("0xaffe")
  • Array
    • The values of the array are the indices to be set to 1 : new BitSet([1,12,9])
  • Uint8Array
    • A binary representation in 8 bit form
  • Number
    • A binary value
  • BitSet
    • A BitSet object, which get copied over

Functions

The data type Mixed can be either a BitSet object, a String or an integer representing a native bitset with 31 bits.

BitSet set(ndx[, value=0])

Mutable; Sets value 0 or 1 to index ndx of the bitset

int get(ndx)

Gets the value at index ndx

BitSet setRange(from, to[, value=1])

Mutable; Helper function for set, to set an entire range to a given value

BitSet clear([from[, to]])

Mutable; Sets a portion of a given bitset to zero

  • If no param is given, the whole bitset gets cleared
  • If one param is given, the bit at this index gets cleared
  • If two params are given, the range is cleared

BitSet slice([from[, to]])

Immutable; Extracts a portion of a given bitset as a new bitset

  • If no param is given, the bitset is getting cloned
  • If one param is given, the index is used as offset
  • If two params are given, the range is returned as new BitSet

BitSet flip([from[, to]])

Mutable; Toggles a portion of a given bitset

  • If no param is given, the bitset is inverted
  • If one param is given, the bit at the index is toggled
  • If two params are given, the bits in the given range are toggled

BitSet not()

Immutable; Calculates the bitwise complement

BitSet and(Mixed x)

Immutable; Calculates the bitwise intersection of two bitsets

BitSet or(Mixed x)

Immutable; Calculates the bitwise union of two bitsets

BitSet xor(Mixed x)

Immutable; Calculates the bitwise xor between two bitsets

BitSet andNot(Mixed x)

Immutable; Calculates the bitwise difference of two bitsets (this is not the nand operation!)

BitSet clone()

Immutable; Clones the actual object

Array toArray()

Returns an array with all indexes set in the bitset

String toString([base=2])

Returns a string representation with respect to the base

int cardinality()

Calculates the number of bits set

int msb()

Calculates the most significant bit (the left most)

int ntz()

Calculates the number of trailing zeros (zeros on the right). If all digits are zero, Infinity is returned, since BitSet.js is an arbitrary large bit vector implementation.

int lsb()

Calculates the least significant bit (the right most)

bool isEmpty()

Checks if the bitset has all bits set to zero

bool equals()

Checks if two bitsets are the same

BitSet.fromBinaryString(str)

Alternative constructor to pass with a binary string

BitSet.fromHexString(str)

Alternative constructor to pass a hex string

BitSet.Random([n=32])

Create a random BitSet with a maximum length of n bits

Iterator Interface

A BitSet object is iterable. The iterator gets all bits up to the most significant bit. If no bits are set, the iteration stops immediately.

let bs = BitSet.Random(55);
for (let b of bs) {
  console.log(b);
} 

Note: If the bitset is inverted so that all leading bits are 1, the iterator must be stopped by the user!

Coding Style

As every library I publish, BitSet.js is also built to be as small as possible after compressing it with Google Closure Compiler in advanced mode. Thus the coding style orientates a little on maxing-out the compression rate. Please make sure you keep this style if you plan to extend the library.

Build the library

Gulp is optional for minifying with Google Closure Compiler. After cloning the Git repository, do:

npm install
gulp

Run a test

Testing the source against the shipped test suite is as easy as

npm test

Copyright and licensing

Copyright (c) 2014-2018, Robert Eisele Dual licensed under the MIT or GPL Version 2 licenses.

Comments
  • Memory usage

    Memory usage

    Hello,

    First of all, bitset.js is a really useful tool. Thanks for your efforts.

    My question is about memory usage of a BitSet. I assume that a BitSet is as large as of its MSB. Let's say we have a BitSet whose 300,000,000th bit is set as 1, remaining are zero. We need to allocate 300M bits, right? If so, total size should be around ~35.7 MB. However, when I execute this scenario (set 300Mth bit as 1), BitSet size is calculated as 194.5 MB. I use an npm package object-sizeof to do that. I naturally don't expect it to allocate exactly 300M bits, instead a close number which is better for memory management. But the difference is huge. So, which is correct? Do I misunderstand something?

    Thanks.

    opened by can-keklik 10
  • If the data is completely zero, then count leading zeros and count trailing zeros should return the word size

    If the data is completely zero, then count leading zeros and count trailing zeros should return the word size

    I'm working on fixed size bitsets, and I create a 64 bit bitset by doing: new BitSet(new Uint8Arrray(4)).

    When calling ntz() on this object, it returns Infinity, IMO it should return the size of the bitmap which in this case is 64.

    If the word is zero (no bits set), count leading zeros and count trailing zeros both return the number of bits in the word, while ffs returns zero. Both log base 2 and zero-based implementations of find first set generally return an undefined result for the zero word. https://en.wikipedia.org/wiki/Find_first_set#Algorithms

    While ffs is something that could return Infinity.

    opened by CMCDragonkai 9
  • Webpack compatible version

    Webpack compatible version

    Hi,

    This is a great lib, especially the infinite length feature.

    Is it possible to get a published version that is compatible with webpack using ES5 exports?

    Many thanks!

    opened by jamesjryan 8
  • Usabiliity...

    Usabiliity...

    For the most part, I like BitSet however, (taking a clue from "Prototype the User Experience"), I think the usability could be increased if you made the following changes:

    1. All mathematical operations are immutable operations, which return back a new BitSet object.
    2. All other function, those that changes the object, are mutable. (E.g. Set(), SetRange(), Clear(), and (perhaps) Flip()).

    The reason for this is simple, I want to change the actual BitSet when I'm performing an operation directly on the object. However, like Math, operations like: 'and', 'or', "not' etc don't change the lhs or the rhs operands; they just return a new result value. Likewise, BitSet should do the same.

    I just spent 20 minutes tracking down a very subtle but because I forget to assign the return value from a Set operation to itself.

    This code feel very natural: permissions.set(Read) This doesn't feel natural: permissions = permission.set(Read)

    Hope that helps.

    opened by kabua 8
  • Initializing a new BitSet using a byte[]

    Initializing a new BitSet using a byte[]

    We have permission data stored as a byte[], can BitSet be initialized with a byte[]? If so, what would the syntax look like? something like: var bs = new BitSet(bitarray);

    And if not, how would we implement it?

    opened by kabua 6
  • Q: TypeScript Definition file?

    Q: TypeScript Definition file?

    Do you have a TypeScript Definition file? If not, I have a good start on one.

    Also, any plans on porting to TypeScript? If so (or not) my guys are thinking about porting it anyway. If they end up porting it, would you like a pull request?

    opened by kabua 4
  • A `size()` method

    A `size()` method

    Thanks for this library! In my testing, it is almost as fast as the one shipped with Java.

    I need a way to know how big the bitset is. size() or count() or something like that.

    This might be because the forEach() is still lacking, but I am not sure

    opened by PEZ 3
  • [Question] Optimized for large ranges of the same value?

    [Question] Optimized for large ranges of the same value?

    Does this library optimize large ranges of the same value?

    For example, if 1 million bits are marked true, then 1 million false, then one million true, is this internally represented using ranges to compress the information and optimize lookups?

    Can such a format be exported/imported to/from JSON?

    Perhaps there is another better suited data structure for this purpose?

    Thank you.

    opened by woodser 3
  • Use Gulp to build with Closure Compiler and improve performance of toString()

    Use Gulp to build with Closure Compiler and improve performance of toString()

    1. Use Gulp to build with Closure Compiler Fixed a couple of type warnings from Closure Compiler. Add a section in README.md explaining how to build the library.
    2. In toString(), pre-allocate 'arr' instead of growing it. This should improve performance on most JavaScript engines
    opened by Dominator008 3
  • Array parser

    Array parser

    I might be mis-reading the documentation, but as I understand, the following two objects should be equivalent:

    let a = new BitSet([34]).not()
    let b = new BitSet().set(34,1).not()
    

    however they are not:

    a.get(80)  // returns 0, not what I expected
    b.get(80)  // returns 1
    
    opened by shimaore 2
  • Misleading comments on [im]mutable functions

    Misleading comments on [im]mutable functions

    In bitset.js, and the .d.ts in #27, the comments for the bitwise operators include "The result is stored in-place".

    I see that the Readme.md does show the correct immutable description, but the inline documentation should either be kept up to date, too, or remove it.

    affected functions: and, or, andNot, not, xor

    opened by vrachels 2
  • Unexpected Results

    Unexpected Results

    I was trying to use this library to push to the client-side a few things that were being done server-side with either Java's BitSet or C#'s BitArray. Unfortunately, I've found some of the results did not match the values I'd expect.

    For example, I have a Uint8Array of [ 240, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 127, 255, 31 ,0 ,0]. When I check the toArray() it shows the first 'flipped' bit to be at index 8 (should be 4) and the indices 13, 14, and 15 to be set to 0 with quite a few more down the line that don't match the Java or C# response to the dame byte array.

    opened by jwsinner 2
  • How to use this most efficiently?

    How to use this most efficiently?

    Hi,

    I want to store 214 bits in a BitSet. When i do that it's data array is 10 elements. That's 10x 32bit int (320 bit). Ideally it would use the bare minimum in bit overhead. If that were to be done in 32 bit ints then 7 ints (224 bit) would suffice. More ideal would be an array of chars (8 bit each) where i'd need 27 chars giving me 216 bits of room.

    Are there arguments i can set in this class to get that more ideal behavior (ints or chars, both work)?

    opened by markg85 3
  • As we can construct a bitset object by a Buffer, Can we convert the bitset to Buffer

    As we can construct a bitset object by a Buffer, Can we convert the bitset to Buffer

    As we can construct a bitset object by a Buffer, Can we convert the bitset to Buffer

    let bitset = require("bitset"); let buf = Buffer.from([100, 97, 98]); let bs = bitset(buf); bs.toString(); '11000100110000101100100'

    Can we convert a bitset into buffer? let bs1 = new bitset(); bs1.setRange(4,9,1); { data: [ 1008, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], _: 0 } bs1.toString(); '1111110000'

    Now can this be converted into the buffer? eg. add the padding 0's left and make it's size multiple of 8 then convert to byte array or Buffer.

    opened by blyadav511 4
  • iterator: syntax error in IE

    iterator: syntax error in IE

    • OS: Windows 10 Pro
    • Browser: Internet Explorer 11 (and emulation back through 7 and 5)

    Error encountered:

    SCRIPT1028: Expected identifier, string or number
    bitset.js (911,5)
    

    which points to the following line:

    [Symbol.iterator]: function () {
    

    I wasn't familiar with this as valid JS syntax, but some Googling helped me discover it's called a "computed property name" and that IE doesn't support it. I'm aware that IE is largely obsolete with Microsoft's promotion of Edge, but it still exists and does function as a modern browser for the most part. Could you switch to alternate syntax for adding the iterator? Many thanks!

    opened by microshnik 9
  • Shifts

    Shifts

    Re #39. I don't know that I got the implementation right, but it works so far with the test cases I've added. I hope you'll consider adding shifts to the library.

    I noted that the gulpfile is not compatible with gulp 4, so it might be a good idea to change the gulp dependency to version 3. I didn't include a minified file, as it will of course be an ugly diff, but I did generate one in order to run tests.

    All the best, Karl

    opened by karlvr 0
Owner
Robert Eisele
Mathematics, Machine Learning, Databases, Robotics, Hardware Hacking
Robert Eisele
Analysis of WordPress 3D Print Lite 1.9.1.4 - arbitrary file upload vulnerability.

3DPrint-Lite-1.9.1.4-File-Upload Analysis of WordPress 3D Print Lite 1.9.1.4 - arbitrary file upload vulnerability. The Vulnerability: This vulnerabil

Jakom 4 Mar 15, 2022
SPOILER ALERT! A happy little bit of javascript to hide spoilers on your site.

SPOILER ALERT! Don't spoil it! Hide copy and images with a bit of SVG blur. Taste on mouseover. Eat on click. Do you publish spoilers? Do you wish you

Joshua Hull 473 Sep 27, 2022
Gmail-like client-side drafts and bit more. Plugin developed to save html forms data to LocalStorage to restore them after browser crashes, tabs closings and other disasters.

Sisyphus Plugin developed to save html forms data to LocalStorage to restore them after browser crashes, tabs closings and other disasters. Descriptio

Alexander Kaupanin 2k Dec 8, 2022
An implementation of cellular automata in TypeScript

?? cellular-automata An implementation of cellular automata in TypeScript. ?? Usage First of all, clone the repository: $ git clone [email protected]:aro

Faye's Games 2 Feb 7, 2022
A simple implementation of a task list application that can be used to add, remove, edit and check users tasks

"To-do list" is a tool that helps to organize daily activites. It simply lists the things which are needed to be done and allows user to mark them as complete. In this step of project, the CRUD (create, update, delete) methods are implemented. This simple web page is built using webpack and served by a webpack dev server.

Zahra Arshia 5 Mar 28, 2022
JavaScript Survey and Form Library

SurveyJS is a JavaScript Survey and Form Library. SurveyJS is a modern way to add surveys and forms to your website. It has versions for Angular, jQue

SurveyJS 3.5k Jan 1, 2023
⚡️ A resource to help figure out what JavaScript array method would be best to use at any given time

JavaScript Array Explorer When I was first learning array methods, I spent a lot of time digging through the docs to find the appropriate one, and I h

Sarah Drasner 2.6k Jan 2, 2023
🌳 Tiny & elegant JavaScript HTTP client based on the browser Fetch API

Huge thanks to for sponsoring me! Ky is a tiny and elegant HTTP client based on the browser Fetch API Ky targets modern browsers and Deno. For older b

Sindre Sorhus 8.5k Jan 2, 2023
Extensive math expression evaluator library for JavaScript and Node.js

?? Homepage Fcaljs is an extensive math expression evaluator library for JavaScript and Node.js. Using fcal, you can perform basic arithmetic, percent

Santhosh Kumar 93 Dec 19, 2022
Vanilla JavaScript emoji picker component

Vanilla JavaScript emoji picker ?? Screenshot Demo and Documentation https://emoji-button.js.org Features ?? Vanilla JS, use with any framework ?? Use

Joe Attardi 1.1k Dec 31, 2022
📝 Algorithms and data structures implemented in JavaScript with explanations and links to further readings

JavaScript Algorithms and Data Structures This repository contains JavaScript based examples of many popular algorithms and data structures. Each algo

Oleksii Trekhleb 158k Dec 31, 2022
This is my To-do-list project for my Javascript module at Microverse.

To do List This is a To do list project built for learning purposes. Built With HTML Bootstrap Javascript CSS HTML Webpack How to use it Clone the rep

Jonathas Tavares 4 Oct 8, 2021
A JavaScript, zero-dependency, super small version of IP2Location LITE country lookups.

A JavaScript, zero-dependency, super small version of IP2Location LITE country lookups.

Statsig 34 Dec 14, 2022
An easy to use, yet advanced and fully customizable javascript/jQuery paginator plugin

anyPaginator An easy to use, yet advanced and fully customizable Javascript/jQuery paginator plugin. anyPaginator is a spinoff of the anyList project

Arne Morken 2 Feb 17, 2022
Shikimori.ts - JavaScript & TypeScript wrapper for shikimori.one

shikimori.ts shikimori.ts - JavaScript & TypeScript wrapper for shikimori.one Features Full TypeScript support Support all platforms Easy to use Table

null 5 Sep 15, 2022
This library was designed to be used in SPA framework wrappers for the FingerprintJS Pro Javascript Agent

Framework-agnostic SPA service wrapper. Use it to build a FingerprintJS Pro wrapper for your favorite framework.

FingerprintJS 12 Sep 3, 2022
ChelseaJS - a Javascript library for creative, generative Coding

ChelseaJS is a Javascript library for creative, generative Coding. It's simple and intuitive syntax makes it easy for everyone (including non-coders)

Prakrisht Dahiya 26 Oct 6, 2022
Estrela - a JavaScript library for building reactive web components inspired by lit

Estrela ⭐ Full Reactive Web Components Estrela is a JavaScript library for building reactive web components inspired by lit. Just like Lit, Estrela is

null 50 Oct 31, 2022
Responsive, interactive and more accessible HTML5 canvas elements. Scrawl-canvas is a JavaScript library designed to make using the HTML5 canvas element a bit easier, and a bit more fun!

Scrawl-canvas Library Version: 8.5.2 - 11 Mar 2021 Scrawl-canvas website: scrawl-v8.rikweb.org.uk. Do you want to contribute? I've been developing thi

Rik Roots 227 Dec 31, 2022
An HTML5/Canvas implementation of 8-bit color cycling

Overview Here is the JavaScript and C++ source code to my color cycling engine, written in 2010. I am releasing it under the LGPL v3.0. The package co

Joseph Huckaby 8 Dec 1, 2022