Arduino Community Logo: Arduino.landARDUINO.LANDCODE LIBRARIESBitBool

BitBool library for easy bit access.


BitBool class for C++

This class provides an efficient and easy to use method for dealing with individual bits. The library is in fact a drop-in replacement for a bool or boolean array. However it has many more possibilities and is perfect for use on embedded systems.

The main feature of this library is the fact it allows bits to be read and written using a simple array subscript notation BitBool takes advantage of the C++ lifetime of temporaries and the effects of a design paradigm abbreviated 'Raii', or "Resource acquisition is initialization".


The BitBool library is a template library, and therefore uses a slightly different syntax when declaring an instance These differences involve passing values to a template, rather than the constructor of an object. It may seem daunting, however do not worry, the system is fairly straight forward to use.

The two template parameters used by the library are explained below.

Creating a BitBool

To demonstrate how easy BitBool is to use, consider an array of boolean variables.

bool ledState0[ 8 ] = { true, false, true, false, true, false, true, false };
//Or even
bool ledState1[ 8 ] = { 1, 0, 1, 0, 1, 0, 1, 0 };

Each of the arrays above take up 8 bytes of RAM on an AVR processor. This may not be a problem, but if you ever need thousands of elements, you'll find memory becoming scarce.

BitBool can describe the same arrays in a single byte, or 10,000 elements in 1250 bytes, which is within the usable range of most Arduino boards Even with this immense increase in efficiency, you need to be aware that BitBool will be sized using bytes, so asking for 75 elements will still allocate enough room to store 80 values as the smallest multiple of 8 (bits per byte) that can hold 75 values is 10.

BitBool is a drop in replacement for boolean & bool arrays: its usage for reading and modifying elements is no different to that of an array The only differences are the obvious declaration using a template, and the way an initial set of values can be applied to the entire BitBool Outlined in the example below is a declaration for a BitBool containing 8 bits, and its not initialized to any particular value(s).

BitBool< 8 > ledState;

To achieve initialization equivalent to the bool arrays described above, we need to pack the bit values into bytes. There are a number of ways you can describe the data, its up to you to decide which works best for you.

The GCC compiler allows us to use a number literal prefix for binary numbers. By adding 0b to a string of ones and zeros, the compiler will treat the number as binary.

BitBool< 8 > ledState = { 0b01010101 };

Notice how the bit pattern is reversed compared to a list of true/false data we are used to This is due to bit zero being the rightmost bit in the literal, and the BitBool will index these right to left By setting the second template parameter to true, we can reverse the indexing.

BitBool< 8, true > ledState = { 0b10101010 }; //Reversed the indexing and now bits are indexed left to right. 

Like myself you may think that using a compiler extension isn't the best option; but there is an alternative, the Arduino core defines a set of binary values from 0 to 255 These allow you to specify any combination of 1 to 8 bits, a prefix of B is used for the collection of defines.

BitBool< 8 > bitA = { B00001111 };
BitBool< 8 > bitB = { B1111 };

If you are interested in what these defines are, or would like to use them in your project, you can view the source on the Arduino GitHub page. You can just as easily use hexadecimal, or decimal values if you are comfortable with them.

BitBool< 8 > ledState = { 0x0F };
BitBool< 8 > ledState = { 16 };

As you can see, each initializer is eight bits maximum, to initialize more than eight bits you must break up the BitBool into a list of bytes The examples below set every valid bit to one.

BitBool< 8 > bitA = { B11111111 };
BitBool< 16 > bitB = { B11111111, B11111111 };
BitBool< 17 > bitC = { B11111111, B11111111, B00000001 };
BitBool< 17, true > bitD = { B11111111, B11111111, B10000000 };

If you wish to default the entire BitBool to zero, you can use an empty initialization list.

BitBool< 8 > ledState = {};
BitBool< 8 > ledState = {0};

Comment system coming soon.

Designed & created by Christopher Andrews. 2014