mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
128 lines
4.6 KiB
Markdown
128 lines
4.6 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/SparseArray/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/SparseArray/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/SparseArray/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/SparseArray/releases)
|
|
|
|
|
|
# SparseArray
|
|
|
|
Arduino library for sparse arrays of floats.
|
|
|
|
|
|
## Description
|
|
|
|
SparseArray is an **experimental** library to implement a one
|
|
dimensional sparse array of floats (a.k.a. vector) on an Arduino.
|
|
A sparse array is an array with mostly zeros and a low percentage
|
|
non-zero values.
|
|
The purpose of this library is efficient storage in memory.
|
|
|
|
The maximum array size this library can represent is 65535 elements
|
|
with a theoretical maximum of 65535 non-zero elements.
|
|
(although that does not make sense due to overhead)
|
|
In practice the library limits the number of non-zero elements to 1000.
|
|
|
|
Note: 255 non-zero elements would fit in an UNO's 2K memory.
|
|
|
|
Relates to:
|
|
- https://github.com/RobTillaart/SparseMatrix
|
|
- https://github.com/RobTillaart/distanceTable
|
|
|
|
Note: this library is derived from SparseMatrix.
|
|
|
|
|
|
#### Implementation
|
|
|
|
The implementation is based on 2 arrays holding ```x, value```
|
|
where value is float, and x is an uint16_t.
|
|
That are 6 bytes per element.
|
|
The number of elements that the sparse array object can hold is
|
|
given as parameter to the constructor.
|
|
If the space cannot be allocated the size is set to zero.
|
|
|
|
In the future other data types should be possible.
|
|
|
|
Relates to https://github.com/RobTillaart/SET
|
|
|
|
|
|
#### Performance
|
|
|
|
The elements are not kept sorted or indexed so optimizations might be
|
|
possible but are not investigated yet.
|
|
There is however a test sketch to monitor the performance of
|
|
the most important functions.
|
|
|
|
Accessing elements internally is done with a linear search,
|
|
which becomes (much) slower if the number of elements is increasing.
|
|
This means that although in theory there can be 65535 elements,
|
|
in practice a few 100 can already become annoyingly slow.
|
|
To keep performance a bit the library has a limit build in.
|
|
Check the .h file for **SPARSEARRAY_MAX_SIZE 1000**
|
|
|
|
|
|
## Interface
|
|
|
|
```cpp
|
|
#include "SparseArray.h"
|
|
```
|
|
|
|
### Constructor + meta
|
|
|
|
- **SparseArray(uint16_t size)** constructor.
|
|
Parameter is the maximum number of elements in the sparse array.
|
|
Note this number is limited to **SPARSEARRAY_MAX_SIZE 1000**.
|
|
If the space requested cannot be allocated size will be set to 0.
|
|
- **uint16_t size()** maximum number of elements.
|
|
If this is zero, a problem occurred with allocation happened.
|
|
- **uint16_t count()** current number of elements in the array.
|
|
Should be between 0 and size.
|
|
- **float sum()** sum of all elements ( != 0 ) in the array.
|
|
- **void clear()** resets the array to all zero's again.
|
|
|
|
|
|
### Access
|
|
|
|
- **bool set(uint16_t x, float value)** gives an element in the array a value.
|
|
If the value is set to zero, it is removed from the internal store.
|
|
Returns false if the internal store is full, true otherwise.
|
|
- **float get(uint16_t x)** returns a value from the array.
|
|
- **bool add(uint16_t x, float value)** adds value to an element in the array.
|
|
If needed a new internal element is created.
|
|
If the sum is zero, the element is removed from the internal store.
|
|
Returns false if the internal store is full, true otherwise.
|
|
- **void boundingSegment(uint16_t &minX, uint16_t &maxX)**
|
|
Returns the bounding box in which all values != 0 are located.
|
|
This can be useful for printing or processing the non zero elements.
|
|
|
|
|
|
## Future
|
|
|
|
#### must
|
|
- improve documentation
|
|
|
|
#### should
|
|
- do test
|
|
- investigate optimizations
|
|
- derived sorted class ==> insertSort
|
|
- keep in sync with SparseMatrix where possible
|
|
- merge into one class hierarchy?
|
|
- Template class for the data type
|
|
- better than SparseArray64 SparseArray32 SparseArray16 SparseArray8 (signed / unsigned?)
|
|
|
|
#### could
|
|
- dump should be in the class?
|
|
- or as static function...
|
|
- stream as param dump(Stream str, ...
|
|
|
|
#### ideas
|
|
|
|
- array { uint32_t, float }; for logging millis/micros + measurement
|
|
delta coding of time stamp? if it fit in 16 bit?
|
|
=> sounds like a class on its own.
|
|
- investigate index \[\] operator for **get()** and **set()**
|
|
- would break with sparse matrix
|
|
|
|
|