bitfun

bitfun

Functions for manipulating bitmasks as numbers. Deterministic, without side effects.

Installation

npm i bitfun -S

How to play

import * as bitfun from 'bitfun';

...
const mask = bitfun.add(1, [1,2]) // mask equals 3
...

- But i don't like using numbers!
- Easy

import * as bitfun from 'bitfun';

const rights = {
  NONE: 0,
  READ: 1,
  WRITE: 2,
  EXECUTE: 4
};

...
if (bitfun.includes(user.rights, [rights.READ, rights.WRITE])) {
...

You can put constants to separate file and import them as you wish.

API

bitfun.fromArray(array)

• array <Array<Number>> Array of flags.
• Returns: <Number> Bitmask.

Creates a new bitmask from specified array.

> bitfun.fromArray([1,2])    01,10
< 3                          11

> bitfun.fromArray([1,2,3])    01,10,11
< 3                            11

bitfun.toArray(mask)

• mask <Number> Bitmask.
• Returns: <Array<Number>> Array of flags.

Creates array of flags from specified bitmask.

> bitfun.toArray(3)         11
< [1,2]                     01,10

> bitfun.toArray(5)         101
< [1,4]                     001,100

> bitfun.toArray(0)
< []

bitfun.add(mask, array)

• mask <Number> Bitmask.
• array <Array<Number>> Array of flags.
• Returns: <Number> New bitmask.

Adds bits to an existing bitmask.

> bitfun.add(2, [1])        10 | 01
< 3                         11

> bitfun.add(3, [1,2,3])    11 | 01,10,11
< 3                         11

bitfun.remove(mask, array)

• mask <Number> Bitmask.
• array <Array<Number>> Array of flags.
• Returns: <Number> New bitmask.

Removes bits from an existing bitmask.

> bitfun.remove(2, [1])       10 | 01
< 2                           10

> bitfun.remove(3, [1,2,3])   11 | 01,10,11
< 0                           00

bitfun.equals(mask, array)

• mask <Number> Bitmask.
• array <Array<Number>> Array of flags.
• Returns: <Boolean> Match.

Returns true if mask includes only specified bits.

> bitfun.equals(2, [1])      10 | 01
< false                      10 | 01

> bitfun.equals(2, [1, 2])   10 | 01,10
< false                      10 | 11

> bitfun.equals(3, [1])      11 | 01
< false                      11 | 01

> bitfun.equals(3, [1,2])    11 | 01,10
< true                       11 | 11

bitfun.includes(mask, array)

• mask <Number> Bitmask.
• array <Array<Number>> Array of flags.
• Returns: <Boolean> Match.

Returns true if mask includes all of the specified bits.

> bitfun.includes(2, [1])      10 | 01
< false                        10 | 01

> bitfun.includes(2, [1,2])    10 | 01,10
< false                        10 | 11

> bitfun.includes(3, [1])      11 | 01
< true                         11 | 01

> bitfun.includes(3, [1,2])    11 | 01,10
< true                         11 | 11

bitfun.excludes(mask, array)

• mask <Number> Bitmask.
• array <Array<Number>> Array of flags.
• Returns: <Boolean> Match.

Returns true if mask includes some or none of the specified bits.

> bitfun.excludes(2, [1])      10 | 01
< true                         10 | 01

> bitfun.excludes(2, [1,2])    10 | 01,10
< true                         10 | 11

> bitfun.excludes(3, [1])      11 | 01
< false                        11 | 01

> bitfun.excludes(3, [1,2])    11 | 01,10
< false                        11 | 11

bitfun.noneOf(mask, array)

• mask <Number> Bitmask.
• array <Array<Number>> Array of flags.
• Returns: <Boolean> Match.

Returns true if mask includes none of the specified bits.

> bitfun.noneOf(2, [1])      10 | 01
< true                       10 | 01

> bitfun.noneOf(2, [1,2])    10 | 01,10
< false                      10 | 11

> bitfun.noneOf(3, [1])      11 | 01
< false                      11 | 01

> bitfun.noneOf(3, [1,2])    11 | 01,10
< false                      11 | 11

Testing

npm test