bitwise

JavaScript 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.xor([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

yarn add bitwise

or

npm i bitwise

Table of Contents

• bits
  • operations (and, nand, nor, not, or, xnor, xor)
  • toString
• buffer
  • create
  • modify
  • operations (and, nand, nor, not, or, xnor, xor)
  • read
  • readCInt
  • readInt
  • readUInt
• byte
  • read
  • write
• integer
  • getBit
  • setBit
  • toggleBit
• nibble
  • read
  • write
• string
  • toBits

bits

bits.and

(bits1: Array, bits2: Array)

Applies the 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.nand

(bits1: Array, bits2: Array)

Applies the 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, bits2: Array)

Applies the 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)

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, bits2: Array)

Applies the 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, bits2: Array)

Applies the 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, bits2: Array)

Applies the 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.toString

(bits: Array, spacing = 0, spacer = ' ')

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 buffer from 'bitwise/buffer'

buffer.create

(bits: Array)

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, bitOffset = 0)

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

const buffer = new Buffer('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)

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)

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)

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)

Flips all bits in the given buffer.

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

buffer.or

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

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)

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)

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 = 0, bitLength = 8)

Returns an Array containing bitLength bits starting at bitOffset.

const buffer = new Buffer('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.readCInt

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

Converts a section of a buffer to a complementary integer. A complementary integer is like an unsigned integer, but always represents negative numbers.

// buffer 11110110
bitwise.buffer.readCInt(buffer, 3, 5)
// -22

buffer.readInt

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

Converts a section of a buffer to a signed integer.

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

buffer.readUInt

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

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'

byte.read

(byte: Integer)

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)

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: Integer, position: Integer)

Gets the value of a specific bit.

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

integer.setBit

(number: Integer, position: Integer, value: Integer)

Sets the value of a specific bit.

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

integer.toggleBit

(number: Integer, position: Integer)

Toggles the value of a specific bit.

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

nibble

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

nibble.read

(nibble: Integer)

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: Array)

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'

string.toBits

(string: String)

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]

History

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