final edits

Author: RobTillaart

CHANGELOG.md

@@ -8,8 +8,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [0.3.0] - 2026-02-23
 - fix #13, allow size to be 65535 (uint16_t)
-- fix math overflow when using int result types.
-- add multi type **multiMapCache<T1, T2>** to have all options.
+- add patch for mixed math signed / unsigned multiMap. 
+- add multi type **multiMapCache<T1, T2>** as it was missing.
 - update readme.md
 - update GitHub actions
 - minor edits

MultiMap.h

@@ -36,7 +36,9 @@ T multiMap(T value, T* _in, T* _out, uint16_t size)
   if (value == _in[pos]) return _out[pos];
 
   //  interpolate in the right segment for the rest
-  return T(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
+  return (value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
+  //  if interpolation overflows use this line
+  //  return T(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
 }
 
 
@@ -83,7 +85,9 @@ T multiMapCache(T value, T* _in, T* _out, uint16_t size)
     else
     {
       //  interpolate in the right segment for the rest
-      cache = T(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
+      cache = (value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
+      //  if interpolation overflows use this line
+      //  cache = T(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
     }
   }
   return cache;
@@ -114,7 +118,10 @@ T multiMapBS(T value, T* _in, T* _out, uint16_t size)
     if (value >= _in[mid]) lower = mid;
     else upper = mid;
   }
-  return T(float(value - _in[lower]) * (_out[upper] - _out[lower]) / (_in[upper] - _in[lower])) + _out[lower];
+  //  interpolate in the right segment for the rest
+  return (value - _in[lower]) * (_out[upper] - _out[lower]) / (_in[upper] - _in[lower]) + _out[lower];
+  //  if interpolation overflows use this line
+  //  return T(float(value - _in[lower]) * (_out[upper] - _out[lower]) / (_in[upper] - _in[lower])) + _out[lower];
 }
 
 
@@ -138,7 +145,9 @@ T2 multiMap(T1 value, T1* _in, T2* _out, uint16_t size)
   if (value == _in[pos]) return _out[pos];
 
   //  interpolate in the right segment for the rest
-  return T2(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
+  return (value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
+  //  if interpolation overflows use this line
+  //  return T2(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
 }
 
 
@@ -185,7 +194,9 @@ T2 multiMapCache(T1 value, T1* _in, T2* _out, uint16_t size)
     else
     {
       //  interpolate in the right segment for the rest
-      cache = T2(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
+      cache = (value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1]) + _out[pos-1];
+      //  if interpolation overflows use this line
+      //  return T2(float(value - _in[pos-1]) * (_out[pos] - _out[pos-1]) / (_in[pos] - _in[pos-1])) + _out[pos-1];
     }
   }
   return cache;
@@ -215,8 +226,10 @@ T2 multiMapBS(T1 value, T1* _in, T2* _out, uint16_t size)
     if (value >= _in[mid]) lower = mid;
     else upper = mid;
   }
-
-  return T2(float(value - _in[lower]) * (_out[upper] - _out[lower]) / (_in[upper] - _in[lower])) + _out[lower];
+  //  interpolate in the right segment for the rest
+  return (value - _in[lower]) * (_out[upper] - _out[lower]) / (_in[upper] - _in[lower]) + _out[lower];
+  //  if interpolation overflows use this line
+  //  return T2(float(value - _in[lower]) * (_out[upper] - _out[lower]) / (_in[upper] - _in[lower])) + _out[lower];
 }
 
 

README.md

@@ -57,42 +57,40 @@ However there might be more than one input value mapping onto the same output va
 See - https://en.wikipedia.org/wiki/Bijection,_injection_and_surjection
 
 
+### Math problems in interpolation (rare).
+
+In multiMap the interpolation math can fail. This happens when integer types are used 
+that are too small to handle the multiplication in the interpolation (e.g. 8 or 16 bit)
+Also when a mixed signed / unsigned types are used this can happen.
+
+There are two solutions to handle this.
+- (preferred) use float (double) as either input or output type.
+This forces casting to float in the interpolation solving the math problem.
+Drawback is it might take extra memory (e.g. int16_t => float).
+- The multiMap.h file contains **commented** code to cast the interpolation 
+during the interpolation only.
+Comment the existing interpolation and uncomment the other line.
+This saves memory as the arrays used do not "grow". 
+
+Note both solutions have a performance penalty
+
+See the sketch **multimap_demo_fail.ino** (UNO R3) to show the problem.
+
+
 ### 0.3.0 Breaking change
 
 This 0.3.0 version makes the previous versions obsolete.
 
 Since 0.3.0 sizes of multiMap can exceed 256 elements, up to 65535 elements.
 This is because the size has changed from an uint8_t => uint16_t.
 
-More important the internal math has an extra float cast as when using int types
-there was sometimes an overflow in the interpolation (rare but wrong).
-
-On an UNO R3 this breaking change altered the performance.
-Linear search got better, binary search got worse but is still
-better than the linear search.
-
-From **multimap_BS_compare.ino** version 0.2.1 versus 0.3.0.
-
-|  version  |  size  |    t1   |    t2   |   ratio   |
-|:----------|:------:|--------:|--------:|----------:|
-|   0.2.1   |   10   |   9476  |   9364  |    98.82  |
-|   0.2.1   |   15   |  13348  |  12628  |    94.61  |
-|   0.2.1   |   20   |  17808  |  15948  |    89.56  |
-|   0.2.1   |   30   |  28476  |  22712  |    79.76  |
-|   0.2.1   |   40   |  41516  |  29620  |    71.35  |
-|   0.2.1   |   50   |  56896  |  36608  |    64.34  |
-|   0.2.1   |   70   |  94716  |  50700  |    53.53  |
-|   0.2.1   |   90   | 141936  |  65136  |    45.89  |
-|           |        |         |         |           |
-|   0.3.0   |   10   |  10592  |  10688  |   100.91  |
-|   0.3.0   |   15   |  14528  |  14736  |   101.43  |
-|   0.3.0   |   20   |  18808  |  18868  |   100.32  |
-|   0.3.0   |   30   |  28412  |  27240  |    95.87  |
-|   0.3.0   |   40   |  39396  |  35784  |    90.83  |
-|   0.3.0   |   50   |  51764  |  44428  |    85.83  |
-|   0.3.0   |   70   |  80648  |  61864  |    76.71  |
-|   0.3.0   |   90   | 115068  |  79640  |    69.21  |
-|           |        |         |         |           |
+On an UNO R3 the change of the size to uint16_t altered the performance.
+Linear search got better, binary search got worse but still performs
+better than the linear search in a test.
+
+Run **multimap_BS_compare.ino** to see the differences.
+
+(output logs of UNO R3 are in the example folder).
 
 
 ### Related

examples/multimap_2d/multimap_2d.ino

@@ -4,9 +4,10 @@
 // PURPOSE: demo mapping an angle on a semi-circle (2D {x, y} position)
 //     URL: https://github.com/RobTillaart/MultiMap
 //
-//  when printing into a plotter one sees a rough sine and cosine
+//  when printing into a plotter one sees a very rough sine and cosine
 //  with an amplitude of 5, approximated with interpolation.
 
+
 #include "MultiMap.h"
 
 float in[]  = { 0, 30, 60, 90, 120, 150, 180, 210, 240, 270, 300, 330, 360 };

examples/multimap_BS_compare/output_0.3.0.txt

@@ -6,102 +6,103 @@ Arduino\libraries\MultiMap\examples\multimap_BS_compare\multimap_BS_compare.ino
 MULTIMAP_LIB_VERSION: 0.3.0
 
 size	t1	t2	ratio
-4	6328	5992	94.69
-5	7008	6744	96.23
-6	7700	7524	97.71
-7	8400	8320	99.05
-8	9116	9092	99.74
-9	9852	9888	100.37
-10	10592	10688	100.91
-11	11352	11496	101.27
-12	12128	12304	101.45
-13	12908	13120	101.64
-14	13716	13924	101.52
-15	14528	14736	101.43
-16	15360	15556	101.28
-17	16204	16368	101.01
-18	17056	17196	100.82
-19	17924	18032	100.60
-20	18808	18868	100.32
-21	19708	19696	99.94
-22	20620	20532	99.57
-23	21544	21372	99.20
-24	22488	22208	98.75
-25	23440	23048	98.33
-26	24400	23888	97.90
-27	25388	24724	97.38
-28	26380	25564	96.91
-29	27388	26408	96.42
-30	28412	27240	95.87
-31	29448	28088	95.38
-32	30500	28928	94.85
-33	31564	29776	94.34
-34	32644	30628	93.82
-35	33732	31488	93.35
-36	34836	32344	92.85
-37	35956	33200	92.34
-38	37088	34060	91.84
-39	38240	34924	91.33
-40	39396	35784	90.83
-41	40568	36652	90.35
-42	41760	37512	89.83
-43	42960	38368	89.31
-44	44184	39232	88.79
-45	45404	40108	88.34
-46	46648	40964	87.82
-47	47904	41832	87.32
-48	49180	42700	86.82
-49	50468	43572	86.34
-50	51764	44428	85.83
-51	53072	45296	85.35
-52	54404	46152	84.83
-53	55744	47020	84.35
-54	57100	47880	83.85
-55	58468	48748	83.38
-56	59844	49616	82.91
-57	61236	50496	82.46
-58	62652	51356	81.97
-59	64080	52220	81.49
-60	65516	53088	81.03
-61	66968	53956	80.57
-62	68428	54832	80.13
-63	69908	55708	79.69
-64	71404	56576	79.23
-65	72904	57460	78.82
-66	74424	58332	78.38
-67	75960	59212	77.95
-68	77508	60088	77.52
-69	79076	60976	77.11
-70	80648	61864	76.71
-71	82236	62744	76.30
-72	83836	63636	75.91
-73	85456	64524	75.51
-74	87088	65396	75.09
-75	88728	66292	74.71
-76	90396	67172	74.31
-77	92064	68072	73.94
-78	93744	68960	73.56
-79	95448	69848	73.18
-80	97164	70740	72.80
-81	98888	71636	72.44
-82	100632	72520	72.06
-83	102392	73404	71.69
-84	104160	74288	71.32
-85	105944	75180	70.96
-86	107736	76064	70.60
-87	109552	76960	70.25
-88	111368	77852	69.91
-89	113204	78752	69.57
-90	115068	79640	69.21
-91	116928	80532	68.87
-92	118808	81420	68.53
-93	120704	82316	68.20
-94	122612	83212	67.87
-95	122728	83312	67.88
-96	122732	83352	67.91
-97	122728	83432	67.98
-98	122728	83428	67.98
-99	122724	83468	68.01
+4	5588	5600	100.21
+5	6160	6200	100.65
+6	6756	6820	100.95
+7	7368	7448	101.09
+8	7992	8076	101.05
+9	8636	8700	100.74
+10	9308	9344	100.39
+11	9996	9996	100.00
+12	10700	10644	99.48
+13	11424	11288	98.81
+14	12172	11944	98.13
+15	12936	12588	97.31
+16	13724	13232	96.42
+17	14524	13884	95.59
+18	15348	14552	94.81
+19	16192	15224	94.02
+20	17052	15892	93.20
+21	17936	16564	92.35
+22	18836	17232	91.48
+23	19748	17904	90.66
+24	20688	18580	89.81
+25	21648	19252	88.93
+26	22624	19928	88.08
+27	23620	20592	87.18
+28	24644	21260	86.27
+29	25680	21936	85.42
+30	26728	22608	84.59
+31	27804	23276	83.71
+32	28896	23952	82.89
+33	30008	24628	82.07
+34	31140	25320	81.31
+35	32296	26008	80.53
+36	33464	26700	79.79
+37	34652	27396	79.06
+38	35864	28088	78.32
+39	37096	28780	77.58
+40	38340	29476	76.88
+41	39612	30164	76.15
+42	40900	30860	75.45
+43	42204	31556	74.77
+44	43532	32252	74.09
+45	44880	32944	73.40
+46	46244	33640	72.74
+47	47624	34336	72.10
+48	49032	35028	71.44
+49	50452	35724	70.81
+50	51900	36420	70.17
+51	53356	37108	69.55
+52	54844	37804	68.93
+53	56340	38500	68.34
+54	57856	39196	67.75
+55	59400	39888	67.15
+56	60960	40580	66.57
+57	62536	41276	66.00
+58	64136	41972	65.44
+59	65748	42668	64.90
+60	67388	43360	64.34
+61	69044	44056	63.81
+62	70716	44756	63.29
+63	72412	45448	62.76
+64	74128	46144	62.25
+65	75856	46840	61.75
+66	77608	47552	61.27
+67	79384	48268	60.80
+68	81176	48976	60.33
+69	82980	49696	59.89
+70	84812	50408	59.43
+71	86656	51128	59.00
+72	88528	51844	58.56
+73	90416	52556	58.13
+74	92320	53276	57.71
+75	94248	53992	57.29
+76	96196	54704	56.87
+77	98156	55428	56.47
+78	100148	56132	56.05
+79	102144	56860	55.67
+80	104176	57572	55.26
+81	106220	58292	54.88
+82	108280	59008	54.50
+83	110360	59716	54.11
+84	112460	60436	53.74
+85	114580	61156	53.37
+86	116720	61872	53.01
+87	118876	62588	52.65
+88	121056	63304	52.29
+89	123252	64020	51.94
+90	125468	64736	51.60
+91	127700	65456	51.26
+92	129960	66172	50.92
+93	132236	66896	50.59
+94	134528	67608	50.26
+95	134696	67696	50.26
+96	134696	67724	50.28
+97	134692	67772	50.32
+98	134696	67776	50.32
+99	134692	67804	50.34
+
 
 
 

examples/multimap_demo/multimap_demo.ino

@@ -9,7 +9,7 @@
 
 #include "MultiMap.h"
 
-//  not the IN array is not equidistant.
+//  note the IN array is not equidistant.
 //  layout is to see the points of the graph.
 float in[]  = { 0, 20,  40,  50,  60,   80,   90,   100, 105 };
 float out[] = { 1, 2.8, 4.5, 7.0, 10.4, 33.5, 57.5, 100, 120 };