sys: util: rename Z_MIN Z_MAX Z_CLAMP to min max and clamp

Rename these three macros to an unprefixed lower-case variant. This is
normally not done for Zephyr macros (see container_of) but in this case
it seems like a good idea to adopt the lowercase names to:

1. have the same convention as the equivalent Linux macros, helping devs
   working cross project recognizing (mis)use patterns.
2. make it somewhat intuitive that the lowercase ones are meant to be
   used in functions while the uppercase ones are to be used for static
   evaluation.

Add few c++ guards to avoid colliding with std::min and std::max.

Signed-off-by: Fabio Baltieri <[email protected]>

Author: fabiobaltieri

doc/releases/migration-guide-4.3.rst

@@ -38,6 +38,9 @@ Base Libraries
   been moved from ``util.h`` to a separate
   :zephyr_file:`include/zephyr/sys/util_utf8.h` file.
 
+* ``Z_MIN``, ``Z_MAX`` and ``Z_CLAMP`` macros have been renamed to
+  :c:macro:`min` :c:macro:`max` and :c:macro:`clamp`.
+
 Boards
 ******
 

drivers/usb/device/usb_dc_sam0.c

@@ -608,7 +608,7 @@ int usb_dc_ep_write(uint8_t ep, const uint8_t *buf, uint32_t len, uint32_t *ret_
 		return -EAGAIN;
 	}
 
-	len = Z_MIN(len, capacity);
+	len = min(len, capacity);
 
 	/* Note that this code does not use the hardware's
 	 * multi-packet and automatic zero-length packet features as

include/zephyr/dsp/utils.h

@@ -116,7 +116,7 @@ extern "C" {
  * @return The converted Q7 fixed-point value.
  */
 #define Z_SHIFT_F32_TO_Q7(src, m)                                                                  \
-	((q7_t)Z_CLAMP((int32_t)(src * (1U << 7)) >> m, INT8_MIN, INT8_MAX))
+	((q7_t)clamp((int32_t)(src * (1U << 7)) >> m, INT8_MIN, INT8_MAX))
 
 /**
  * @brief Convert a floating-point (float32_t) value to a Q15 fixed-point value with a right shift.
@@ -126,7 +126,7 @@ extern "C" {
  * @return The converted Q15 fixed-point value.
  */
 #define Z_SHIFT_F32_TO_Q15(src, m)                                                                 \
-	((q15_t)Z_CLAMP((int32_t)(src * (1U << 15)) >> m, INT16_MIN, INT16_MAX))
+	((q15_t)clamp((int32_t)(src * (1U << 15)) >> m, INT16_MIN, INT16_MAX))
 
 /**
  * @brief Convert a floating-point (float32_t) value to a Q31 fixed-point value with a right shift.
@@ -136,7 +136,7 @@ extern "C" {
  * @return The converted Q31 fixed-point value.
  */
 #define Z_SHIFT_F32_TO_Q31(src, m)                                                                 \
-	((q31_t)Z_CLAMP((int64_t)(src * (1U << 31)) >> m, INT32_MIN, INT32_MAX))
+	((q31_t)clamp((int64_t)(src * (1U << 31)) >> m, INT32_MIN, INT32_MAX))
 
 /**
  * @brief Convert a floating-point (float64_t) value to a Q7 fixed-point value with a right shift.
@@ -146,7 +146,7 @@ extern "C" {
  * @return The converted Q7 fixed-point value.
  */
 #define Z_SHIFT_F64_TO_Q7(src, m)                                                                  \
-	((q7_t)Z_CLAMP((int32_t)(src * (1U << 7)) >> m, INT8_MIN, INT8_MAX))
+	((q7_t)clamp((int32_t)(src * (1U << 7)) >> m, INT8_MIN, INT8_MAX))
 
 /**
  * @brief Convert a floating-point (float64_t) value to a Q15 fixed-point value with a right shift.
@@ -156,7 +156,7 @@ extern "C" {
  * @return The converted Q15 fixed-point value.
  */
 #define Z_SHIFT_F64_TO_Q15(src, m)                                                                 \
-	((q15_t)Z_CLAMP((int32_t)(src * (1U << 15)) >> m, INT16_MIN, INT16_MAX))
+	((q15_t)clamp((int32_t)(src * (1U << 15)) >> m, INT16_MIN, INT16_MAX))
 
 /**
  * @brief Convert a floating-point (float64_t) value to a Q31 fixed-point value with a right shift.
@@ -166,7 +166,7 @@ extern "C" {
  * @return The converted Q31 fixed-point value.
  */
 #define Z_SHIFT_F64_TO_Q31(src, m)                                                                 \
-	((q31_t)Z_CLAMP((int64_t)(src * (1U << 31)) >> m, INT32_MIN, INT32_MAX))
+	((q31_t)clamp((int64_t)(src * (1U << 31)) >> m, INT32_MIN, INT32_MAX))
 
 /**
  * @}

include/zephyr/sys/util.h

@@ -376,8 +376,8 @@ extern "C" {
 /**
  * @brief Obtain the maximum of two values.
  *
- * @note Arguments are evaluated twice. Use Z_MAX for a GCC-only, single
- * evaluation version
+ * @note Arguments are evaluated twice. Use @ref max for a single evaluation
+ * version.
  *
  * @param a First value.
  * @param b Second value.
@@ -387,28 +387,30 @@ extern "C" {
 #define MAX(a, b) (((a) > (b)) ? (a) : (b))
 #endif
 
+#ifndef __cplusplus
 /** @brief Return larger value of two provided expressions.
  *
  * Macro ensures that expressions are evaluated only once.
  *
  * @note Macro has limited usage compared to the standard macro as it cannot be
  *	 used:
- *	 - to generate constant integer, e.g. __aligned(Z_MAX(4,5))
- *	 - static variable, e.g. array like static uint8_t array[Z_MAX(...)];
+ *	 - to generate constant integer, e.g. __aligned(max(4,5))
+ *	 - static variable, e.g. array like static uint8_t array[max(...)];
  */
-#define Z_MAX(a, b) ({ \
+#define max(a, b) ({ \
 		/* random suffix to avoid naming conflict */ \
 		__typeof__(a) _value_a_ = (a); \
 		__typeof__(b) _value_b_ = (b); \
 		(_value_a_ > _value_b_) ? _value_a_ : _value_b_; \
 	})
+#endif
 
 #ifndef MIN
 /**
  * @brief Obtain the minimum of two values.
  *
- * @note Arguments are evaluated twice. Use Z_MIN for a GCC-only, single
- * evaluation version
+ * @note Arguments are evaluated twice. Use @ref min for a single evaluation
+ * version.
  *
  * @param a First value.
  * @param b Second value.
@@ -418,17 +420,19 @@ extern "C" {
 #define MIN(a, b) (((a) < (b)) ? (a) : (b))
 #endif
 
+#ifndef __cplusplus
 /** @brief Return smaller value of two provided expressions.
  *
- * Macro ensures that expressions are evaluated only once. See @ref Z_MAX for
+ * Macro ensures that expressions are evaluated only once. See @ref max for
  * macro limitations.
  */
-#define Z_MIN(a, b) ({ \
+#define min(a, b) ({ \
 		/* random suffix to avoid naming conflict */ \
 		__typeof__(a) _value_a_ = (a); \
 		__typeof__(b) _value_b_ = (b); \
 		(_value_a_ < _value_b_) ? _value_a_ : _value_b_; \
 	})
+#endif
 
 #ifndef MAX_FROM_LIST
 /**
@@ -555,8 +559,8 @@ extern "C" {
 /**
  * @brief Clamp a value to a given range.
  *
- * @note Arguments are evaluated multiple times. Use Z_CLAMP for a GCC-only,
- * single evaluation version.
+ * @note Arguments are evaluated multiple times. Use @ref clamp for a single
+ * evaluation version.
  *
  * @param val Value to be clamped.
  * @param low Lowest allowed value (inclusive).
@@ -567,12 +571,13 @@ extern "C" {
 #define CLAMP(val, low, high) (((val) <= (low)) ? (low) : MIN(val, high))
 #endif
 
+#ifndef __cplusplus
 /** @brief Return a value clamped to a given range.
  *
- * Macro ensures that expressions are evaluated only once. See @ref Z_MAX for
+ * Macro ensures that expressions are evaluated only once. See @ref max for
  * macro limitations.
  */
-#define Z_CLAMP(val, low, high) ({                                             \
+#define clamp(val, low, high) ({                                               \
 		/* random suffix to avoid naming conflict */                   \
 		__typeof__(val) _value_val_ = (val);                           \
 		__typeof__(low) _value_low_ = (low);                           \
@@ -581,6 +586,7 @@ extern "C" {
 		(_value_val_ > _value_high_) ? _value_high_ :                  \
 					       _value_val_;                    \
 	})
+#endif
 
 /**
  * @brief Checks if a value is within range.

subsys/net/lib/lwm2m/lwm2m_rd_client.c

@@ -1176,7 +1176,7 @@ static int64_t next_rx_off(void)
 /** Return timestamp to next even whether it is RX_OFF or update event */
 static int64_t calc_next_event(void)
 {
-	return Z_MIN(next_update(), next_rx_off());
+	return min(next_update(), next_rx_off());
 }
 
 static void sm_registration_done(void)

subsys/shell/shell.c

@@ -346,7 +346,7 @@ static void find_completion_candidates(const struct shell *sh,
 		is_candidate = is_completion_candidate(candidate->syntax,
 						incompl_cmd, incompl_cmd_len);
 		if (is_candidate) {
-			*longest = Z_MAX(strlen(candidate->syntax), *longest);
+			*longest = max(strlen(candidate->syntax), *longest);
 			if (*cnt == 0) {
 				*first_idx = idx;
 			}

subsys/shell/shell_help.c

@@ -187,7 +187,7 @@ void z_shell_help_subcmd_print(const struct shell *sh,
 
 	/* Searching for the longest subcommand to print. */
 	while ((entry = z_shell_cmd_get(parent, idx++, &dloc)) != NULL) {
-		longest = Z_MAX(longest, z_shell_strlen(entry->syntax));
+		longest = max(longest, z_shell_strlen(entry->syntax));
 	}
 
 	/* No help to print */

tests/unit/util/main.c

@@ -245,26 +245,31 @@ static int inc_func(bool cleanup)
 	return a++;
 }
 
-/* Test checks if @ref Z_MAX, @ref Z_MIN and @ref Z_CLAMP return correct result
+/* Test checks if @ref max, @ref min and @ref clamp return correct result
  * and perform single evaluation of input arguments.
  */
-ZTEST(util, test_z_max_z_min_z_clamp) {
-	zassert_equal(Z_MAX(inc_func(true), 0), 1, "Unexpected macro result");
-	/* Z_MAX should have call inc_func only once */
+ZTEST(util, test_max_min_clamp) {
+#ifdef __cplusplus
+	/* C++ has its own std::min() and std::max(), min and max are not available. */
+	ztest_test_skip();
+#else
+	zassert_equal(max(inc_func(true), 0), 1, "Unexpected macro result");
+	/* max should have call inc_func only once */
 	zassert_equal(inc_func(false), 2, "Unexpected return value");
 
-	zassert_equal(Z_MIN(inc_func(false), 2), 2, "Unexpected macro result");
-	/* Z_MIN should have call inc_func only once */
+	zassert_equal(min(inc_func(false), 2), 2, "Unexpected macro result");
+	/* min should have call inc_func only once */
 	zassert_equal(inc_func(false), 4, "Unexpected return value");
 
-	zassert_equal(Z_CLAMP(inc_func(false), 1, 3), 3, "Unexpected macro result");
-	/* Z_CLAMP should have call inc_func only once */
+	zassert_equal(clamp(inc_func(false), 1, 3), 3, "Unexpected macro result");
+	/* clamp should have call inc_func only once */
 	zassert_equal(inc_func(false), 6, "Unexpected return value");
 
-	zassert_equal(Z_CLAMP(inc_func(false), 10, 15), 10,
+	zassert_equal(clamp(inc_func(false), 10, 15), 10,
 		      "Unexpected macro result");
-	/* Z_CLAMP should have call inc_func only once */
+	/* clamp should have call inc_func only once */
 	zassert_equal(inc_func(false), 8, "Unexpected return value");
+#endif
 }
 
 ZTEST(util, test_max_from_list_macro) {