Merge pull request #62377 from skyoct/feat/func_clamp

support clamp function

docs/en/sql-reference/functions/conditional-functions.md

@@ -234,3 +234,34 @@ SELECT least(toDateTime32(now() + toIntervalDay(1)), toDateTime64(now(), 3))
 :::note
 The type returned is a DateTime64 as the DataTime32 must be promoted to 64 bit for the comparison.
 :::
+
+## clamp
+
+Constrain the return value between A and B.
+
+**Syntax**
+
+``` sql
+clamp(value, min, max)
+```
+
+**Arguments**
+
+- `value` – Input value.
+- `min` – Limit the lower bound.
+- `max` – Limit the upper bound.
+
+**Returned values**
+
+If the value is less than the minimum value, return the minimum value; if it is greater than the maximum value, return the maximum value; otherwise, return the current value.
+
+Examples:
+
+```sql
+SELECT clamp(1, 2, 3) result,  toTypeName(result) type;
+```
+```response
+┌─result─┬─type────┐
+│      2 │ Float64 │
+└────────┴─────────┘
+```

src/Functions/clamp.cpp

@@ -0,0 +1,69 @@
+#include <Functions/IFunction.h>
+#include <Functions/FunctionFactory.h>
+#include <Functions/FunctionHelpers.h>
+#include <DataTypes/getLeastSupertype.h>
+#include <Interpreters/castColumn.h>
+#include <Interpreters/Context.h>
+
+namespace DB
+{
+
+namespace ErrorCodes
+{
+    extern const int NUMBER_OF_ARGUMENTS_DOESNT_MATCH;
+    extern const int BAD_ARGUMENTS;
+}
+
+
+class FunctionClamp : public IFunction
+{
+
+public:
+    static constexpr auto name = "clamp";
+
+    String getName() const override { return name; }
+    size_t getNumberOfArguments() const override { return 3; }
+    bool useDefaultImplementationForConstants() const override { return true; }
+    bool isSuitableForShortCircuitArgumentsExecution(const DataTypesWithConstInfo & /*arguments*/) const override { return false; }
+    static FunctionPtr create(ContextPtr) { return std::make_shared<FunctionClamp>(); }
+
+    DataTypePtr getReturnTypeImpl(const DataTypes & types) const override
+    {
+        if (types.size() != 3)
+            throw Exception(ErrorCodes::NUMBER_OF_ARGUMENTS_DOESNT_MATCH, "Function {} requires 3 arguments", getName());
+
+        return getLeastSupertype(types);
+    }
+
+    ColumnPtr executeImpl(const ColumnsWithTypeAndName & arguments, const DataTypePtr & result_type, size_t input_rows_count) const override
+    {
+        size_t arg_size = arguments.size();
+        Columns converted_columns(arg_size);
+        for (size_t arg = 0; arg < arg_size; ++arg)
+            converted_columns[arg] = castColumn(arguments[arg], result_type)->convertToFullColumnIfConst();
+
+        auto result_column = result_type->createColumn();
+        for (size_t row_num = 0; row_num < input_rows_count; ++row_num)
+        {
+            if (converted_columns[1]->compareAt(row_num, row_num, *converted_columns[2], 1) > 0)
+                throw Exception(ErrorCodes::BAD_ARGUMENTS, "The minimum value cannot be greater than the maximum value for function {}", getName());
+
+            size_t best_arg = 0;
+            if (converted_columns[1]->compareAt(row_num, row_num, *converted_columns[best_arg], 1) > 0)
+                best_arg = 1;
+            else if (converted_columns[2]->compareAt(row_num, row_num, *converted_columns[best_arg], 1) < 0)
+                best_arg = 2;
+
+            result_column->insertFrom(*converted_columns[best_arg], row_num);
+        }
+
+        return result_column;
+    }
+
+};
+
+REGISTER_FUNCTION(Clamp)
+{
+    factory.registerFunction<FunctionClamp>();
+}
+}

tests/queries/0_stateless/02415_all_new_functions_must_be_documented.reference

@@ -201,6 +201,7 @@ cbrt
 ceil
 char
 cityHash64
+clamp
 coalesce
 concat
 concatAssumeInjective

tests/queries/0_stateless/03036_clamp.reference

@@ -0,0 +1,14 @@
+10
+20
+15
+b
+0
+['hello']
+-1
+234
+\N
+\N
+5
+0
+1
+2

tests/queries/0_stateless/03036_clamp.sql

@@ -0,0 +1,15 @@
+SELECT clamp(1, 10, 20);
+SELECT clamp(30, 10, 20);
+SELECT clamp(15, 10, 20);
+SELECT clamp('a', 'b', 'c');
+SELECT clamp(today(), yesterday() - 10, yesterday() + 10) - today();
+SELECT clamp([], ['hello'], ['world']);
+SELECT clamp(-1., -1000., 18446744073709551615.);
+SELECT clamp(toNullable(123), 234, 456);
+select clamp(1, null, 5);
+select clamp(1, 6, null);
+select clamp(1, 5, nan);
+select clamp(toInt64(number), toInt64(number-1), toInt64(number+1)) from numbers(3);
+select clamp(number, number-1, number+1) from numbers(3);   -- { serverError NO_COMMON_TYPE }
+select clamp(1, 3, 2);   -- { serverError BAD_ARGUMENTS } 
+select clamp(1, data[1], data[2])from (select arrayJoin([[1, 2], [2,3], [3,2], [4, 4]]) as data);   -- { serverError BAD_ARGUMENTS }