The bitset-mut package exports a single BitSet class.

import { BitSet } from "bitset-mut";

const bitset = new BitSet();

As the package name suggests, most methods mutate the original BitSet instead of returning a new BitSet. This is done because cloning large BitSets may prove expensive.

This can be worked around by cloning before mutating via the clone() method.

Performance

This package is benchmarked against other popular bit set implementations in the benchmarks/ directory. An overview is available at benchmarks/README.md.

Basic usage

import { BitSet } from "bitset-mut";

const a = new BitSet();
const b = new BitSet();

a.add(0).add(2);
b.flip(4, 7);

console.log(a.or(b).toString());
//=> "11110101"

Creating a BitSet

The BitSet constructor accepts:

• A bit string, only comprised of 0s and 1s (e.g. "10011010")
• An array of indices, which sets the bits at the provided indices
• Another BitSet, which clones the provided BitSet

If no arguments are provided, an empty BitSet is created.

new BitSet().toString();
//=> "0"

new BitSet("01100101").toString();
//=> "1100101"

new BitSet([0, 1, 5]).toString();
//=> "100011"

You can also create BitSets using a few static methods:

BitSet.fromIndices([0, 1, 5]).toString();
//=> "100011"

BitSet.fromBitMask(0b1001).toString();
//=> "1001"

BitSet.random(10).toString();
//=> "101001101"

Serializing a BitSet

The toString method on BitSet returns a string of 0s and 1s.

BitSet.fromBitMask(0b1001).toString();
//=> "1001"

You can also use the toArray method to get an array containing the index of each set bit (in ascending order):

BitSet.fromBitMask(0b1001).toArray();
//=> [0, 3]

Usage

• BitSet.add
• BitSet.remove
• BitSet.has
• BitSet.set
• BitSet.setRange
• BitSet.setMultiple
• BitSet.flip
• BitSet.slice
• BitSet.invert
• BitSet.and
• BitSet.or
• BitSet.andNot
• BitSet.xor
• BitSet.clear
• BitSet.empty
• BitSet.equals
• BitSet.intersects
• BitSet.isEmpty
• BitSet.clone
• BitSet.forEach
• BitSet[Symbol.iterator]
• BitSet.toString
• BitSet.toArray
• BitSet.size
• BitSet.length
• BitSet.cardinality

class BitSet {
  add(index: number): BitSet;
}

Sets the bit at index to 1, adding index to the set.

class BitSet {
  remove(index: number): BitSet;
}

Sets the bit at index to 0, removing index from the set.

class BitSet {
  has(index: number): boolean;
}

Returns true if the bit at index is set to 0, and false otherwise.

class BitSet {
  set(index: number, value?: number = 1): boolean;
}

Sets the bit at index to 1 if value is truthy, and 0 otherwise. If value is not provided, it defaults to 1.

class BitSet {
  setRange(from: number, to: number, value?: number = 1): boolean;
}

Sets the bits between from and to (inclusive) to 1 if value is truthy, and 0 otherwise. If value is not provided, it defaults to 1.

class BitSet {
  setMultiple(indices: number[], value?: number = 1): boolean;
}

Sets the bit at the indices to 1 if value is truthy, and 0 otherwise. If value is not provided, it defaults to 1.

class BitSet {
  flip(index: number): BitSet;
}

Flips the bit at index, changing 0 to 1 and 1 to 0.

BitSet.flip(from, to)

class BitSet {
  flip(from: number, to: number): BitSet;
}

Flips the bits between from and to (inclusive), changing 0 to 1 and 1 to 0.

class BitSet {
  slice(): BitSet;
}

Clones the bit set. To clone a specific portion, use BitSet.slice(from, to).

BitSet.slice(from, to)

class BitSet {
  slice(from: number, to: number): BitSet;
}

Returns a new BitSet only containing the bits in the range from (inclusive) and to (exclusive).

class BitSet {
  invert(): BitSet;
}

Inverts every bit in the bit set, changing 0 to 1 and 1 to 0.

class BitSet {
  and(other: BitSet): BitSet;
}

Performs bitwise AND (intersection), mutating the BitSet.

const a = new BitSet("1011");
const b = new BitSet("1101");

a.and(b);

a.toString(); // 'a' has been mutated
//=> "1001"

b.toString(); // 'b' has not been mutated
//=> "1101"

class BitSet {
  or(other: BitSet): BitSet;
}

Performs bitwise OR (union), mutating the BitSet.

const a = new BitSet("0101");
const b = new BitSet("1100");

a.or(b);

a.toString(); // 'a' has been mutated
//=> "1101"

b.toString(); // 'b' has not been mutated
//=> "1100"

class BitSet {
  andNot(other: BitSet): BitSet;
}

Performs bitwise AND NOT (subtraction), mutating the BitSet.

const a = new BitSet("0111");
const b = new BitSet("1100");

a.andNot(b);

a.toString(); // 'a' has been mutated
//=> "0011"

b.toString(); // 'b' has not been mutated
//=> "1100"

class BitSet {
  xor(other: BitSet): BitSet;
}

Performs bitwise XOR, mutating the BitSet.

const a = new BitSet("0111");
const b = new BitSet("1100");

a.xor(b);

a.toString(); // 'a' has been mutated
//=> "1011"

b.toString(); // 'b' has not been mutated
//=> "1100"

class BitSet {
  clear(): BitSet;
}

Sets all bits to zero without changing the size of the BitSet.

BitSet.clear(index)

class BitSet {
  clear(index: number): BitSet;
}

Sets the bit at the specified index to zero.

BitSet.clear(from, to)

class BitSet {
  clear(from: number, to: number): BitSet;
}

Sets the bits between from and to (inclusive) to zero

class BitSet {
  empty(): BitSet;
}

Removes all bits from the bitset, setting its size to 0.

class BitSet {
  equals(other: BitSet): boolean;
}

Returns true if this and the other BitSet are equal (have the same bits set to 1). The size of the BitSets is not considered.

class BitSet {
  intersects(other: BitSet): boolean;
}

Returns true if this and the other BitSet have any bits set to 1 in common (i.e. if they overlap).

class BitSet {
  isEmpty(): boolean;
}

Returns true if no bits are set to 1.

class BitSet {
  clone(): BitSet;
}

Returns a clone of the BitSet.

class BitSet {
  forEach(callback: (index: number) => void): void;
}

Invokes callback with the index of every bit set to 1, in ascending order.

class BitSet {
  [Symbol.iterator](): Iterator<number>;
}

Returns an iterator that yields the index of every bit set to 1, in ascending order.

class BitSet {
  toString(): string;
}

Returns the BitSet serialized as a bit string (e.g. "10001010").

class BitSet {
  toArray(): number[];
}

Returns an array containing the index of each set bit (in ascending order).

class BitSet {
  cardinality(): number;
}

Returns the number of bits (i.e. count) set to 1.

class BitSet {
  size: number;
}

Returns the number of bits in the BitSet, including both bits set to 1 and 0.

class BitSet {
  length: number;
}

Returns the number of words (32-bit integers) in the BitSet.