update readme.md (#17)

- update readme.md (badges). - add performance test example (another). - add UNO + ESP32 test results. - minor edits.
RobTillaart · Oct 31, 2023 · 19d3332 · 19d3332
1 parent 7eb7380
commit 19d3332
Show file tree

Hide file tree

Showing 15 changed files with 225 additions and 44 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.4.1] - 2023-10-30
+- update readme.md (badges).
+- add performance test example (another).
+  - add UNO + ESP32 test results.
+- minor edits.
+
+
 ## [0.4.0] - 2022-11-02
 - add changelog.md
 - add rp2040 to build-CI

diff --git a/FastMap.cpp b/FastMap.cpp
@@ -1,11 +1,9 @@
 //
 //    FILE: FastMap.cpp
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.0
+// VERSION: 0.4.1
 // PURPOSE: class with fast map function - library for Arduino
 //     URL: https://github.com/RobTillaart/FastMap
-//
-// HISTORY: see changelog.md
 
 
 #include "FastMap.h"
@@ -115,5 +113,5 @@ double FastMapDouble::upperConstrainedMap(double value)
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/FastMap.h b/FastMap.h
@@ -2,14 +2,14 @@
 //
 //    FILE: FastMap.h
 //  AUTHOR: Rob Tillaart
-// VERSION: 0.4.0
+// VERSION: 0.4.1
 // PURPOSE: class with fast map function - library for Arduino
 //     URL: https://github.com/RobTillaart/FastMap
 
 
 #include "Arduino.h"
 
-#define FASTMAP_LIB_VERSION           (F("0.4.0"))
+#define FASTMAP_LIB_VERSION           (F("0.4.1"))
 
 
 class FastMap
@@ -53,5 +53,5 @@ class FastMapDouble
 };
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/README.md b/README.md
@@ -2,8 +2,11 @@
 [![Arduino CI](https://github.com/RobTillaart/FastMap/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
 [![Arduino-lint](https://github.com/RobTillaart/FastMap/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/FastMap/actions/workflows/arduino-lint.yml)
 [![JSON check](https://github.com/RobTillaart/FastMap/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/FastMap/actions/workflows/jsoncheck.yml)
+[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/FastMap.svg)](https://github.com/RobTillaart/FastMap/issues)
+
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/FastMap/blob/master/LICENSE)
 [![GitHub release](https://img.shields.io/github/release/RobTillaart/FastMap.svg?maxAge=3600)](https://github.com/RobTillaart/FastMap/releases)
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/FastMap.svg)](https://registry.platformio.org/libraries/robtillaart/FastMap)
 
 
 # FastMap
@@ -23,6 +26,7 @@ This allows mapping that would be hard to achieve with the normal **map()** func
 
 Since 0.4.0 the **init()** function will not accept zero range defining input or output parameters. 
 
+
 ## Performance notes
 
 (based upon tests https://github.com/RobTillaart/FastMap/issues/4 )
@@ -54,6 +58,13 @@ Furthermore using double might imply a performance penalty on some platforms.
 
 ## Interface
 
+```cpp
+#include "FastMap.h"
+```
+
+### Base
+
+- **FastMap()** Constructor
 - **bool init(float in_min, float in_max, float out_min, float out_max)** defines the linear mapping parameters.  
 The **init()** function calculates all needed values for the **map()**, the **back()** call and the **constrainXX()** functions.
 The **init()** function can be called again with new values when needed to do other mapping,
@@ -84,6 +95,8 @@ To display doubles one might need the **sci()** function of my **printHelpers**
 https://github.com/RobTillaart/printHelpers
 
 Note that on most embedded platforms the performance of doubles is less than floats.
+See below.
+
 
 #### boards supporting double
 
@@ -112,22 +125,58 @@ void loop() {}
 ```
 
 
-## Usage
+## Performance 
+
+Tested version 0.4.1 with **fastMap_performance_test.ino**
+
+|         |  MAP     |  FASTMAP  |  FASTMAP dbl  |  Notes  |
+|:--------|:--------:|:---------:|:-------------:|:-------:|
+|  UNO    |  496072  |  211888   |  211888       |  float == double
+|  ESP32  |  1814    |  627      |  6924         |  
+
+
+UNO scores factor 2.34
+ESP32 scores factor 2.89
+
+Note: the 8 byte double (ESP32) is ~11 x slower than the float version,
+and ~4 x slower than the default map function.
+So unless the precision of 8 bytes double is required one better
+uses the float version.
 
-See examples.
+Note: always do your own performance measurements!
+
+If you have additional performance figures for other boards,
+please let me know (report via an issue).
 
 
 ## Future
 
-#### must
+#### Must
 
-#### should
 - update documentation
+
+#### Should
+
 - test performance fastMapDouble on ESP32.
+  - need good test example
+
+#### Could
 
-#### could
 - investigate map function for complex numbers? / coordinates?
-- can fastMap and fastMapDouble be in a class hierarchy? gain?
 - Template class?
 
+#### Wont
+
+- can fastMap and fastMapDouble be in a class hierarchy? limited gain?
+
+
+## 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,
+
+
 
diff --git a/examples/constrainedMapDemo/constrainedMapDemo.ino b/examples/constrainedMapDemo/constrainedMapDemo.ino
@@ -46,5 +46,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/fastMapDemo/fastMapDemo.ino b/examples/fastMapDemo/fastMapDemo.ino
@@ -25,10 +25,10 @@ void setup()
   Serial.println(FASTMAP_LIB_VERSION);
   Serial.println();
 
-  // Get a non optimizable value;
+  //  Get a non optimizable value;
   int z = analogRead(A0);
 
-  // REFERENCE
+  //  REFERENCE
   start = micros();
   for (int i = 0; i < 10000; i++)
   {
@@ -42,7 +42,7 @@ void setup()
   Serial.println(x);
   Serial.println();
 
-  // FASTMAP
+  //  FASTMAP
   mapper.init(0, 1023, yy, zz);
   start = micros();
   for (int i = 0; i < 10000; i++)
@@ -55,7 +55,7 @@ void setup()
   Serial.print(" -> ");
   Serial.println(x);
 
-  // GAIN
+  //  GAIN
   Serial.print("Performance factor: ");
   Serial.println(reference/(stop-start));
 }
@@ -66,5 +66,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/fastMapDemo2/fastMapDemo2.ino b/examples/fastMapDemo2/fastMapDemo2.ino
@@ -8,8 +8,8 @@
 
 #include "FastMap.h"
 
-FastMap CtoF;
-FastMap FtoC;
+FastMap CtoF;  //  Celsius to Fahrenheit
+FastMap FtoC;  //  Fahrenheit to Celsius
 
 
 void setup()
@@ -39,5 +39,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/fastMapDemo3/fastMapDemo3.ino b/examples/fastMapDemo3/fastMapDemo3.ino
@@ -8,7 +8,7 @@
 
 #include "FastMap.h"
 
-FastMap CtoF;
+FastMap CtoF;  //  Celsius to Fahrenheit
 
 
 void setup()
@@ -46,5 +46,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/fastMapDemo4/fastMapDemo4.ino b/examples/fastMapDemo4/fastMapDemo4.ino
@@ -25,10 +25,10 @@ void setup()
   Serial.println(FASTMAP_LIB_VERSION);
   Serial.println();
 
-  // Get a non optimizable value;
+  //  Get a non optimizable value;
   int z = analogRead(A0);
 
-  // REFERENCE
+  //  REFERENCE
   start = micros();
   for (int i = 0; i < 10000; i++)
   {
@@ -43,7 +43,7 @@ void setup()
   Serial.println(x);
   Serial.println();
 
-  // FASTMAP
+  //  FASTMAP
   mapper.init(0, 1023, yy, zz);
   start = micros();
   for (int i = 0; i < 10000; i++)
@@ -57,12 +57,12 @@ void setup()
   Serial.print(" -> ");
   Serial.println(x);
 
-  // GAIN
+  //  GAIN
   Serial.print("Performance factor: ");
   Serial.println((float)reference/(stop-start));
   Serial.println();
 
-  // constrainedMap
+  //  constrainedMap
   mapper.init(0, 1023, yy, zz);
   start = micros();
   for (int i = 0; i < 10000; i++)
@@ -76,12 +76,12 @@ void setup()
   Serial.print(" -> ");
   Serial.println(x);
 
-  // GAIN
+  //  GAIN
   Serial.print("Performance factor: ");
   Serial.println((float)reference/(stop-start));
   Serial.println();
 
- // lowerConstrainedMap
+ //  lowerConstrainedMap
   mapper.init(0, 1023, yy, zz);
   start = micros();
   for (int i = 0; i < 10000; i++)
@@ -95,12 +95,12 @@ void setup()
   Serial.print(" -> ");
   Serial.println(x);
 
-  // GAIN
+  //  GAIN
   Serial.print("Performance factor: ");
   Serial.println((float)reference/(stop-start));
   Serial.println();
 
- // upperConstrainedMap
+ //  upperConstrainedMap
   mapper.init(0, 1023, yy, zz);
   start = micros();
   for (int i = 0; i < 10000; i++)
@@ -114,7 +114,7 @@ void setup()
   Serial.print(" -> ");
   Serial.println(x);
 
-  // GAIN
+  //  GAIN
   Serial.print("Performance factor: ");
   Serial.println((float)reference/(stop-start));
   Serial.println();
@@ -128,5 +128,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --
 
diff --git a/examples/fastMapDouble/fastMapDouble.ino b/examples/fastMapDouble/fastMapDouble.ino
@@ -11,7 +11,7 @@
 
 #include "FastMap.h"
 
-#include "printHelpers.h"    // https://github.com/RobTillaart/printHelpers
+#include "printHelpers.h"    //  https://github.com/RobTillaart/printHelpers
 
 uint32_t start, stop;
 volatile double x;
@@ -27,11 +27,11 @@ void setup()
   Serial.println(FASTMAP_LIB_VERSION);
   Serial.println();
 
-  // Get a non optimizable value;
+  //  Get a non optimizable value;
   volatile double pie = PI;
 
-  // FASTMAP
-  // map 0 .. 100% to lightspeed in km/hr
+  //  FASTMAP
+  //  map 0 .. 100% to lightspeed in km/hr
   mapper.init(0, 100, 0, 1.0792528488E+12);
   start = micros();
   for (int i = 0; i < 10000; i++)
@@ -65,5 +65,5 @@ void loop()
 }
 
 
-// -- END OF FILE --
+//  -- END OF FILE --