mirror of
https://github.com/RobTillaart/Arduino.git
synced 2024-10-03 18:09:02 -04:00
150 lines
6.0 KiB
Markdown
150 lines
6.0 KiB
Markdown
|
|
[](https://github.com/marketplace/actions/arduino_ci)
|
|
[](https://github.com/RobTillaart/TOPMIN/actions/workflows/arduino-lint.yml)
|
|
[](https://github.com/RobTillaart/TOPMIN/actions/workflows/jsoncheck.yml)
|
|
[](https://github.com/RobTillaart/TOPMIN/issues)
|
|
|
|
[](https://github.com/RobTillaart/TOPMIN/blob/master/LICENSE)
|
|
[](https://github.com/RobTillaart/TOPMIN/releases)
|
|
[](https://registry.platformio.org/libraries/robtillaart/TOPMIN)
|
|
|
|
|
|
# TOPMIN
|
|
|
|
Arduino library to track the top N minima.
|
|
|
|
## Description
|
|
|
|
This experimental library tracks the top N minima of a series of values.
|
|
|
|
The library implements two classes:
|
|
- **TOPMIN** just tracks the values. (smaller footprint).
|
|
- **TOPMINext** also tracks a user defined 32-bit tag (e.g. timestamp).
|
|
|
|
The latter is more useful as it allows to link the top N values to a certain time
|
|
or day, an index in a database, or another indirect reference.
|
|
It can even be used to store a second parameter e.g. what was the humidity for
|
|
the top N temperatures.
|
|
|
|
The library can be used for different applications:
|
|
- track top N minima temperature / humidity over a given period of time.
|
|
- track top N UV minima intensity during the day.
|
|
- track top N trading volumes or $$.
|
|
- track top N smallest fish caught in a contest.
|
|
- track top N minimum number of visitors during a day.
|
|
|
|
The 32 bit tag, can be filled with a 32 bit number like a timestamp, bit can also
|
|
be used more creatively e.g. 2x 16 bit numbers or even 32 booleans.
|
|
Any mapping is possible (but not part of the library).
|
|
|
|
|
|
#### 0.2.0 breaking change
|
|
|
|
Since version 0.2.0 the minima is found with **getValue(index == 0)**.
|
|
In earlier versions the minima was found with **index == count()**.
|
|
|
|
The advantage of this change is that independent of the size of the TOPMIN
|
|
object the true minima will always at index == 0. So if you change your code
|
|
and the size of the TOPMIN object, far less code needs to be changed.
|
|
It also allows to have two or more TOPMIN objects of different size and use one
|
|
index to access both.
|
|
|
|
|
|
#### Related
|
|
|
|
- https://github.com/RobTillaart/TOPMAX
|
|
- https://github.com/RobTillaart/TOPMIN
|
|
- https://github.com/RobTillaart/runningAverage
|
|
- https://github.com/RobTillaart/MINMAX
|
|
|
|
|
|
## Interface
|
|
|
|
```cpp
|
|
#include "TOPMIN.h"
|
|
```
|
|
|
|
#### TOPMIN
|
|
|
|
- **TOPMIN(uint8_t size = 5)** Constructor, defines the number of elements it can hold.
|
|
Default number of elements is 5. If **size** < 3 it will be set to 3.
|
|
The maximum size is currently 255, or less if there is not enough memory.
|
|
- **uint8_t count()** returns the number of elements in the internal array. 0.. size.
|
|
- **uint8_t size()** returns the maximum number of elements in the internal array.
|
|
- **void reset()** reset the internal counter to 0, logical clearing of the system.
|
|
- **bool add(float value)** add a value to the TOPMIN object if it is in the top N of minima.
|
|
If so the largest element is removed.
|
|
Returns false if not added or if there was an allocation error.
|
|
- **float getValue(uint8_t index)** get an element of the internal array.
|
|
The index must be <= **count()**, if not the function currently returns **NaN**.
|
|
This may or may not be a valid value, so the user should guard the **index** parameter carefully.
|
|
- **bool fill(float value)** convenience function to fill the internal array
|
|
with a single value e.g. 0. Returns true on success.
|
|
|
|
|
|
#### TOPMINext
|
|
|
|
Derived from TOPMIN, extended with a tag field.
|
|
|
|
- **TOPMINext(uint8_t size = 5)** Constructor, defines the number of elements it can hold.
|
|
Default number of elements is 5. If **size** < 3 it will be set to 3.
|
|
The maximum size is currently 255, or less if there is not enough memory.
|
|
- **bool add(float value, uint32_t tag)** add a value to the TOPMINext object to check if
|
|
it needs to be in the top N of minima. If so add the 32-bit **tag** too (at same index).
|
|
The 32-bit **tag** is typical an index, counter or timestamp, but any semantic is possible.
|
|
- **uint32_t getTag(uint8_t index)** get the tag from an element of the internal array.
|
|
The index must be <= **count()**, if not the function currently returns **0xFFFFFFFF**.
|
|
This may or may not be a valid value, so the user should guard the **index** parameter carefully.
|
|
- **bool fill(float value, uint32_t tag)** convenience function to fill the internal array
|
|
with a single value e.g. 0. (tag idem).
|
|
|
|
|
|
# Future
|
|
|
|
#### Must
|
|
|
|
- improve documentation.
|
|
- keep TOPMIN and TOPMAX functional in sync.
|
|
|
|
#### Should
|
|
|
|
- add unit tests.
|
|
- for extended version if possible.
|
|
|
|
#### Could
|
|
|
|
- add more examples.
|
|
- example creative use of tag field.
|
|
- add error handling
|
|
- TOP_ERR_ALLOCATION
|
|
- TOP_ERR_INDEX
|
|
- TOP_NOT_ADDED
|
|
- TOP_OK
|
|
- int error; **int lastError()**
|
|
- create template class.
|
|
- **bool check(float value)** and **bool check(float value, uint32_t tag)**
|
|
- if (value < getValue(0)) or so.
|
|
- **inRange(value)**
|
|
- checks if this value would be added to the TOP-N
|
|
- **TOP** class, in which the condition can be set as parameter.
|
|
- a function() returning true or false when comparing 2 values.
|
|
- **bool hasValue(float value)** and **bool hasTag(uint32_t tag)**
|
|
- or **int getIndex(...)** duplicates?
|
|
|
|
#### Wont
|
|
|
|
- how to handle double/triple etc. entries with same value
|
|
- they are handled as unique elements, that is what I had in mind.
|
|
- optimize loops in **fill()** (maybe upon request)
|
|
- pointer math
|
|
|
|
|
|
## 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,
|
|
|