2021-01-29 06:31:58 -05:00
|
|
|
|
|
|
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
2021-10-19 10:11:27 -04:00
|
|
|
[](https://github.com/RobTillaart/BitArray/actions/workflows/arduino-lint.yml)
|
|
|
|
|
[](https://github.com/RobTillaart/BitArray/actions/workflows/jsoncheck.yml)
|
2023-10-18 10:24:20 -04:00
|
|
|
[](https://github.com/RobTillaart/BitArray/issues)
|
|
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
[](https://github.com/RobTillaart/BitArray/blob/master/LICENSE)
|
|
|
|
|
[](https://github.com/RobTillaart/BitArray/releases)
|
2023-10-18 10:24:20 -04:00
|
|
|
[](https://registry.platformio.org/libraries/robtillaart/BitArray)
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2021-10-19 10:11:27 -04:00
|
|
|
|
2020-11-27 05:10:47 -05:00
|
|
|
# BitArray
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2021-12-14 05:17:14 -05:00
|
|
|
Arduino library for compact array of objects with a size expressed in bits, typically 1..10.
|
2020-11-27 05:10:47 -05:00
|
|
|
|
2021-10-19 10:11:27 -04:00
|
|
|
|
2020-11-27 05:10:47 -05:00
|
|
|
## Description
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2020-11-27 05:10:47 -05:00
|
|
|
The BitArray class allows the user to instantiate an array of elements, each of the same size in bits.
|
|
|
|
|
For example one could create an array of 100 throws with a dice. Normally this would take 100 bytes,
|
|
|
|
|
but BitArray can store one throw in 3 bits, so 100 throws in approx 40 bytes.
|
2021-12-14 05:17:14 -05:00
|
|
|
Another example is to store multiple 10 bit analogRead() values efficiently.
|
2020-11-27 05:10:47 -05:00
|
|
|
|
|
|
|
|
The class is optimized for storage and takes care of efficiently packing the elements
|
|
|
|
|
into multiple bytes, and byte borders. Depending where an element is located writing and reading
|
|
|
|
|
can take more time. You need to check if your application needs more performance than
|
|
|
|
|
this library can deliver.
|
|
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
#### Related
|
|
|
|
|
|
2020-11-27 05:10:47 -05:00
|
|
|
The BitArray library is one from a set of three:
|
2021-12-14 05:17:14 -05:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
- 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).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### Notes
|
|
|
|
|
|
|
|
|
|
The BitArray class allocates dynamic memory, so called BA_SEGMENTS,
|
|
|
|
|
each of 200 bytes.
|
|
|
|
|
As the memory size of different processors differ the maximum amount of SEGMENTS
|
|
|
|
|
depends on architecture.
|
|
|
|
|
|
|
|
|
|
The library is tested on AVR architecture only.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## Interface
|
|
|
|
|
|
|
|
|
|
```cpp
|
|
|
|
|
#include "BitArray.h"
|
2020-11-27 05:10:47 -05:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
```
|
2020-11-27 05:10:47 -05:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
#### Constructor
|
2021-10-19 10:11:27 -04:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
- **BitArray()** Constructor
|
|
|
|
|
- **~BitArray()** Destructor, frees dynamic memory
|
|
|
|
|
- **uint8_t begin(const uint8_t bits, const uint16_t size)** Frees memory used and allocates the memory requested.
|
|
|
|
|
The maximum number of elements is 65535 if memory allows,
|
2020-11-27 05:10:47 -05:00
|
|
|
the maximum element size is 32.
|
|
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
Better names could be **bits == elementSize** and **size == elementCount**.
|
2021-10-19 10:11:27 -04:00
|
|
|
|
2020-11-27 05:10:47 -05:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
#### Admin
|
2020-11-27 05:10:47 -05:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
- **uint16_t capacity()** idem.
|
|
|
|
|
- **uint16_t memory()** idem.
|
|
|
|
|
- **uint16_t bits()** idem.
|
|
|
|
|
- **uint16_t segments()** idem.
|
|
|
|
|
- **uint8_t getError()** idem.
|
2021-10-19 10:11:27 -04:00
|
|
|
|
2021-01-29 06:31:58 -05:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
#### base functions
|
2020-11-27 05:10:47 -05:00
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
- **void clear()** sets all elements to 0.
|
|
|
|
|
- **uint32_t get(const uint16_t index)** gets the value of the element at index.
|
|
|
|
|
- **uint32_t set(const uint16_t index, uint32_t value)** sets index to value.
|
|
|
|
|
Overwrites existing value.
|
|
|
|
|
Returns value.
|
|
|
|
|
- **void setAll(uint32_t value)** sets whole array to value.
|
|
|
|
|
- **uint32_t toggle(const uint16_t index)** toggles value at index.
|
|
|
|
|
Return value is maxValue (debug info).
|
2020-11-27 05:10:47 -05:00
|
|
|
|
2021-10-19 10:11:27 -04:00
|
|
|
|
|
|
|
|
## Future
|
|
|
|
|
|
2023-02-08 08:03:23 -05:00
|
|
|
#### Must
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### Should
|
|
|
|
|
|
2021-12-14 05:17:14 -05:00
|
|
|
- testing.
|
2023-02-08 08:03:23 -05:00
|
|
|
- is returning value in **set()** needed? (0.3.0)
|
|
|
|
|
- as value is a parameter **void** seems good enough.
|
|
|
|
|
- return value **toggle()** could be new value? (0.3.0)
|
|
|
|
|
- code prep is working (commented for now)
|
|
|
|
|
- naming parameters ** begin()** (0.3.0)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### Could
|
|
|
|
|
|
2021-12-14 05:17:14 -05:00
|
|
|
- functional examples.
|
2021-10-19 10:11:27 -04:00
|
|
|
- investigate element size of 64 (for doubles) and beyond.
|
2023-02-08 08:03:23 -05:00
|
|
|
- move code to .cpp (0.3.0)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### Wont
|
2022-10-29 09:54:56 -04:00
|
|
|
|
2021-10-19 10:11:27 -04:00
|
|
|
|
2023-10-18 10:24:20 -04:00
|
|
|
## Support
|
|
|
|
|
|
|
|
|
|
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,
|
|
|
|
|
|
|
|
|
|
|
