Skip to content

Latest commit

 

History

History
733 lines (516 loc) · 14.9 KB

readme.md

File metadata and controls

733 lines (516 loc) · 14.9 KB
Raw

bitwise

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

Example

import bitwise from 'bitwise'

const bits = bitwise.byte.read(42)
// [0, 0, 1, 0, 1, 0, 1, 0]

bitwise.bits.toString(bits, 4)
// '0010 1010'

bitwise.byte.write(bits)
// 42

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

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

// cherry-pick parts of bitwise
import byte from 'bitwise/byte'
byte.read(42)
// [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

// cherry-pick
import and from 'bitwise/bits/and'
import bits from 'bitwise/bits'
import toString from 'bitwise/bits/to-string'

bits.and

(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.

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

bits.circularShiftLeft

(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.

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

bits.circularShiftRight

(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.

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

bits.nand

(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.

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

bits.nor

(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.

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

bits.not

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

Flips all given bits and returns the flipped bits.

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

bits.or

(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.

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

bits.xnor

(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.

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

bits.xor

(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.

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

bits.reduceAnd

(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.

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

bits.reduceNand

(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.

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

bits.reduceNor

(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.

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

bits.reduceOr

(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.

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

bits.reduceXnor

(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.

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

bits.reduceXor

(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.

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

bits.toBoolean

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

Converts a bit array to a boolean array.

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

bits.toString

(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.

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

buffer

// cherry-pick
import and from 'bitwise/buffer/and'
import buffer from 'bitwise/buffer'
import create from 'bitwise/buffer/create'

buffer.create

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

Creates a new buffer and writes the given bits.

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

buffer.modify

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

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

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

buffer.and

(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.

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

buffer.nand

(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.

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

buffer.nor

(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.

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

buffer.not

(buffer: Buffer): Buffer

Flips all bits in the given buffer.

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

buffer.or

(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.

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

buffer.xnor

(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.

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

buffer.xor

(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.

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

buffer.read

(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.

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

buffer.readInt

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

Converts a section of a buffer to a signed integer.

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

buffer.readUInt

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

Converts a section of a buffer to an unsigned integer.

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

byte

// cherry-pick
import byte from 'bitwise/byte'
import read from 'bitwise/byte/read'

byte.read

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

Returns an Array of length 8 containing the read bits.

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

byte.write

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

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

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

integer

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

integer.getBit

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

Gets the value of a specific bit.

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

integer.setBit

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

Sets the value of a specific bit.

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

integer.toggleBit

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

Toggles the value of a specific bit.

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

nibble

// cherry-pick
import nibble from 'bitwise/nibble'
import read from 'bitwise/nibble/read'

nibble.read

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

Returns an Array of length 4 containing the read bits.

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

nibble.write

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

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

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

string

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

string.toBits

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

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

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

Development

bitwise uses bun instead of node

# install dependencies
bun install

# run tests
bun test

# build
bun 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