Arduino library for compact array of booleans of max size 2000 (UNO).
The BoolArray class allows the user to instantiate an array of booleans, allocating only one bit per element. For example one could create an array of 1000 throws with a coin. Normally this would take 1000 bytes, but BoolArray can store one throw in 1 bit, so 1000 throws in approx 125 bytes.
The class is optimized for storage by packing 8 elements of the array in one byte. You need to check if your application needs more performance than this library can deliver.
The BoolArray class allocates dynamic memory. The BOOLARRAY_MAXSIZE is set to 10000 (booleans). This number is chosen as it is about the maximum one can allocate in one call on an UNO.
If one want to allocate more booleans, adjust the BOOLARRAY_MAXSIZE. This can be done as a command line option.
The library is tested on AVR architecture only.
Since 0.3.0 a BoolArray32 class is added - experimental for now.
Where the BoolArray class can have max 65535 booleans, the BoolArray32 class has a 32 bit interface allowing up to 4 billion++ booleans in theory. Although most IOT devices would not have enough memory, it allows one to have more than 65535 booleans.
Also it might be that the BoolArray32 class is faster on some platforms that are native 32 bit (not verified yet). On an Arduino UNO the BoolArray32 class is slower.(verified).
The BitArray library is one from a set of three:
- https://github.com/RobTillaart/BitArray for elements of user defined size in bits (values 0 .. 2^n-1).
- https://github.com/RobTillaart/BoolArray for elements of 1 bit (values 0 .. 1).
- https://github.com/RobTillaart/nibbleArray for elements of 4 bits or smaller (values 0 .. 15).
BoolArray is faster than BitArray as it only supports single bits and does not need to merge parts of different bytes to read/write a value. However BoolArray currently only supports 2000 bits while BitArray can support more.
See boolArrayDemo0.ino
Indicative performance figures.
| class | function | UNO | ESP32 | Notes |
|---|---|---|---|---|
| BoolArray | set(0) | 10.37 | ||
| BoolArray | set(1) | 10.25 | ||
| BoolArray | get(i) | 16.03 | ||
| BoolArray | setAll(0) | 96 | per 2000 | |
| BoolArray | setAll(1) | 100 | per 2000 | |
| BoolArray32 | set(0) | 15.97 | ||
| BoolArray32 | set(1) | 15.84 | ||
| BoolArray32 | get(i) | 24.20 | ||
| BoolArray32 | setAll(0) | 148 | per 2000 | |
| BoolArray32 | setAll(1) | 144 | per 2000 |
- UNO 16 MHz, ESP32 240 MHz.
- toggle() is expected to be similar to set()
- clear() is a wrapper around setAll(0) so similar.
#include "BoolArray.h"- BoolArray() Constructor
- ~BoolArray() Destructor
- uint8_t begin(uint32_t size) dynamically allocates size elements (8 booleans in one byte). Returns BOOLARRAY_OK on success.
- uint16_t size() returns number of boolean elements.
- uint16_t memory() returns number of bytes used.
The following functions return BOOLARRAY_OK on success.
- uint8_t setAll(uint8_t value) Sets all elements to false (0) or true (all other values).
- uint8_t clear() Sets all elements to false.
- uint8_t get(uint16_t index) Return 0 or 1 OR an error value which can be interpreted as true. So one need to check these carefully.
- uint8_t set(uint16_t index, uint8_t value) Set the element to false (0) or true (all other values).
- uint8_t toggle(uint16_t index) Toggles element at index.
- improve documentation
- add performance figures (UNO + ESP32)
- performance test on ESP32
- performance for clear() dedicated loop vs setAll(0) call
- investigate template class
- improve allocation (see PrintCharArray)
- update examples.
- investigate uint32_t array[N] for BoolArray32 (ESP32?)
- adjust math
- performance intern 16 bit instead of 8 bit is NOT faster on UNO
If you appreciate my libraries, you can support the development and maintenance. Improve the quality of the libraries by providing issues and Pull Requests, or donate through PayPal or GitHub sponsors.
Thank you,