bitwise

JavaScript/TypeScript library to manipulate bits, nibbles, bytes, and buffers.

Example

1import bitwise from 'bitwise'
2
3const bits = bitwise.byte.read(42)
4// [0, 0, 1, 0, 1, 0, 1, 0]
5
6bitwise.bits.toString(bits, 4)
7// '0010 1010'
8
9bitwise.byte.write(bits)
10// 42
11
12bitwise.bits.and([0, 0, 1, 1], [0, 1, 0, 1])
13// [0, 0, 0, 1]
14
15bitwise.bits.xor([0, 0, 1, 1], [0, 1, 0, 1])
16// [0, 1, 1, 0]
17
18// cherry-pick parts of bitwise
19import byte from 'bitwise/byte'
20byte.read(42)
21// [0, 0, 1, 0, 1, 0, 1, 0]

Installation

bun add bitwise

or

yarn add bitwise

or

npm install --save bitwise

Table of Contents

• bits
  • operations (and, circularShiftLeft, circularShiftRight, nand, nor, not, or, xnor, xor)
  • reduce operations (reduceAnd, reduceNand, reduceNor, reduceOr, reduceXnor, reduceXor)
  • toString
• buffer
  • create
  • modify
  • operations (and, nand, nor, not, or, xnor, xor)
  • read
  • readInt
  • readUInt
• byte
  • read
  • write
• integer
  • getBit
  • setBit
  • toggleBit
• nibble
  • read
  • write
• string
  • toBits

bits

1// cherry-pick
2import and from 'bitwise/bits/and'
3import bits from 'bitwise/bits'
4import toString from 'bitwise/bits/to-string'

bits.and

1(bits1: Array<0|1>, bits2: Array<0|1>): Array<0|1>

Applies the bitwise AND operation, expects two arrays of the same size and returns a new one.

1bitwise.bits.and([1, 0, 0, 0, 1, 1, 0, 1], [0, 1, 1, 0, 0, 1, 0, 0])
2// [0, 0, 0, 0, 0, 1, 0, 0]

bits.circularShiftLeft

1(bits: Array<0|1>, amount: number): Array<0|1>

Applies the bitwise ROL operation, expects two arrays of the same size and a shift amount and returns a new one.

1bitwise.bits.circularShiftLeft([0, 0, 0, 1, 1, 1, 1, 1], 1)
2// [0, 0, 1, 1, 1, 1, 1, 0]

bits.circularShiftRight

1(bits: Array<0|1>, amount: number): Array<0|1>

Applies the bitwise ROR operation, expects two arrays of the same size and a shift amount and returns a new one.

1bitwise.bits.circularShiftRight([0, 0, 0, 1, 1, 1, 1, 1], 1)
2// [1, 0, 0, 0, 1, 1, 1, 1]

bits.nand

1(bits1: Array<0|1>, bits2: Array<0|1>): Array<0|1>

Applies the bitwise NAND operation, expects two arrays of the same size and returns a new one.

1bitwise.bits.nand([1, 0, 0, 0, 1, 1, 0, 1], [0, 1, 1, 0, 0, 1, 0, 0])
2// [1, 1, 1, 0, 1, 0, 0, 1]

bits.nor

1(bits1: Array<0|1>, bits2: Array<0|1>): Array<0|1>

Applies the bitwise NOR operation, expects two arrays of the same size and returns a new one.

1bitwise.bits.nor([1, 0, 0, 0, 1, 1, 0, 1], [0, 1, 1, 0, 0, 1, 0, 0])
2// [1, 1, 1, 0, 1, 0, 0, 1]

bits.not

1(bits: Array<0|1>): Array<0|1>

Flips all given bits and returns the flipped bits.

1bitwise.bits.not([1, 0, 1, 1, 0, 1])
2// [0, 1, 0, 0, 1, 0]

bits.or

1(bits1: Array<0|1>, bits2: Array<0|1>): Array<0|1>

Applies the bitwise OR operation, expects two arrays of the same size and returns a new one.

1bitwise.bits.or([1, 0, 0, 0, 1, 1, 0, 1], [0, 1, 1, 0, 0, 1, 0, 0])
2// [1, 1, 1, 0, 1, 1, 0, 1]

bits.xnor

1(bits1: Array<0|1>, bits2: Array<0|1>): Array<0|1>

Applies the bitwise exclusive NOR operation, expects two arrays of the same size and returns a new one.

1bitwise.bits.xnor([1, 0, 0, 0, 1, 1, 0, 1], [0, 1, 1, 0, 0, 1, 0, 0])
2// [1, 1, 1, 0, 1, 0, 0, 1]

bits.xor

1(bits1: Array<0|1>, bits2: Array<0|1>): Array<0|1>

Applies the bitwise exclusive OR operation, expects two arrays of the same size and returns a new one.

1bitwise.bits.xor([1, 0, 0, 0, 1, 1, 0, 1], [0, 1, 1, 0, 0, 1, 0, 0])
2// [1, 1, 1, 0, 1, 0, 0, 1]

bits.reduceAnd

1(bits: Array<0|1>): 0|1

Applies the bitwise AND operation on the given bits. Returns one bit. Throws if less than 2 bits are given.

1bitwise.bits.reduceAnd([1, 0, 0, 0, 1, 1, 0, 1])
2// 0

bits.reduceNand

1(bits: Array<0|1>): 0|1

Applies the NAND operation on the given bits. Returns one bit. Throws if less than 2 bits are given.

1bitwise.bits.reduceNand([1, 0, 0, 0, 1, 1, 0, 1])
2// 0

bits.reduceNor

1(bits: Array<0|1>): 0|1

Applies the NOR operation on the given bits. Returns one bit. Throws if less than 2 bits are given.

1bitwise.bits.reduceNor([1, 0, 0, 0, 1, 1, 0, 1])
2// 0

bits.reduceOr

1(bits: Array<0|1>): 0|1

Applies the OR operation on the given bits. Returns one bit. Throws if less than 2 bits are given.

1bitwise.bits.reduceOr([1, 0, 0, 0, 1, 1, 0, 1])
2// 1

bits.reduceXnor

1(bits: Array<0|1>): 0|1

Applies the XNOR operation on the given bits. Returns one bit. Throws if less than 2 bits are given.

1bitwise.bits.reduceXnor([1, 0, 0, 0, 1, 1, 0, 1])
2// 1

bits.reduceXor

1(bits: Array<0|1>): 0|1

Applies the XOR operation on the given bits. Returns one bit. Throws if less than 2 bits are given.

1bitwise.bits.reduceXor([1, 0, 0, 0, 1, 1, 0, 1])
2// 0

bits.toBoolean

1(bits: Array<0|1>): Array<boolean>

Converts a bit array to a boolean array.

1bitwise.bits.toBoolean([0, 1])
2// [false, true]

bits.toString

1(bits: Array<0|1>, spacing: number = 0, spacer: string = ' '): string

Converts a bit Array to a String. If defined, inserts spacer every spacing characters, but never inserts it as the last substring.

1bitwise.bits.toString([1, 0, 1, 0, 1, 0], 2, '_')
2// '10_10_10'

buffer

1// cherry-pick
2import and from 'bitwise/buffer/and'
3import buffer from 'bitwise/buffer'
4import create from 'bitwise/buffer/create'

buffer.create

1(bits: Array<0|1>): Buffer

Creates a new buffer and writes the given bits.

1const buffer = bitwise.buffer.create([1, 1, 1, 1, 0, 0, 0, 1, 1, 0, 1, 0])
2// Buffer(1111 0001 1010 0000)

buffer.modify

1(buffer: Buffer, newBits: Array<0|1>, bitOffset: number = 0): void

Modifies the buffer's bits to equal newBits starting at bitOffset.

1const buffer = Buffer.from('A43A', 'hex')
2bitwise.buffer.modify(buffer, [0, 0, 0, 1, 0, 0, 1], 3)
3// Buffer(1010 1001 0011 1010)

buffer.and

1(buffer1: Buffer, buffer2: Buffer, isLooping = false): Buffer

Applies a bitwise AND with buffer2 to every value in buffer1. Returns a new buffer. If isLooping is set, buffer1 may be read multiple times in case it's shorter than buffer2.

1bitwise.buffer.and(buffer1, buffer2, false)
2// Buffer(buffer1 AND buffer2)

buffer.nand

1(buffer1: Buffer, buffer2: Buffer, isLooping = false): Buffer

Applies a bitwise NAND with buffer2 to every value in buffer1. Returns a new buffer. If isLooping is set, buffer1 may be read multiple times in case it's shorter than buffer2.

1bitwise.buffer.nand(buffer1, buffer2, false)
2// Buffer(buffer1 NAND buffer2)

buffer.nor

1(buffer1: Buffer, buffer2: Buffer, isLooping = false): Buffer

Applies a bitwise NOR with buffer2 to every value in buffer1. Returns a new buffer. If isLooping is set, buffer1 may be read multiple times in case it's shorter than buffer2.

1bitwise.buffer.nor(buffer1, buffer2, false)
2// Buffer(buffer1 NOR buffer2)

buffer.not

1(buffer: Buffer): Buffer

Flips all bits in the given buffer.

1bitwise.buffer.not(buffer, false)
2// Buffer(NOT buffer)

buffer.or

1(buffer1: Buffer, buffer2: Buffer, isLooping = false): Buffer

Applies a bitwise OR with buffer2 to every value in buffer1. Returns a new buffer. If isLooping is set, buffer1 may be read multiple times in case it's shorter than buffer2.

1bitwise.buffer.or(buffer1, buffer2, false)
2// Buffer(buffer1 OR buffer2)

buffer.xnor

1(buffer1: Buffer, buffer2: Buffer, isLooping = false): Buffer

Applies a bitwise XNOR with buffer2 to every value in buffer1. Returns a new buffer. If isLooping is set, buffer1 may be read multiple times in case it's shorter than buffer2.

1bitwise.buffer.xnor(buffer1, buffer2, false)
2// Buffer(buffer1 XNOR buffer2)

buffer.xor

1(buffer1: Buffer, buffer2: Buffer, isLooping = false): Buffer

Applies a bitwise XOR with buffer2 to every value in buffer1. Returns a new buffer. If isLooping is set, buffer1 may be read multiple times in case it's shorter than buffer2.

1bitwise.buffer.xor(buffer1, buffer2, false)
2// Buffer(buffer1 XOR buffer2)

buffer.read

1(buffer: Buffer, bitOffset: number = 0, bitLength?: number): Array<0|1>

Returns an Array containing bitLength bits starting at bitOffset. If no bitLength is given, it's assumed to be the rest of the buffer.

1const buffer = Buffer.from('ED743E17', 'hex')
2bitwise.buffer.read(buffer, 12)
3// [0, 1, 0, 0, 0, 0, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1]

buffer.readInt

1(buffer: Buffer, bitOffset: number = 0, bitLength: number = 8): number

Converts a section of a buffer to a signed integer.

1// buffer 11110110
2bitwise.buffer.readInt(buffer, 3, 5)
3// -10

buffer.readUInt

1(buffer: Buffer, bitOffset: number = 0, bitLength: number = 8): number

Converts a section of a buffer to an unsigned integer.

1// buffer 11110110
2bitwise.buffer.readUInt(buffer, 3, 5)
3// 22

byte

1// cherry-pick
2import byte from 'bitwise/byte'
3import read from 'bitwise/byte/read'

byte.read

1(byte: UInt8): Array<0|1>

Returns an Array of length 8 containing the read bits.

1bitwise.byte.read(42)
2// [0, 0, 1, 0, 1, 0, 1, 0]
3bitwise.byte.read(256)
4// RangeError('invalid size')

byte.write

1(bits: Array<0|1>): UInt8

Returns a Byte (0-255) which represents the given bits.

1bitwise.byte.write([0, 0, 1, 0, 1, 0, 1, 0])
2// 42
3bitwise.byte.write([0, 0, 1, 0, 1, 0, 1, 0, 0])
4// RangeError('invalid array length')

integer

1// cherry-pick
2import integer from 'bitwise/integer'

integer.getBit

1(number: number, position: number): 0|1

Gets the value of a specific bit.

1bitwise.integer.getBit(128, 7)
2// 1

integer.setBit

1(number: number, position: number, value: 0|1): Array<0|1>

Sets the value of a specific bit.

1bitwise.integer.setBit(128, 7, 0)
2// 0

integer.toggleBit

1(number: number, position: number): Array<0|1>

Toggles the value of a specific bit.

1bitwise.integer.toggleBit(128, 7)
2// 0

nibble

1// cherry-pick
2import nibble from 'bitwise/nibble'
3import read from 'bitwise/nibble/read'

nibble.read

1(nibble: UInt4): Array<0|1>

Returns an Array of length 4 containing the read bits.

1bitwise.nibble.read(15)
2// [1, 1, 1, 1]
3bitwise.nibble.read(42)
4// RangeError('invalid size')

nibble.write

1(nibble: [<0|1>, <0|1>, <0|1>, <0|1>]): UInt4

Returns a Nibble (0-15) which represents the given bits.

1bitwise.nibble.write([0, 0, 1, 0])
2// 2
3bitwise.nibble.write([0, 0, 1, 0, 1])
4// RangeError('invalid array length')

string

1// cherry-pick
2import string from 'bitwise/string'
3import toBits from 'bitwise/string/to-bits'

string.toBits

1(string: string): Array<0|1>

Converts a string into an array of bits. Ignores all characters except 1 and 0.

1bitwise.string.toBits('10 10 12$%_.0')
2// [1, 0, 1, 0, 1, 0]

Development

bitwise uses bun instead of node

1# install dependencies
2bun install
3
4# run tests
5bun test
6
7# build
8bun run build

History

2.2.1

• remove typescript from dependencies in favor of devDependencies
• (internal) update and apply prettier

2.2.0

• add npm provenance support to package
• (internal) add auto-publish from pipelines
• (internal) Switch to bun

2.1.0

• Add bits.circularShiftLeft (#44 / #49) via @0xflotus
• Add bits.circularShiftRight (#44 / #49) via @0xflotus

2.0.2–2.0.3

• Add Support for Tree Shaking

2.0.1

• Readme/package.json updates

2.0.0

• refactor to typescript
• remove bitwise.buffer.readCInt()

1.4.0

• improve require() support

1.3.0

• add bits.toBoolean

1.2.0

• add bits.reduceAnd
• add bits.reduceNand
• add bits.reduceNor
• add bits.reduceOr
• add bits.reduceXnor
• add bits.reduceXor

1.1.2

• split up buffer.operations

1.1.1

• split up bits.operations

1.1.0

• add integer.getBit
• add integer.setBit
• add integer.toggleBit

1.0.0

• rewrite in ES6
• improve utilization of bitwise operators
• improve API (breaking change)

0.2.0

• Added buffer bitwise operations

0.1.2

• Added nor, xnor, nand
• Fixed bitwise operations modifying original array

0.1.0

• Re-ordered the arguments in readInt, readCInt, readUInt
• Added not, and, or, xor
• Renamed flipBits to not