Math.clamp method?

[Jim Laskey]

+1

> On Jan 25, 2023, at 9:41 AM, Tagir Valeev <amaembo at gmail.com> wrote:
> 
> Hello!
> 
> Quite often it's necessary to clamp a numerical value to a given
> range, using the algorithm like this:
> int clampedValue = value > max ? max : value < min ? min : value;
> or probably
> int clampedValue = Math.max(min, Math.min(max, value));
> Some examples in wild: [1] [2]
> 
> These "algorithms" are verbose and error-prone. E.g., many years ago
> Math.max and Math.min were mixed in Jenkins CI implementation (later
> fixed in [3]). Static analyzers like SonarLint even implement a rule
> to catch such kind of mistake [4], but it cannot statically find a
> mistake if max and min values are not constant.
> 
> Having a library method for this algorithm will make the code more
> readable, and robust. Standard libraries of various languages tend to
> implement a function that encapsulates this algorithm. E.g., Kotlin
> coerseIn [5], C# Math.Clamp [6], Rust num::clamp [7].
> 
> I hereby propose to add a similar method to Java Math class. The
> signatures could be:
> public static int clamp(int value, int min, int max)
> public static long clamp(long value, long min, long max)
> public static double clamp(double value, double min, double max)
> public static float clamp(float value, float min, float max)
> 
> These methods should additionally check that min is not greater than
> max (throwing IllegalArgumentException). Probably IAE should be thrown
> as well if either min or max is NaN for floating point methods. It can
> be discussed what should happen if the value is NaN (I think returning
> NaN would be ok, but throwing an exception is also a possibility).
> 
> I can post CSR and contribute the implementation if Core Library team
> members agree that it's a good idea.
> 
> With best regards,
> Tagir Valeev.
> 
> [1] https://github.com/moneymod/moneymod/blob/4d2c7f5be40dbf392e75/src/main/java/wtf/moneymod/client/impl/ui/click/buttons/settings/SliderButton.java#L71
> [2] https://github.com/androidthings/experiment-expression-flower/blob/f0fd6090e0df1659bad/code/app/src/main/java/com/example/androidthings/VideoProcessor.java#L559
> [3] https://github.com/jenkinsci/jenkins/commit/e00f99251e0b
> [4] https://rules.sonarsource.com/java/RSPEC-3065
> [5] https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.ranges/coerce-in.html
> [6] https://learn.microsoft.com/en-us/dotnet/api/system.math.clamp?view=net-7.0
> [7] https://docs.rs/num/0.2.1/num/fn.clamp.html