docs: Add microbit.scale(value, from_, to) function. (#762)

microbit-carlos · web-flow · commit 1435b6ae9dac · 2022-08-31T19:55:40.000+01:00
diff --git a/docs/microbit.rst b/docs/microbit.rst
@@ -31,6 +31,25 @@ Functions
     :returns: The number of milliseconds since the board was switched on or
         restarted.
 
+.. py:function:: scale(value, from_, to)
+
+    Converts a value from a range to another range.
+
+    For example, to convert 30 degrees from Celsius to Fahrenheit::
+
+        temp_fahrenheit = scale(30, from_=(0, 100), to=(32, 212))
+
+    This can be useful to convert values between inputs and outputs,
+    for example an accelerometer x value to a speaker volume.
+
+    Negative scaling is also supported, for example
+    ``scale(25, from_=(0, 100), to=(0, -200))`` will return ``-50``.
+
+    :param value: A number to convert.
+    :param from_: A tuple to define the range to convert from.
+    :param to: A tuple to define the range to convert to.
+
+    :returns: The ``value`` converted to the ``to`` range.
 
 .. py:function:: sleep(n)
 
diff --git a/docs/microbit_micropython_api.rst b/docs/microbit_micropython_api.rst
@@ -16,6 +16,10 @@ There are a few functions available directly::
     sleep(ms)
     # returns the number of milliseconds since the micro:bit was last switched on.
     running_time()
+    # returns the temperature in Celcius
+    temperature()
+    # converts a number from one scale of values to another
+    scale(value_to_convert, from_=(min_value, max_value), to=(min_value, max_value))
     # makes the micro:bit enter panic mode (this usually happens when the DAL runs
     # out of memory, and causes a sad face to be drawn on the display). The error
     # code can be any arbitrary integer value.
