bits.macro v0.1.0

bits.macro

A set of JavaScript macros for readable bit manipulation of 32bit integers.

So far, this is mostly an idea with a draft implementation. Let me know if you have a use case or other thoughts on it. I would be happy to iterate on this!

Idea and goals

The goal is to enable more readable bitwise transformation of integers. Things like (value & 16384) >> 14 are just not very expressive. This package allows you to write it as GET_BIT_14(value). Sounds like something you would just write a utility function for? You can go that route, however you will need to pass indices as parameters. Reading GET_BIT(7,14) requires you to know the order of parameters in order to determine which one is value and index. It gets worse once you start operating on multiple bits with things like GET_BITS_0_THROUGH_5(value). With a macro, parameters can be read from the function name itself.

Usage

So wait, JavaScript has macros? No, but Babel can support it through babel-macros. Once you have the babel-macros plugin in your Babel configuration, you can simply install and use bits.macro right away:

npm install bits.macro --save-dev

Without additional configuration, simply import the operations you need:

const { GET_BIT_4 } = require('bits.macro')

GET_BIT_4( 16 ) // 1

API

All macros only work for 32 bit integers since bitwise operators only work on those in JavaScript. Bit positions are zero-indexed starting from least significant bit (LSB) to most significant bit (MSB). Or in other words, if you write out the hexadecimal representation in binary they are enumarted right to left. The value 6 has the bits at position 1 and 2 set to one for example. Therefore all position parameters X and Y must be in the range 0,1,...,31 in order to get a meaningful result.

GET_BIT_X(value)

Returns one or zero, depending on the bit at position X in value.

SET_BITS_X_THROUGH_Y(value)

Sets all bits from position X to Y to 1 in value (including Y). Currently this assumes X <= Y.

SET_BIT_IF(index, condition, value)

Sets the bit at position index in value to 1 if condition is truthy.

SET_BIT(index, value)

Sets the bit at position index in value to 1.

SET_BIT_X_IF(condition, value)

Sets the bit at position X in value to 1 if condition is truthy.

SET_BIT_X(value)

Sets the bit at position X in value.