From ab5d8f67aee0c631b3fdf7d6cae94aa71fb4b60c Mon Sep 17 00:00:00 2001
From: Clyde Stubbs <2366188+clydebarrow@users.noreply.github.com>
Date: Thu, 6 Nov 2025 12:48:02 +1000
Subject: [PATCH] [core] Add helper functions for clamp_at_... (#10387)

---
 esphome/core/helpers.h                          | 16 +++++++++++++++-
 tests/components/esp32/common.yaml              | 13 +++++++++++++
 tests/components/esp8266/test.esp8266-ard.yaml  | 13 +++++++++++++
 tests/components/host/common.yaml               |  7 +++++++
 tests/components/libretiny/test.bk72xx-ard.yaml | 13 +++++++++++++
 tests/components/nrf52/test.nrf52-adafruit.yaml | 10 ++++++++++
 tests/components/rp2040/test.rp2040-ard.yaml    | 13 +++++++++++++
 7 files changed, 84 insertions(+), 1 deletion(-)
 create mode 100644 tests/components/esp32/common.yaml
 create mode 100644 tests/components/esp8266/test.esp8266-ard.yaml
 create mode 100644 tests/components/libretiny/test.bk72xx-ard.yaml
 create mode 100644 tests/components/rp2040/test.rp2040-ard.yaml

diff --git a/esphome/core/helpers.h b/esphome/core/helpers.h
index 660874ed1a..48af7f674a 100644
--- a/esphome/core/helpers.h
+++ b/esphome/core/helpers.h
@@ -12,6 +12,7 @@
 #include <string>
 #include <type_traits>
 #include <vector>
+#include <concepts>
 
 #include "esphome/core/optional.h"
 
@@ -1169,7 +1170,20 @@ template<class T> class RAMAllocator {
 
 template<class T> using ExternalRAMAllocator = RAMAllocator<T>;
 
-/// @}
+/**
+ * Functions to constrain the range of arithmetic values.
+ */
+
+template<std::totally_ordered T> T clamp_at_least(T value, T min) {
+  if (value < min)
+    return min;
+  return value;
+}
+template<std::totally_ordered T> T clamp_at_most(T value, T max) {
+  if (value > max)
+    return max;
+  return value;
+}
 
 /// @name Internal functions
 ///@{
diff --git a/tests/components/esp32/common.yaml b/tests/components/esp32/common.yaml
new file mode 100644
index 0000000000..039a261016
--- /dev/null
+++ b/tests/components/esp32/common.yaml
@@ -0,0 +1,13 @@
+logger:
+  level: VERBOSE
+
+esphome:
+  on_boot:
+    - lambda: |-
+        int x = 100;
+        x = clamp(x, 50, 90);
+        assert(x == 90);
+        x = clamp_at_least(x, 95);
+        assert(x == 95);
+        x = clamp_at_most(x, 40);
+        assert(x == 40);
diff --git a/tests/components/esp8266/test.esp8266-ard.yaml b/tests/components/esp8266/test.esp8266-ard.yaml
new file mode 100644
index 0000000000..039a261016
--- /dev/null
+++ b/tests/components/esp8266/test.esp8266-ard.yaml
@@ -0,0 +1,13 @@
+logger:
+  level: VERBOSE
+
+esphome:
+  on_boot:
+    - lambda: |-
+        int x = 100;
+        x = clamp(x, 50, 90);
+        assert(x == 90);
+        x = clamp_at_least(x, 95);
+        assert(x == 95);
+        x = clamp_at_most(x, 40);
+        assert(x == 40);
diff --git a/tests/components/host/common.yaml b/tests/components/host/common.yaml
index 5c329c8245..d5c8446ae8 100644
--- a/tests/components/host/common.yaml
+++ b/tests/components/host/common.yaml
@@ -15,3 +15,10 @@ esphome:
         static const uint8_t my_addr[6] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};
         if (!mac_address_is_valid(my_addr))
           ESP_LOGD("test", "Invalid mac address %X", my_addr[0]); // etc.
+        int x = 100;
+        x = clamp(x, 50, 90);
+        assert(x == 90);
+        x = clamp_at_least(x, 95);
+        assert(x == 95);
+        x = clamp_at_most(x, 40);
+        assert(x == 40);
diff --git a/tests/components/libretiny/test.bk72xx-ard.yaml b/tests/components/libretiny/test.bk72xx-ard.yaml
new file mode 100644
index 0000000000..039a261016
--- /dev/null
+++ b/tests/components/libretiny/test.bk72xx-ard.yaml
@@ -0,0 +1,13 @@
+logger:
+  level: VERBOSE
+
+esphome:
+  on_boot:
+    - lambda: |-
+        int x = 100;
+        x = clamp(x, 50, 90);
+        assert(x == 90);
+        x = clamp_at_least(x, 95);
+        assert(x == 95);
+        x = clamp_at_most(x, 40);
+        assert(x == 40);
diff --git a/tests/components/nrf52/test.nrf52-adafruit.yaml b/tests/components/nrf52/test.nrf52-adafruit.yaml
index 3fe80209b6..cf704ecceb 100644
--- a/tests/components/nrf52/test.nrf52-adafruit.yaml
+++ b/tests/components/nrf52/test.nrf52-adafruit.yaml
@@ -1,3 +1,13 @@
+esphome:
+  on_boot:
+    - lambda: |-
+        int x = 100;
+        x = clamp(x, 50, 90);
+        assert(x == 90);
+        x = clamp_at_least(x, 95);
+        assert(x == 95);
+        x = clamp_at_most(x, 40);
+        assert(x == 40);
 nrf52:
   dfu:
     reset_pin:
diff --git a/tests/components/rp2040/test.rp2040-ard.yaml b/tests/components/rp2040/test.rp2040-ard.yaml
new file mode 100644
index 0000000000..039a261016
--- /dev/null
+++ b/tests/components/rp2040/test.rp2040-ard.yaml
@@ -0,0 +1,13 @@
+logger:
+  level: VERBOSE
+
+esphome:
+  on_boot:
+    - lambda: |-
+        int x = 100;
+        x = clamp(x, 50, 90);
+        assert(x == 90);
+        x = clamp_at_least(x, 95);
+        assert(x == 95);
+        x = clamp_at_most(x, 40);
+        assert(x == 40);