Add library code and tests

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: 2021 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+name: Run Tests
+
+on: [pull_request, push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Set up Python 3.6
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.6
+    - name: Versions
+      run: |
+        python3 --version
+    - name: Checkout Current Repo
+      uses: actions/checkout@v1
+      with:
+        submodules: true
+    - name: Install pytest
+      run: pip install pytest
+    - name: Install locally
+      run: pip install .
+    - name: Run tests
+      run: pytest

README.rst

@@ -32,12 +32,6 @@ This is easily achieved by downloading
 
 Installing from PyPI
 =====================
-.. note:: This library is not available on PyPI yet. Install documentation is included
-   as a standard element. Stay tuned for PyPI availability!
-
-.. todo:: Remove the above note if PyPI version is/will be available at time of release.
-   If the library is not planned for PyPI, remove the entire 'Installing from PyPI' section.
-
 On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
 PyPI <https://pypi.org/project/adafruit-circuitpython-simplemath/>`_. To install for current user:
 
@@ -60,11 +54,6 @@ To install in a virtual environment in your current project:
     source .env/bin/activate
     pip3 install adafruit-circuitpython-simplemath
 
-Usage Example
-=============
-
-.. todo:: Add a quick, simple example. It and other examples should live in the examples folder and be included in docs/examples.rst.
-
 Contributing
 ============
 

adafruit_simplemath.py

@@ -1,5 +1,4 @@
-# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
-# SPDX-FileCopyrightText: Copyright (c) 2021 Adafruit Industries for Adafruit Industries LLC
+# SPDX-FileCopyrightText: Copyright (c) 2021 Dan Halbert for Adafruit Industries LLC
 #
 # SPDX-License-Identifier: MIT
 """
@@ -14,23 +13,59 @@
 Implementation Notes
 --------------------
 
-**Hardware:**
-
-.. todo:: Add links to any specific hardware product page(s), or category page(s). Use unordered list & hyperlink rST
-   inline format: "* `Link Text <url>`_"
-
 **Software and Dependencies:**
 
 * Adafruit CircuitPython firmware for the supported boards:
   https://github.com/adafruit/circuitpython/releases
-
-.. todo:: Uncomment or remove the Bus Device and/or the Register library dependencies based on the library's use of either.
-
-# * Adafruit's Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
-# * Adafruit's Register library: https://github.com/adafruit/Adafruit_CircuitPython_Register
 """
 
-# imports
-
 __version__ = "0.0.0-auto.0"
 __repo__ = "https://github.com/adafruit/Adafruit_CircuitPython_SimpleMath.git"
+
+
+def 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 ``map()`` function,
+    but returns a floating point result, and constrains the output value to be between
+    ``out_min`` and ``out_max``.
+    If ``in_min`` is greater than ``in_max`` or ``out_min`` is greater than ``out_max``,
+    the corresponding range is reversed, allowing, for example, mapping a range of 0-10 to 50-0.
+
+    :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
+    if out_min <= out_max:
+        return max(min(mapped, out_max), out_min)
+    return min(max(mapped, out_max), out_min)
+
+
+def constrain(x: float, out_min: float, out_max: float) -> float:
+    """Constrains ``x`` to be within the inclusive range [``out_min``, ``out_max``].
+    Sometimes called ``clip`` or ``clamp`` in other libraries.
+    ``out_min`` should be less than or equal to ``out_max``.
+    If ``x`` is less than ``out_min``, return ``out_min``.
+    If ``x`` is greater than ``out_max``, return ``out_max``.
+    Otherwise just return ``x``.
+
+    :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))

docs/index.rst

@@ -20,18 +20,6 @@ Table of Contents
 
     api
 
-.. toctree::
-    :caption: Tutorials
-
-.. todo:: Add any Learn guide links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
-
-.. toctree::
-    :caption: Related Products
-
-.. todo:: Add any product links here. If there are none, then simply delete this todo and leave
-    the toctree above for use later.
-
 .. toctree::
     :caption: Other Links
 

examples/simplemath_simpletest.py

@@ -1,3 +1,13 @@
 # SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
 #
 # SPDX-License-Identifier: Unlicense
+
+from adafruit_simplemath import map_range, constrain
+
+# Map, say, a sensor value, from a range of 0-255 to 0-1023.
+print(map_range(30, 0, 255, 0, 1023))
+
+# Constrain a value to a range.
+print(constrain(0, 1, 3))  # prints 1
+print(constrain(4, 1, 3))  # prints 3
+print(constrain(2, 2, 3))  # prints 2

tests/constrain_test.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: 2021 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+from adafruit_simplemath import constrain
+
+
+def test_constrain():
+    assert constrain(1, 1, 10) == 1
+    assert constrain(10, 1, 10) == 10
+    assert constrain(0, 1, 10) == 1
+    assert constrain(11, 1, 10) == 10

tests/map_range_test.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2021 Dan Halbert for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+from adafruit_simplemath import map_range
+
+
+def test_map_range():
+    assert map_range(1, 0, 10, 0, 100) == 10.0
+    assert map_range(-1, 0, 10, 0, 100) == 0
+    assert map_range(11, 0, 10, 0, 100) == 100
+    assert map_range(5, 0, 10, 0, 5) == 2.5
+    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