add multiMapCache and multiMapBS template functions (#8)

- add **multiMapCache()**, experimental version that caches the last value.
  to be used with input that do not change often.
- add **multiMapBS()**, experimental version that uses binary search.
  to be used with arrays > 10 (rule of thumb)
- add examples
- major rewrite readme.md

Author: RobTillaart

CHANGELOG.md

@@ -6,13 +6,21 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.1.7] - 2023-06-24
+- add **multiMapCache()**, experimental version that caches the last value.
+  to be used with input that do not change often.
+- add **multiMapBS()**, experimental version that uses binary search.
+  to be used with arrays > 10 (rule of thumb)
+- add examples
+- major rewrite readme.md
+
+
 ## [0.1.6] - 2022-11-17
 - add RP2040 in build-CI
 - add changelog.md
 - update readme.md
 - clean up unit test
 
-
 ## [0.1.5] - 2021-12-22
 - update library.json
 - update readme

MultiMap.h

@@ -2,61 +2,58 @@
 //
 //    FILE: MultiMap.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.1.6
+// VERSION: 0.1.7
 //    DATE: 2011-01-26
 // PURPOSE: Arduino library for fast non-linear mapping or interpolation of values
 //     URL: https://github.com/RobTillaart/MultiMap
 //     URL: http://playground.arduino.cc/Main/MultiMap
 
 
 
-#define MULTIMAP_LIB_VERSION                (F("0.1.6"))
+#define MULTIMAP_LIB_VERSION                (F("0.1.7"))
 
 
 #include "Arduino.h"
 
 
-// note: the in array should have increasing values
+// note: the in array must have increasing values
 template<typename T>
 T multiMap(T value, T* _in, T* _out, uint8_t size)
 {
-    // take care the value is within range
-    // value = constrain(value, _in[0], _in[size-1]);
-    if (value <= _in[0]) return _out[0];
-    if (value >= _in[size-1]) return _out[size-1];
+  //  output is constrained to out array
+  if (value <= _in[0]) return _out[0];
+  if (value >= _in[size-1]) return _out[size-1];
 
-    // search right interval
-    uint8_t pos = 1;  // _in[0] already tested
-    while(value > _in[pos]) pos++;
+  // search right interval
+  uint8_t pos = 1;  // _in[0] already tested
+  while(value > _in[pos]) pos++;
 
-    // this will handle all exact "points" in the _in array
-    if (value == _in[pos]) return _out[pos];
+  // this will handle all exact "points" in the _in array
+  if (value == _in[pos]) return _out[pos];
 
-    // interpolate in the right segment for the rest
-    return (value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
+  // interpolate in the right segment for the rest
+  return (value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
 }
 
 
-/*
-//  speed optimized version if inputs do not change often e.g.  2 2 2 2 2 3 3 3 3 5 5 5 5 5 5 8 8 8 8 5 5 5 5 5 
-//  implements a minimal cache
+//  performance optimized version if inputs do not change often 
+//     e.g.  2 2 2 2 2 3 3 3 3 5 5 5 5 5 5 8 8 8 8 5 5 5 5 5 
+//  implements a minimal cache of the lastValue.
 //
-//  note: the in array should have increasing values
-
+//  note: the in array must have increasing values
 template<typename T>
-T multiMap(T value, T* _in, T* _out, uint8_t size)
+T multiMapCache(T value, T* _in, T* _out, uint8_t size)
 {
-  static T lastvalue = -1;
+  static T lastValue = -1;
   static T cache = -1;  
 
-  if (value == lastvalue)
+  if (value == lastValue)
   {
     return cache;
   }
-  lastvalue = value;
+  lastValue = value;
 
-  // take care the value is within range
-  // value = constrain(value, _in[0], _in[size-1]);
+  //  output is constrained to out array
   if (value <= _in[0])
   {
     cache = _out[0];
@@ -67,7 +64,7 @@ T multiMap(T value, T* _in, T* _out, uint8_t size)
   }
   else
   {
-    // search right interval; index 0 _in[0] already tested
+    //  search right interval; index 0 _in[0] already tested
     uint8_t pos = 1;  
     while(value > _in[pos]) pos++;
 
@@ -84,8 +81,32 @@ T multiMap(T value, T* _in, T* _out, uint8_t size)
   }
   return cache;
 }
-*/
 
 
-// -- END OF FILE --
+//  binary search version, should be faster for size > 10 
+//  (rule of thumb)
+//
+// note: the in array must have increasing values
+template<typename T>
+T multiMapBS(T value, T* _in, T* _out, uint16_t size)
+{
+  //  output is constrained to out array
+  if (value <= _in[0]) return _out[0];
+  if (value >= _in[size-1]) return _out[size-1];
+
+  // Binary Search
+  uint16_t lower = 0;
+  uint16_t upper = size - 1;
+  while (lower < upper - 1)
+  {
+    uint16_t mid = (lower + upper) / 2;
+    if (value >= _in[mid]) lower = mid;
+    else upper = mid;
+  }
+
+  return (value - _in[lower]) * (_out[upper] - _out[lower]) / (_in[upper] - _in[lower]) + _out[lower];
+}
+
+
+//  -- END OF FILE --
 

README.md

@@ -8,38 +8,112 @@
 
 # MultiMap
 
-Arduino library for fast non-linear mapping or interpolation of values
+Arduino library for fast non-linear mapping or interpolation of values.
 
 
 ## Description
 
-In Arduino applications often the value of a sensor is mapped upon a more
-usable value. E.g. the value of analogRead() is mapped onto 0 .. 5.0 Volt.
-This is done by the map function which does a linear interpolation. 
+In Arduino applications often the 'raw' value of a sensor is mapped upon a more
+usable value. E.g. the value of analogRead() 0 .. 1023 is mapped onto 0 .. 5.0 Volt.
+This is often done by the map function which does a linear interpolation.
+
 This means in code:
 
 ```cpp
     output = C1 + input * C2
 ```
 
-As C1 and C2 are to be calculated Arduino has the **map()** that calculates the 
-two variables runtime from two given mappings.
+As C1 and C2 are to be determined, Arduino has the **map()** function that calculates the 
+two variables runtime from two given mapping points (I1, O1) and (I2, O2).
 
 ```cpp
     output = map(input, I1, I2, O1, O2):
 ```
 
-In many cases when there is no linear mapping possible, as the 'points' are not on a single straight line.
-One needs non-linear math to calculate the output, **Multimap()** just simulates that.
+In many cases when there is no linear mapping possible as the 'points' are not on a single straight line.
+To solve this one needs non-linear math to calculate the output.
+
+The **multiMap()** function simulates this math by approximating the non-linear function with multiple
+linear line segments. 
+Of course this approximation introduces an error. 
+By increasing the number of points and choose their position strategically the average error will be reduced.
+
+Note: some functions are hard to approximate with multiMap as they go to infinity or have a singularity.
+Think of **tan(x)** around x = PI/2 (90°) or **sin(1/x)** around zero.
+
+
+#### Usage
+
+The basic call for **multiMap()** is:
+
+```cpp
+output = Multimap<datatype>(input, inputArray, outputArray, size);
+```
+
+**multiMap()** needs two equally sized arrays representing the reference 'points' named 
+**inputArray\[\]** and **outputArray\[\]** both of the **datatype**.
 
-**out = Multimap(value, input, output, size)** needs two equal sized arrays of reference 'points', 
-**input\[\]** and **output\[\]**, it looks up the 
-input value in the input\[\] array and if needed it linear interpolates between two
-points of the output\[\] array. 
+**multiMap()** will do a lookup of the input value in the inputArray\[\].
+If it cannot find the index of an exact point it will determine a weighted position between two points.
+This optional weighted point is used to interpolate a value from data in the output\[\] array.
 
-- The **input\[\]** array must have increasing values, 
+- The **inputArray\[\]** must have increasing values, 
 there is no such restriction for the **output\[\]** array.
-- **Multimap()** automatically constrains the output to the first and last value in the **output\[\]** array.
+- The values of the **inputArray\[\]** do not need to have the same distance (non-equidistant).
+E.g an array like { 1, 10, 100, 1000 } is valid.
+- **multiMap()** automatically constrains the output to the first and last value in the **output\[\]** array.
+This is a explicit difference with the **map()** function.
+Therefore it is important to extend the range of the arrays to cover all possible values.
+
+
+#### Performance
+
+**multiMap()** does a linear search for the inputValue in the inputArray.
+This implies that usage of larger and more precise arrays will take more time.
+Furthermore "low" input values will be found faster than "high" values.
+
+As every usage of multiMap() is unique one should always do a performance check to see
+if there is a substantial gain in the case at hand. In my experience there often is.
+
+
+#### MultiMapBS
+
+Experimental 0.1.7 => use with care.
+
+**multiMapBS()** MMBS for short, is a very similar function as **multiMap()**.
+The main difference is that MMBS uses binary search instead of linear search.
+
+First performance tests indicate that for array sizes about 10 MMBS is on par
+with **multiMap()**. This is expected as both need on average about 5 steps 
+to find the right interval.
+
+Be sure to do your own tests to see if MMBS improves your performance.
+
+
+#### MultiMapCache
+
+Experimental 0.1.7 => use with care.
+
+**multiMapCache()** MMC for short, is a very similar function as **multiMap()**.
+The main difference is that MMC caches the last input and output value.
+The goal is to improve the performance by preventing 
+
+If the input sequence has a lot of repeating values e.g. 2 2 2 2 2 2 5 5 5 5 5 4 4 4 4 2 2 2 2 2 2
+MMC will be able to return the value from cache often. 
+Otherwise keeping cache is overhead.
+
+Be sure to do your own tests to see if MMC improves your performance.
+
+
+#### Related
+
+Other mapping libraries 
+
+- https://github.com/RobTillaart/FastMap
+- https://github.com/RobTillaart/Gamma
+- https://github.com/RobTillaart/map2colour
+- https://github.com/RobTillaart/moduloMap
+- https://github.com/RobTillaart/MultiMap
 
 
 ## Operation
@@ -51,20 +125,43 @@ Please note the fail example as this shows that in the intern math overflow can
 
 ## Future
 
-#### must
+#### Must
+
 - improve documentation
 
-#### should
-- Investigate class implementation 
+
+#### Should
+
+- investigate multiMapCache behaviour
+  - determine overhead.
+- investigate binary search multiMapBS behaviour
+  - expect a constant time
+  - where is the tipping point between linear and binary search.
+    (expect around size = 8)
+- extend unit tests
+
+
+#### Could
+
+- Investigate class implementation
+  - basic call out = mm.map(value);
+  - runtime adjusting input and output array **begin(in[], out[])**
   - performance / footprint
   - less parameter passing
-  
-#### could
-- flag if input value was "IN_MIN" <  input < "IN_MAX", 
-  now it is constrained without user being informed.
-- extend unit tests
+  - **isInRange(value)**?
+  - caching last value / position / index (does that help?)
+  - flag if input value was "IN_MIN" <  input < "IN_MAX", 
+    now it is constrained without user being informed.
+- Investigate a 2D multiMap e.g. for complex numbers?
+  - is it possible / feasible?
+- data type input array does not need to be equal to the output array.
+  - template<typename T1, typename T2>
+    ```T2 multiMapBS(T1 value, T1* _in, T2* _out, uint16_t size)```
+
+
+#### Wont
 
-#### wont
 - should the lookup tables be merged into one array of pairs?
-  - you cannot reuse e.g. the input array then. (memory footprint)
+  - you cannot reuse e.g. the input array or the output array then. 
+    this would not improve the memory footprint.