0.1.1 TOPMAX

libraries/TOPMAX/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.1.1] - 2023-05-20
+- add **TOPMAXext**, holds a value + tag (e.g. timestamp or counter)
+- add examples.
+- changed **get()** into **getValue()**
+- update readme.md
+- minor edits.
+
+
 ## [0.1.0] - 2023-05-18
 - initial version
 

libraries/TOPMAX/README.md

@@ -13,8 +13,27 @@ Arduino library to track the top N maxima.
 ## Description
 
 This experimental library tracks the top N maxima of a series of values. 
-It can be used e.g. to track the top 5 peak temperatures over a given 
-period of time.
+
+The library implements two classes:
+- **TOPMAX** just tracks the values. (smaller footprint).
+- **TOPMAXext** 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 peak temperature / humidity over a given period of time.
+- track top N UV peak intensity during the day.
+- track top N trading volumes or $$.
+- track top N largest fish caught in a contest.
+- track top N number of visitors during a day.
+- track top N of time-outs, e.g. to monitor production loss. 
+
+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).
 
 
 #### Links
@@ -31,38 +50,57 @@ period of time.
 #include "TOPMAX.h"
 ```
 
+#### TOPMAX
+
 - **TOPMAX(uint8_t size = 5)** Constructor, defines the number of elements it can hold.
-Default number of elements is 5. If size < 3 it becomes 3.
-- **uint8_t count()** returns the number of elements in the internal array.
+Default number of elements is 5. If **size** < 3 it will be set to 3.
+The maximum size is currently 255.
+- **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, clearing the system.
-- **bool add(float value)** add a value to the TOPMAX object to check it needs to be in the top N of maxima.
-- **float get(uint8_t index)** get an element of the internal array.
-index == count().
+- **void reset()** reset the internal counter to 0, logical clearing of the system.
+- **bool add(float value)** add a value to the TOPMAX object to check of it needs to be 
+in the top N of maxima.
+- **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.
 
 
+#### TOPMAXext
+
+Derived from TOPMAX, extended with a tag field.
+
+- **TOPMAXext(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.
+- **bool add(float value, uint32_t tag)** add a value to the TOPMAXext object to check if
+it needs to be in the top N of maxima. 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
 
-- keep functional in sync with TOPMIN
+- keep functional in sync with TOPMIN.
 - improve documentation.
 
-
 #### Should
 
 - add unit tests.
 - add more examples.
-
+- add performance measurements.
+  - depends on size / and inserted values.
 
 #### Could
 
-- create template class
-- create derived class that holds an index or timestamp
-  - uint32_t extra per element.
-
+- create template class.
 
 #### Wont
 

libraries/TOPMAX/TOPMAX.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: TOPMAX.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //    DATE: 2023-05-18
 // PURPOSE: Arduino library to track top n maxima.
 //     URL: https://github.com/RobTillaart/TOPMAX
@@ -77,12 +77,12 @@ bool TOPMAX::add(float value)
     _arr[i - 1] = _arr[i];
     i++;
   }
-  _arr[i-1] = value;
+  _arr[i - 1] = value;
   return true;
 }
 
 
-float TOPMAX::get(uint8_t index)
+float TOPMAX::getValue(uint8_t index)
 {
   if (index > _count) return NAN;
   return _arr[index];
@@ -99,5 +99,84 @@ void TOPMAX::fill(float value)
 }
 
 
+////////////////////////////////////////////////////
+//
+//  DERIVED
+//
+TOPMAXext::TOPMAXext(uint8_t size) : TOPMAX(size)
+{
+  _tag = (uint32_t *) malloc(_size * sizeof(uint32_t));
+}
+
+
+TOPMAXext::~TOPMAXext()
+{
+  if (_tag) free(_tag);
+}
+  
+  
+bool TOPMAXext::add(float value, uint32_t tag)
+{
+  //  initial
+  if (_count == 0)
+  {
+    _arr[_count] = value;
+    _tag[_count] = tag;
+    _count++;
+    return true;
+  }
+
+  //  not all elements filled.
+  if (_count < _size)
+  {
+    int i = _count - 1;
+    while ((i >= 0) && (value < _arr[i]))
+    {
+      _arr[i + 1] = _arr[i];
+      _tag[i + 1] = _tag[i];
+      i--;
+    }
+    _arr[i + 1] = value;
+    _tag[i + 1] = tag;
+    _count++;
+    return true;
+  }
+
+  //  too small (or equal)
+  if (value <= _arr[0]) return false;
+
+  //  insert
+  int i = 1;
+  while ((i < _size) && (value > _arr[i]))
+  {
+    _arr[i - 1] = _arr[i];
+    _tag[i - 1] = _tag[i];
+    i++;
+  }
+  _arr[i - 1] = value;
+  _tag[i - 1] = tag;
+  return true;
+  
+}
+
+
+uint32_t TOPMAXext::getTag(uint8_t index)
+{
+  if (index > _count) return 0xFFFFFFFF;
+  return _tag[index];
+}
+
+
+void TOPMAXext::fill(float value, uint32_t tag)
+{
+  for (int i = 0; i < _size; i++)
+  {
+    _arr[i] = value;
+    _tag[i] = tag;
+  }
+  _count = _size;
+}
+
+
 //  -- END OF FILE --
 

libraries/TOPMAX/TOPMAX.h

@@ -2,13 +2,13 @@
 //
 //    FILE: TOPMAX.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //    DATE: 2023-05-18
 // PURPOSE: Arduino library to track top n maxima.
 //     URL: https://github.com/RobTillaart/TOPMAX
 
 
-#define TOPMAX_LIB_VERSION             (F("0.1.0"))
+#define TOPMAX_LIB_VERSION             (F("0.1.1"))
 
 
 #include "Arduino.h"
@@ -23,17 +23,36 @@ public:
   uint8_t count();
   uint8_t size();
   void    reset();
-  bool    add(float value);
-  float   get(uint8_t index);
-  void    fill(float value);
+  virtual bool add(float value);
+  virtual void fill(float value);
+  float   getValue(uint8_t index);
 
 
-private:
+protected:
   uint8_t _size;
   uint8_t _count;
   float * _arr;
 };
 
 
+////////////////////////////////////////////////////
+//
+//  DERIVED
+//
+class TOPMAXext : public TOPMAX
+{
+public:
+  TOPMAXext(uint8_t size = 5);
+  ~TOPMAXext();
+  
+  bool     add(float value, uint32_t tag);
+  uint32_t getTag(uint8_t index);
+  void     fill(float value, uint32_t tag);
+
+private:
+  uint32_t * _tag;
+};
+
+
 //  -- END OF FILE --
 

libraries/TOPMAX/examples/TOPMAX_demo/TOPMAX_demo.ino

@@ -35,7 +35,7 @@ void loop()
   Serial.print("\t");
   for (int i = 0; i < tm.count(); i++)
   {
-    Serial.print(tm.get(i));
+    Serial.print(tm.getValue(i));
     Serial.print("\t");
   }
   Serial.println();

libraries/TOPMAX/examples/TOPMAXext_count/TOPMAXext_count.ino

@@ -0,0 +1,51 @@
+//
+//    FILE: TOPMAXext_count.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: TOPMAX demo
+//     URL: https://github.com/RobTillaart/TOPMAX
+
+
+#include "TOPMAX.h"
+
+
+TOPMAXext tme(5);
+uint32_t cnt = 0;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("TOPMAX_LIB_VERSION: ");
+  Serial.println(TOPMAX_LIB_VERSION);
+  Serial.println();
+
+  tme.fill(0, 0);
+  tme.reset();
+}
+
+
+void loop()
+{
+  int x = random(10000);
+
+  Serial.print(cnt++);
+  Serial.print("\t");
+  Serial.print(x);
+  Serial.print("\t");
+  for (int i = 0; i < tme.count(); i++)
+  {
+    Serial.print(tme.getValue(i));
+    Serial.print(":(");
+    Serial.print(tme.getTag(i));
+    Serial.print(")\t");
+  }
+  Serial.println();
+
+  tme.add(x, cnt);  //  tag the maxima with the "sample counter".
+
+  delay(random(200));
+}
+
+
+//  -- END OF FILE --

libraries/TOPMAX/examples/TOPMAXext_millis/TOPMAXext_millis.ino

@@ -0,0 +1,51 @@
+//
+//    FILE: TOPMAXext_millis.ino
+//  AUTHOR: Rob Tillaart
+// PURPOSE: TOPMAX demo
+//     URL: https://github.com/RobTillaart/TOPMAX
+
+
+#include "TOPMAX.h"
+
+
+TOPMAXext tme(5);
+uint32_t cnt = 0;
+
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println(__FILE__);
+  Serial.print("TOPMAX_LIB_VERSION: ");
+  Serial.println(TOPMAX_LIB_VERSION);
+  Serial.println();
+
+  tme.fill(0, 0);
+  tme.reset();
+}
+
+
+void loop()
+{
+  int x = random(10000);
+
+  Serial.print(cnt++);
+  Serial.print("\t");
+  Serial.print(x);
+  Serial.print("\t");
+  for (int i = 0; i < tme.count(); i++)
+  {
+    Serial.print(tme.getValue(i));
+    Serial.print(":(");
+    Serial.print(tme.getTag(i));
+    Serial.print(")\t");
+  }
+  Serial.println();
+
+  tme.add(x, millis());
+
+  delay(random(200));
+}
+
+
+//  -- END OF FILE --

libraries/TOPMAX/keywords.txt

@@ -3,16 +3,20 @@
 
 # Data types (KEYWORD1)
 TOPMAX	KEYWORD1
+TOPMAXext	KEYWORD1
 
 
 # Methods and Functions (KEYWORD2)
 count	KEYWORD2
 size	KEYWORD2
 reset	KEYWORD2
+
 add	KEYWORD2
-get	KEYWORD2
 fill	KEYWORD2
 
+getValue	KEYWORD2
+getTag	KEYWORD2
+
 
 # Constants (LITERAL1)
 TOPMAX_LIB_VERSION	LITERAL1

libraries/TOPMAX/library.json

@@ -15,7 +15,7 @@
     "type": "git",
     "url": "https://github.com/RobTillaart/TOPMAX"
   },
-  "version": "0.1.0",
+  "version": "0.1.1",
   "license": "MIT",
   "frameworks": "arduino",
   "platforms": "*",

libraries/TOPMAX/library.properties

@@ -1,5 +1,5 @@
 name=TOPMAX
-version=0.1.0
+version=0.1.1
 author=Rob Tillaart <rob.tillaart@gmail.com>
 maintainer=Rob Tillaart <rob.tillaart@gmail.com>
 sentence=Arduino library to track top n maxima.

libraries/TOPMAX/test/unit_test_001.cpp

@@ -84,12 +84,12 @@ unittest(test_get)
   {
     tm.add(i);
     int idx = tm.count();
-    assertEqualFloat(i, tm.get(idx - 1), 0.001);
+    assertEqualFloat(i, tm.getValue(idx - 1), 0.001);
   }
 
   for (int i = 0; i < tm.count(); i++)
   {
-    fprintf(stderr, "%f\t", tm.get(i));
+    fprintf(stderr, "%f\t", tm.getValue(i));
   }
 
   fprintf(stderr, "\n");