* Auto-swap the limits passed to constrain if necessary (Closes #3)

* Split map_range into map_range and unconstrained_map_range.
  * map_range will constrain the output value within the provided limits
  * unconstrained_map_range will only use the limits to define the linear equation
* Add tests for constrain with auto-swap
* Add tests for unconstrained_map_range

Author: lesamouraipourpre

adafruit_simplemath.py

@@ -1,4 +1,5 @@
 # SPDX-FileCopyrightText: Copyright (c) 2021 Dan Halbert for Adafruit Industries LLC
+# SPDX-FileCopyrightText: 2021 James Carr
 #
 # SPDX-License-Identifier: MIT
 """
@@ -8,7 +9,7 @@
 Math utility functions
 
 
-* Author(s): Adafruit Industries
+* Author(s): Dan Halbert, James Carr
 
 Implementation Notes
 --------------------
@@ -24,21 +25,18 @@
 
 
 def map_range(
-    x: float,
-    in_min: float,
-    in_max: float,
-    out_min: float,
-    out_max: float,
-    constrained: bool = True,
+    x: float, in_min: float, in_max: float, out_min: float, out_max: float
 ) -> float:
     """
     Maps a number from one range to another. Somewhat similar to the Arduino
     :attr:`map()` function, but returns a floating point result, and
-    optionally constrains the output value to be between :attr:`out_min` and
+    constrains the output value to be between :attr:`out_min` and
     :attr:`out_max`. If :attr:`in_min` is greater than :attr:`in_max` or
     :attr:`out_min` is greater than :attr:`out_max`, the corresponding range
     is reversed, allowing, for example, mapping a range of 0-10 to 50-0.
 
+    See also :py:func:`unconstrained_map_range`
+
     .. code-block::
 
         from adafruit_simplemath import map_range
@@ -48,25 +46,61 @@ def map_range(
         x = map_range(percent, 0, 100, 0, screen_width - 1)
         print("X position", percent, "% from the left of screen is", x)
 
-        celsius = 20
-        fahrenheit = map_range(celsius, 0, 100, 32, 212, constrained=False)
-        print(celsius, "degress Celsius =", fahrenheit, "degrees Fahrenheit")
+    :param float x: Value to convert
+    :param float in_min: Start value of input range.
+    :param float in_max: End value of input range.
+    :param float out_min: Start value of output range.
+    :param float out_max: End value of output range.
+    :return: Returns value mapped to new range.
+    :rtype: float
+    """
+    # in_range = in_max - in_min
+    # in_delta = x - in_min
+    # if in_range != 0:
+    #     mapped = in_delta / in_range
+    # elif in_delta != 0:
+    #     mapped = in_delta
+    # else:
+    #     mapped = 0.5
+    # mapped *= out_max - out_min
+    # mapped += out_min
+
+    mapped = unconstrained_map_range(x, in_min, in_max, out_min, out_max)
+
+    if out_min <= out_max:
+        return max(min(mapped, out_max), out_min)
+    return min(max(mapped, out_max), out_min)
+
+
+def unconstrained_map_range(
+    x: float, in_min: float, in_max: float, out_min: float, out_max: float
+) -> float:
+    """
+    Maps a number from one range to another. Somewhat similar to the Arduino
+    :attr:`map()` function, but returns a floating point result, and
+    does not constrain the output value to be between :attr:`out_min` and
+    :attr:`out_max`. If :attr:`in_min` is greater than :attr:`in_max` or
+    :attr:`out_min` is greater than :attr:`out_max`, the corresponding range
+    is reversed, allowing, for example, mapping a range of 0-10 to 50-0.
+
+    See also :py:func:`map_range`
+
+    .. code-block::
+
+        from adafruit_simplemath import unconstrained_map_range
 
         celsius = -20
-        fahrenheit = map_range(celsius, 0, 100, 32, 212, False)
+        fahrenheit = unconstrained_map_range(celsius, 0, 100, 32, 212)
         print(celsius, "degress Celsius =", fahrenheit, "degrees Fahrenheit")
 
     :param float x: Value to convert
     :param float in_min: Start value of input range.
     :param float in_max: End value of input range.
     :param float out_min: Start value of output range.
     :param float out_max: End value of output range.
-    :param bool constrained: Whether the output value should be constrained
-        between :attr:`out_min` and :attr:`out_max`. Defaults to `True`.
     :return: Returns value mapped to new range.
     :rtype: float
     """
-    # pylint: disable=too-many-arguments
     in_range = in_max - in_min
     in_delta = x - in_min
     if in_range != 0:
@@ -78,11 +112,7 @@ def map_range(
     mapped *= out_max - out_min
     mapped += out_min
 
-    if not constrained:
-        return mapped
-    if out_min <= out_max:
-        return max(min(mapped, out_max), out_min)
-    return min(max(mapped, out_max), out_min)
+    return mapped
 
 
 def constrain(x: float, out_min: float, out_max: float) -> float:
@@ -93,11 +123,14 @@ def constrain(x: float, out_min: float, out_max: float) -> float:
     If :attr:`x` is less than :attr:`out_min`, return :attr:`out_min`.
     If :attr:`x` is greater than :attr:`out_max`, return :attr:`out_max`.
     Otherwise just return :attr:`x`.
+    If :attr:`max_value` is less than :attr:`min_value`, they will be swapped.
 
     :param float x: Value to constrain
     :param float out_min: Lower bound of output range.
     :param float out_max: Upper bound of output range.
     :return: Returns value constrained to given range.
     :rtype: float
     """
-    return max(out_min, min(x, out_max))
+    if out_min <= out_max:
+        return max(min(x, out_max), out_min)
+    return min(max(x, out_max), out_min)

examples/simplemath_simpletest.py

@@ -1,8 +1,9 @@
-# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
+# SPDX-FileCopyrightText: 2021 Dan Halbert for Adafruit Industries
+# SPDX-FileCopyrightText: 2021 James Carr
 #
 # SPDX-License-Identifier: Unlicense
 
-from adafruit_simplemath import map_range, constrain
+from adafruit_simplemath import map_range, unconstrained_map_range, constrain
 
 print("map_range() examples")
 # Map, say, a sensor value, from a range of 0-255 to 0-1023.
@@ -20,15 +21,16 @@
 x = map_range(percent, 0, 100, 0, screen_width - 1)
 print("X position", percent, "% from the left of screen is", x)
 
+print("\nunconstrained_map_range() examples")
 celsius = 20
-fahrenheit = map_range(celsius, 0, 100, 32, 212, constrained=False)
+fahrenheit = unconstrained_map_range(celsius, 0, 100, 32, 212)
 print(celsius, "degress Celsius =", fahrenheit, "degrees Fahrenheit")
 
 celsius = -20
-fahrenheit = map_range(celsius, 0, 100, 32, 212, False)
+fahrenheit = unconstrained_map_range(celsius, 0, 100, 32, 212)
 print(celsius, "degress Celsius =", fahrenheit, "degrees Fahrenheit")
 
-print("constrain() examples")
+print("\nconstrain() examples")
 # Constrain a value to a range.
 def constrain_example(value, min_value, max_value):
     constrained_value = constrain(value, min_value, max_value)
@@ -45,5 +47,8 @@ def constrain_example(value, min_value, max_value):
 
 
 constrain_example(0, 1, 3)  # expects 1
+constrain_example(0, 3, 1)  # expects 1
 constrain_example(4, 1, 3)  # expects 3
+constrain_example(4, 3, 1)  # expects 3
 constrain_example(2, 2, 3)  # expects 2
+constrain_example(2, 3, 2)  # expects 2

tests/constrain_test.py

@@ -1,4 +1,5 @@
 # SPDX-FileCopyrightText: 2021 Dan Halbert for Adafruit Industries
+# SPDX-FileCopyrightText: 2021 James Carr
 #
 # SPDX-License-Identifier: Unlicense
 
@@ -10,3 +11,8 @@ def test_constrain():
     assert constrain(10, 1, 10) == 10
     assert constrain(0, 1, 10) == 1
     assert constrain(11, 1, 10) == 10
+
+    # Check out_min > out_max
+    assert constrain(5, 10, 0) == 5
+    assert constrain(-5, 10, 0) == 0
+    assert constrain(15, 10, 0) == 10

tests/map_range_test.py

@@ -13,6 +13,3 @@ def test_map_range():
     assert map_range(1, 10, 0, 0, 5) == 4.5
     assert map_range(1, 0, 10, 10, 0) == 9.0
     assert map_range(10, 1, 10, 1, 20) == 20.0
-    assert map_range(392, 32, 212, 0, 100) == 100.0
-    assert map_range(392, 32, 212, 0, 100, constrained=True) == 100.0
-    assert map_range(392, 32, 212, 0, 100, constrained=False) == 200.0

tests/unconstrained_map_range_test.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2021 James Carr
+#
+# SPDX-License-Identifier: Unlicense
+
+from adafruit_simplemath import unconstrained_map_range
+
+
+def test_unconstrained_map_range():
+    assert unconstrained_map_range(-40, 32, 212, 0, 100) == -40.0
+    assert unconstrained_map_range(50, 32, 212, 0, 100) == 10.0
+    assert unconstrained_map_range(392, 32, 212, 0, 100) == 200.0