Usage

npm install @codescrum/bitmask-set-jsbi

import{BitmaskSet,Bitmask}from"@codescrum/bitmask-set-jsbi"// Given an array that you want to operate onletmyArray=[1,2,3,4,5,6,7,8,9]// We first define the `BitmaskSet` which we will work with.letset=newBitmaskSet(myArray)// Then we define some bitmasks, representing different sets of elements// you pass either their elements, or a strings of 1's and 0'sleta=set.bitmask([1,3,5,7,9])// let a = set.bitmask("101010101")letb=set.bitmask([2,4,6,8])// let b = set.bitmask("010101010")letc=set.bitmask([1,3,5])// let c = set.bitmask("101010000")letd=set.bitmask([6,8])// let d = set.bitmask("000001010")lete=set.bitmask([1,2,3,4,5])// let e = set.bitmask("111110000")letf=set.bitmask([6,7,8,9])// let e = set.bitmask("000001111")letg=set.bitmask([1,9])// let g = set.bitmask("100000001")// For ease of visualization we defined the elements in order when// creating the bitmasks, but you can pass the elements in any order, even// if they include duplicates when creating the bitmasks.//// Note that you must use the `BitmaskSet` instance to create the// bitmasks based on it, or alternatively instantiate them as:letbitmask=newBitmask(set,[1,2,3])// same as set.bitmask([1,3,5])// Print a bitmask's string representationconsole.log("bitmask: "+bitmask)// bitmask: 111000000//// All the following methods return bitmasks// These methods are the most basic ones and can only take other// bitmasks as argumentsa.and(b)// 000000000 bitwise anda.or(b)// 111111111 bitwise ora.xor(e)// 010100101 bitwise xora.invert()// 010101010 (like bitwise not)// These methods can take both bitmasks and elements as arguments// Also, they always return a new bitmask (they don't mutate the bitmask// you call them on.//// Note that some are just the same with different names for// semantics convenience (expressiveness)a.add([1,2,3,4,5])// 111110101 you can add an array of elementsa.add(e)// 111110101 you can add elements from another bitmask tooa.union(e)// 000000101 same as add (added for convenience)a.include(e)// 111110101 same as add (added for convenience)a.remove([1,2,3,4,5])// 000000101 you can remove an array of elementsa.remove(e)// 000000101 you can remove elements from another bitmask tooa.exclude(e)// 000000101 same as remove (added for convenience)a.distinct(e)// 000000101 same as xor (added for convenience)a.unlike(e)// 000000101 same as xor (added for convenience)a.different(e)// 000000101 same as xor (added for convenience)a.intersection(e)// 101010000 return elements in commona.intersect(e)// 101010000 same as intersection (added for convenience)a.is_in(b)// true  - checks if all elements of a are in b.a.is_not_in(b)// false - a.is_not_in(b) == !a.is_in(b)a.is_full()// false - checks if all elements are present (i.e. "111111111")a.is_empty()// false - checks if no elements are present (i.e. "000000000")a.is_zero()// false - same as is_empty (i.e. "000000000")// All bitmask methods are `lazy` in the sense they don't compute any// elements while you perform operations on them.// As long as you are in "bitmask space" you manipulate everything through// bitwise operations.// Once you are ready to get your final items, just call `elements()`a.invert().elements()// [2,4,6,8] (note: this result will be memoized)//// Some more examples// Compare to string representationconsole.log("a == '101010101': ",(a=='101010101'))// true// Equality between bitmasksconsole.log("a.invert().equals(b): ",a.invert().equals(b))// trueconsole.log(`${a}.is_in(${b}): `,a.is_in(b))// falseconsole.log(`${a}.is_in(${c}): `,a.is_in(c))// falseconsole.log(`${c}.is_in(${a}): `,c.is_in(a))// trueconsole.log(`${d}.is_in(${f}): `,d.is_in(f))// trueconsole.log(`${g}.is_in(${a}): `,g.is_in(a))// trueconsole.log(`${g}.is_in(${b}): `,g.is_in(b))// false// Note that you can chain methods since they keep returning// bitmasks, so a given selection of elements can be expressed// as follows:letresult=a// Take all elements from `a`.distinct(b)// mutually excluding those from `b`.and(e)// that are also in `e`.add(f)// then add the ones in `f`.remove(g)// then remove those in `g`.invert()// invert the current selectionconsole.log("result: "+result)// result: 100000001// After manipulations, compute final resulting elements.// Elements get computed when you first call `elements()`// in your resulting bitmask:console.debug(result.elements())// [ 1, 9 ]

How does it work? What does it do?

Development / testing

Debugging

mocha inspect

NODE_INSPECT_RESUME_ON_START=1 mocha inspect

Possible upgrades

Further development

Benchmarking

Alternatives?

License

Contributors