sys: util: add SCALE() to change a value range

This permits to make a computation in a larger range to gain precision:

	int32_t tmp_in = SCALE(in, -100, 100, INT32_MIN, INT32_MAX);

Or convert between two unit systems:

	uint32_t fahrenheit = SCALE(celsius, 0, 100, 32, 212);

Signed-off-by: Josuah Demangeon <me@josuah.net>

Author: josuah

include/zephyr/sys/util.h

@@ -407,6 +407,30 @@ extern "C" {
 #define CLAMP(val, low, high) (((val) <= (low)) ? (low) : MIN(val, high))
 #endif
 
+/**
+ * @brief Linearly maps a value from one scale to another.
+ *
+ * A value is considered to fit on an input range, and is scaled to
+ * the same proportion of the output range.
+ * The ranges are described by their minimum and maximum values.
+ *
+ * @note To avoid an overflow, the number of bits of the input and output range
+ *       must be equal or lower to 61. For instance, an input range with min and max
+ *       values between INT8_MIN and INT8_MAX, then the output range must have
+ *       values within INT53_MIN and INT53_MAX.
+ *
+ * @note The size of the output range can be [0, 0].
+ *       The size of the input range must be greater than 0
+ *
+ * @param i The value to convert from the input range to the output range.
+ * @param imin The minimum value of the input range.
+ * @param imax The maximum value of the input range.
+ * @param omin The minimum value of the output range.
+ * @param omax The maximum value of the output range.
+ */
+#define SCALE(i, imin, imax, omin, omax) \
+	(((int64_t)(i) - (imin)) * ((int64_t)(omax) - (omin)) / ((int64_t)(imax) - (imin)) + (omin))
+
 /**
  * @brief Checks if a value is within range.
  *

tests/lib/sys_util/src/main.c

@@ -13,6 +13,73 @@
  * @{
  */
 
+ZTEST(sys_util, test_SCALE)
+{
+	/* Test for a few arbitrary values */
+	zassert_equal(SCALE(3, 0, 10, 0, 100), 30);
+	zassert_equal(SCALE(-3, -10, 0, -100, 0), -30);
+	zassert_equal(SCALE(10, -100, 100, -10, 10), 1);
+	zassert_equal(SCALE(0, -10, 40, -50, 0), -40);
+	zassert_equal(SCALE(0, -128, 127, 0, 2), 1);
+	zassert_equal(SCALE(5, -50, 5000, -1000, 10), -989);
+
+	/* Test for i = 1..60 and o = 60..1 */
+	for (int i = 1; i < 61; i++) {
+		int o = 61 - i;
+		int64_t imin = -(1ll << i);
+		int64_t imax = +(1ll << i);
+		int64_t omin = -(1ll << o);
+		int64_t omax = +(1ll << o);
+
+		/* Special case: the output range can be [0, 0] */
+
+		zassert_equal(SCALE(imin, imin, imax, 0, 0), 0);
+		zassert_equal(SCALE(0, imin, imax, 0, 0), 0);
+		zassert_equal(SCALE(imax, imin, imax, 0, 0), 0);
+
+		zassert_equal(SCALE(0, 0, imax, 0, 0), 0);
+		zassert_equal(SCALE(imax, 0, imax, 0, 0), 0);
+
+		zassert_equal(SCALE(imin, imin, 0, 0, 0), 0);
+		zassert_equal(SCALE(0, imin, 0, 0, 0), 0);
+
+		/* Test the extreme of all known cases */
+
+		zassert_equal(SCALE(imin, imin, imax, omin, omax), omin);
+		zassert_equal(SCALE(0, imin, imax, omin, omax), 0);
+		zassert_equal(SCALE(imax, imin, imax, omin, omax), omax);
+
+		zassert_equal(SCALE(0, 0, imax, omin, omax), omin);
+		zassert_equal(SCALE(imax, 0, imax, omin, omax), omax);
+
+		zassert_equal(SCALE(imin, imin, 0, omin, omax), omin);
+		zassert_equal(SCALE(0, imin, 0, omin, omax), omax);
+
+		zassert_equal(SCALE(imin, imin, imax, 0, omax), 0);
+		zassert_equal(SCALE(0, imin, imax, 0, omax), omax / 2);
+		zassert_equal(SCALE(imax, imin, imax, 0, omax), omax);
+
+		zassert_equal(SCALE(imin, imin, imax, omin, 0), omin);
+		zassert_equal(SCALE(0, imin, imax, omin, 0), omin / 2);
+		zassert_equal(SCALE(imax, imin, imax, omin, 0), 0);
+
+		zassert_equal(SCALE(0, 0, imax, 0, omax), 0);
+		zassert_equal(SCALE(imax, 0, imax, 0, omax), omax);
+
+		zassert_equal(SCALE(0, 0, imax, omin, 0), omin);
+		zassert_equal(SCALE(imax, 0, imax, omin, 0), 0);
+
+		zassert_equal(SCALE(imin, imin, 0, 0, omax), 0);
+		zassert_equal(SCALE(0, imin, 0, 0, omax), omax);
+
+		zassert_equal(SCALE(imin, imin, 0, omin, 0), omin);
+		zassert_equal(SCALE(0, imin, 0, omin, 0), 0);
+
+		zassert_equal(SCALE(0, 0, imax, 0, omax), 0);
+		zassert_equal(SCALE(imax, 0, imax, 0, omax), omax);
+	}
+}
+
 /**
  * @brief Test wait_for works as expected with typical use cases
  *
@@ -71,7 +138,6 @@ ZTEST(sys_util, test_NUM_VA_ARGS_LESS_1)
  * @}
  */
 
-
 /**
  * @defgroup sys_util_tests Sys Util Tests
  * @ingroup all_tests