Fix #30 #31, add getSum() and getStandardDeviationLast(count) (#32)

- Fix #30, add **float getSum()** (thanks to heidnerd)
- Fix #31, add **float getStandardDeviationLast(uint16_t count)** (thanks to alvaro-oliver)
- added code to detect inner array == NULL in more functions (return NAN).
  - changed return type **bool clear()**
  - changed return type **bool addValue(..)**
  - changed return type **bool fillValue(..)**
  - changed return type **bool setPartial(..)**
- moved performance.txt to performance sketch
- update unit test
- update keywords.txt
- update readme.md
- minor edits.

Author: RobTillaart

CHANGELOG.md

@@ -6,11 +6,24 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.6] - 2024-06-15
+- Fix #30, add **float getSum()** (thanks to heidnerd)
+- Fix #31, add **float getStandardDeviationLast(uint16_t count)** (thanks to alvaro-oliver)
+- added code to detect inner array == NULL in more functions (return NAN).
+  - changed return type **bool clear()**
+  - changed return type **bool addValue(..)**
+  - changed return type **bool fillValue(..)**
+  - changed return type **bool setPartial(..)**
+- moved performance.txt to performance sketch
+- update unit test
+- update keywords.txt
+- update readme.md
+- minor edits.
+
 ## [0.4.5] - 2024-01-05
 - fix URL in examples
 - minor edits
 
-
 ## [0.4.4] - 2023-10-18
 - update readme.md badges
 - update examples
@@ -29,7 +42,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - minor edits
 
 ## [0.4.1] - 2021-11-22
-- updated buil-CI, readme, badges
+- updated build-CI, readme, badges
 - add getAverageLast() functions.
 
 ## [0.4.0] - 2021-05-18
@@ -57,7 +70,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [0.2.15] - 2020-01-17
 - fix overflow in getValue - see issue #139
 
-
 ## [0.2.14] - 2020-01-15
 - added getValue(n) to retrieve elements in order of addition - see issue #132
 
@@ -107,7 +119,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [0.2.01] - 2012-11-21
 - refactored
 
-## [0.2.00] - 2012-??-??  
+## [0.2.00] - 2012-??-??
 - Yuval Naveh added trimValue (found on web)
 - http://stromputer.googlecode.com/svn-history/r74/trunk/Arduino/Libraries/RunningAverage/RunningAverage.cpp
 

README.md

@@ -58,12 +58,19 @@ No default size (yet).
 
 ### Basic
 
-- **void clear()** empties the internal buffer.
-- **void add(float value)** wrapper for **addValue()**
-- **void addValue(float value)** adds a new value to the object, if the internal buffer is full, 
+The following functions return **false** if the internal buffer is not allocated.
+
+- **bool clear()** empties the internal buffer.
+- **bool add(float value)** wrapper for **addValue()**.
+- **bool addValue(float value)** adds a new value to the object, if the internal buffer is full, 
 the oldest element is removed.
-- **void fillValue(float value, uint16_t number)**  adds number elements of value. 
+- **bool fillValue(float value, uint16_t number)**  adds number elements of value. 
 Good for initializing the system to a certain starting average.
+
+
+The following functions returns NAN if there are no values present (count == 0) or 
+of internal array is not allocated.
+
 - **float getValue(uint16_t position)** returns the value at **position** from the additions. 
 Position 0 is the first one to disappear.
 - **float getAverage()** iterates over all elements to get the average, slower but accurate. 
@@ -80,6 +87,7 @@ Needs more than one element to be calculable.
 - **float getMax()** returns maximum since last clear, does not need to be in the buffer any more.
 - **float getMinInBuffer()** returns minimum in the internal buffer.
 - **float getMaxInBuffer()** returns maximum in the internal buffer.
+- **float getSum()** returns sum of values in the internal buffer.
 
 
 ### Admin functions
@@ -92,9 +100,10 @@ Needs more than one element to be calculable.
 
 ## Partial functions
 
-- **void setPartial(uint16_t partial = 0)** use only a part of the internal array. 
+- **bool setPartial(uint16_t partial = 0)** use only a part of the internal array. 
 Allows to change the weight and history factor. 
 0 ==> use all == default.
+Returns false if internal buffer is not allocated.
 - **uint16_t getPartial()** returns the set value for partial.
 
 
@@ -122,15 +131,41 @@ parameter, the functions will return the statistics of the whole buffer.
 
 - **float getAverageSubset(uint16_t start, uint16_t count)** 
 Get the average of subset - count elements from start.
+Returns NAN if no elements or internal array not allocated.
+
+
+## Performance
+
+Indicative performance on an UNO, see examples.
+
+|  Function              |  0.4.5 us  |  0.4.6 us  |  Notes  |
+|:----------------------:|:----------:|:----------:|:-------:|
+|  clear                 |      60    |      60    |
+|  addValue              |      24    |      24    |
+|  fillValue             |    1512    |    1520    |
+|  getValue              |       4    |       8    |
+|  getAverage            |     520    |     552    |
+|  getFastAverage        |      36    |      40    |
+|  getStandardDeviation  |    1856    |    1856    |
+|  getStandardError      |    1920    |    1920    |
+|  getMin                |       8    |       4    |
+|  getMax                |       4    |       4    |
+|  getMinInBuffer        |     216    |     212    |
+|  getMaxInBuffer        |     208    |     208    |
+|  getSum                |       -    |       8    |
+|  bufferIsFull          |       8    |       8    |
+|  getElement            |       4    |       4    |
+|  getSize               |       8    |       8    |
+|  getCount              |       8    |       8    |
+|  last functions        |       -    |       -    |  not tested
 
 
 ## Operation
 
 See examples
 
 
-## Future 
-
+## Future
 
 #### Must
 
@@ -139,16 +174,22 @@ See examples
 #### Should
 
 - check for optimizations.
-  - divide by count happens often ...
-- clear(bool zero = true) to suppress setting all to 0. ?
-
+  - divide by count happens often
+  - fillValue can be optimized (See #13)
+- ```temp = sqrt(temp/(_count - 1));```  is this correct STDDEV?
+  - divide by count or count - 1?  
+  - https://www.zaner.com/3.0/education/technicalstudies/MSD.asp
+  
 #### Could
 
-- create a double based derived class? Template class?
+- create a double based derived class? 
+  - Template class?
 - add error handling (important?).
 - investigate **modus()** most frequently occurring value.
   - difficult with floats ?
-  - what to do when on two or more values are on par?
+  - what to do when on two or more values are on par? (no modus?)
+- **int getUniqueValuesInBuffer()** O(n^2)
+
 
 #### Wont
 

RunningAverage.cpp

@@ -1,7 +1,7 @@
 //
 //    FILE: RunningAverage.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.5
+// VERSION: 0.4.6
 //    DATE: 2011-01-30
 // PURPOSE: Arduino library to calculate the running average by means of a circular buffer
 //     URL: https://github.com/RobTillaart/RunningAverage
@@ -30,26 +30,31 @@ RunningAverage::~RunningAverage()
 
 
 //  resets all counters
-void RunningAverage::clear()
+bool RunningAverage::clear()
 {
   _count = 0;
   _index = 0;
   _sum = 0.0;
   _min = NAN;
   _max = NAN;
+  if (_array == NULL)
+  {
+    return false;
+  }
   for (uint16_t i = _size; i > 0; )
   {
     _array[--i] = 0.0;  //  keeps addValue simpler
   }
+  return true;
 }
 
 
 //  adds a new value to the data-set
-void RunningAverage::addValue(const float value)
+bool RunningAverage::addValue(const float value)
 {
   if (_array == NULL)
   {
-    return;
+    return false;
   }
 
   _sum -= _array[_index];
@@ -66,13 +71,15 @@ void RunningAverage::addValue(const float value)
 
   //  update count as last otherwise if ( _count == 0) above will fail
   if (_count < _partial) _count++;
+  return true;
 }
 
 
-//  returns the average of the data-set added so far, NAN if no elements.
+//  returns the average of the data-set added so far, 
+//  returns NAN if no elements or missing array
 float RunningAverage::getAverage()
 {
-  if (_count == 0)
+  if ((_count == 0) || (_array == NULL))
   {
     return NAN;
   }
@@ -94,15 +101,14 @@ float RunningAverage::getFastAverage() const
   {
     return NAN;
   }
-
   return _sum / _count;   //  multiplication is faster ==> extra admin
 }
 
 
 //  returns the minimum value in the buffer
 float RunningAverage::getMinInBuffer() const
 {
-  if (_count == 0)
+  if ((_count == 0) || (_array == NULL))
   {
     return NAN;
   }
@@ -119,7 +125,7 @@ float RunningAverage::getMinInBuffer() const
 //  returns the maximum value in the buffer
 float RunningAverage::getMaxInBuffer() const
 {
-  if (_count == 0)
+  if ((_count == 0) || (_array == NULL))
   {
     return NAN;
   }
@@ -136,11 +142,10 @@ float RunningAverage::getMaxInBuffer() const
 //  returns the value of an element if exist, NAN otherwise
 float RunningAverage::getElement(uint16_t index) const
 {
-  if (_count == 0)
+  if ((_count == 0) || (_array == NULL))
   {
     return NAN;
   }
-
   return _array[index];
 }
 
@@ -161,6 +166,7 @@ float RunningAverage::getStandardDeviation() const
   {
     temp += pow((_array[i] - average), 2);
   }
+  //  TODO: when to divide by count || count-1?
   temp = sqrt(temp/(_count - 1));
   return temp;
   //  see issue #13
@@ -188,16 +194,20 @@ float RunningAverage::getStandardError() const
 //  fill the average with the same value number times. (weight)
 //  This is maximized to size times.
 //  no need to fill the internal buffer over 100%
-void RunningAverage::fillValue(const float value, const uint16_t number)
+bool RunningAverage::fillValue(const float value, const uint16_t number)
 {
-  clear();
+  if (!clear())
+  {
+    return false;
+  }
   uint16_t s = number;
   if (s > _partial) s = _partial;
 
   for (uint16_t i = s; i > 0; i--)
   {
     addValue(value);
   }
+  return true;
 }
 
 
@@ -223,7 +233,7 @@ void RunningAverage::fillValue(const float value, const uint16_t number)
 
 float RunningAverage::getValue(const uint16_t position)
 {
-  if (_count == 0)
+  if ((_count == 0) || (_array == NULL))
   {
     return NAN;
   }
@@ -238,11 +248,11 @@ float RunningAverage::getValue(const uint16_t position)
 }
 
 
-void RunningAverage::setPartial(const uint16_t partial)
+bool RunningAverage::setPartial(const uint16_t partial)
 {
   _partial = partial;
   if ((_partial == 0) || (_partial > _size)) _partial = _size;
-  clear();
+  return clear();
 }
 
 
@@ -264,6 +274,28 @@ float RunningAverage::getAverageLast(uint16_t count)
 }
 
 
+float RunningAverage::getStandardDeviationLast(uint16_t count)
+{
+  uint16_t cnt = count;
+  if (cnt > _count) cnt = _count;
+  if (cnt <= 1) return NAN;
+
+  float temp = 0;
+  float average = getAverageLast(count);
+
+  uint16_t idx = _index;
+
+  for (uint16_t i = 0; i < cnt; i++)
+  {
+    if (idx == 0) idx = _size;
+    idx--;
+    temp += pow((_array[idx] - average), 2);
+  }
+  temp = sqrt(temp/(cnt - 1));
+  return temp;
+}
+
+
 float RunningAverage::getMinInBufferLast(uint16_t count)
 {
   uint16_t cnt = count;
@@ -306,7 +338,7 @@ float RunningAverage::getMaxInBufferLast(uint16_t count)
 
 float RunningAverage::getAverageSubset(uint16_t start, uint16_t count)
 {
-  if (_count == 0)
+  if ((_count == 0) || (_array == NULL))
   {
     return NAN;
   }