[Functions] Add 'mapc' to constrain values

docs/source/Rules/Rules.rst

@@ -1425,6 +1425,8 @@ Basic Math Functions
 * ``^`` The caret is used as the exponentiation operator for calculating the value of x to the power of y (x\ :sup:`y`). 
 
 * ``map(value:fromLow:fromHigh:toLow:toHigh)`` Maps value x in the fromLow/fromHigh range to toLow/toHigh values. Similar to the Arduino map() function. See examples below. (Using a colon as an argument separator to not interfere with regular argument processing)
+* ``mapc(value:fromLow:fromHigh:toLow:toHigh)`` same as map, but constrains the result to the fromLow/fromHigh range.
+
 
 Rules example:
 
@@ -1460,7 +1462,7 @@ Called with event ``eventname2=1.234,100``
  213379 : Info   : ACT : LogEntry,'pow of 1.234^100 = 1353679866.79107'
  213382 : Info   : pow of 1.234^100 = 1353679866.79107
 
-Examples using the ``map()`` function. Map does not constrain the values within the given range, but uses extrapolation when the input value goes outside the ``fromLow`` / ``fromHigh`` range.
+Examples using the ``map()`` & ``mapc()`` function. ``map()`` without the "c" does not constrain the values within the given range, but uses extrapolation when the input value goes outside the ``fromLow`` / ``fromHigh`` range.
 
 Missing values for the map function default to 0.
 
@@ -1476,7 +1478,9 @@ Missing values for the map function default to 0.
 
  on eventname3 do
    let,1,map(%eventvalue1|10%:0:100:100:0) // Reverse mapping of a value, 0..100 will output 100..0
+   let,2,mapc(%eventvalue1|10%:0:100:100:0)
    LogEntry,'Input value %eventvalue1|10% mapped to: %v1%'
+   LogEntry,'Input value %eventvalue1|10% mapped to: %v2% and constrained'
  endon
 
 

src/src/Helpers/Rules_calculate.cpp

@@ -77,7 +77,7 @@ bool RulesCalculate_t::is_quinary_operator(char c)
 {
   const UnaryOperator op = static_cast<UnaryOperator>(c);
 
-  return op == UnaryOperator::Map;
+  return op == UnaryOperator::Map || op == UnaryOperator::MapC;
 }
 
 CalculateReturnCode RulesCalculate_t::push(ESPEASY_RULES_FLOAT_TYPE value)
@@ -280,8 +280,13 @@ ESPEASY_RULES_FLOAT_TYPE RulesCalculate_t::apply_quinary_operator(char op,
   ESPEASY_RULES_FLOAT_TYPE ret{};
   const UnaryOperator qu_op = static_cast<UnaryOperator>(op);
 
-  if (UnaryOperator::Map == qu_op) {
-    return mapADCtoFloat(first, second, third, fourth, fifth);
+  if (UnaryOperator::Map == qu_op || UnaryOperator::MapC == qu_op) {
+
+    // Clamp the result if the operator is MapC
+    if (qu_op == UnaryOperator::MapC) {
+      first = constrain(first, min(second, third), max(second, third));;
+    }
+    ret = mapADCtoFloat(first, second, third, fourth, fifth);
   }
   return ret;
 }
@@ -656,6 +661,8 @@ const __FlashStringHelper* toString(UnaryOperator op)
       return F("atan_d");
     case UnaryOperator::Map:
       return F("map");
+    case UnaryOperator::MapC:
+      return F("mapc");
   }
   return F("");
 }
@@ -692,6 +699,7 @@ String RulesCalculate_t::preProces(const String& input)
     ,UnaryOperator::Tan_d
     #endif // if FEATURE_TRIGONOMETRIC_FUNCTIONS_RULES
     ,UnaryOperator::Map
+    ,UnaryOperator::MapC
 
   };
 

src/src/Helpers/Rules_calculate.h

@@ -55,6 +55,7 @@ enum class UnaryOperator : uint8_t {
   ArcTan,    // Arc Tangent (radian)
   ArcTan_d,  // Arc Tangent (degree)
   Map,       // Map (value, lowFrom, highFrom, lowTo, highTo) (not really unary...)
+  MapC,      // Map (value, lowFrom, highFrom, lowTo, highTo) and clamp to lowTo/highTo
 };
 
 void   preProcessReplace(String      & input,

static/espeasy.js

@@ -150,7 +150,7 @@ var pluginDispCmd = [
 ];
 var commonTag = ["On", "Do", "Endon"];
 var commonNumber = ["toBin", "toHex", "Constrain", "XOR", "AND:", "OR:", "Ord", "bitRead", "bitSet", "bitClear", "bitWrite", "urlencode"];
-var commonMath = ["Log", "Ln", "Abs", "Exp", "Sqrt", "Sq", "Round", "Sin", "Cos", "Tan", "aSin", "aCos", "aTan", "Sin_d", "Cos_d", "Tan_d", "aSin_d", "aCos_d", "aTan_d", "map"];
+var commonMath = ["Log", "Ln", "Abs", "Exp", "Sqrt", "Sq", "Round", "Sin", "Cos", "Tan", "aSin", "aCos", "aTan", "Sin_d", "Cos_d", "Tan_d", "aSin_d", "aCos_d", "aTan_d", "map", "mapc"];
 var commonWarning = ["delay", "Delay", "ResetFlashWriteCounter"];
 var taskSpecifics = [
   //Task settings