archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-27 06:45:07 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

8301226: Add clamp() methods to java.lang.Math and to StrictMath

Browse source 
Reviewed-by: qamai, darcy
This commit is contained in:
Tagir F. Valeev 2023-02-14 05:39:07 +00:00
parent 13b1ebba27
commit 94e7cc8587
3 changed files with 500 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

89
src/java.base/share/classes/java/lang/StrictMath.java
View file

@ -1759,6 +1759,95 @@ public final class StrictMath {
return Math.min(a, b);
}
/**
* Clamps the value to fit between min and max. If the value is less
* than {@code min}, then {@code min} is returned. If the value is greater
* than {@code max}, then {@code max} is returned. Otherwise, the original
* value is returned.
* <p>
* While the original value of type long may not fit into the int type,
* the bounds have the int type, so the result always fits the int type.
* This allows to use method to safely cast long value to int with
* saturation.
*
* @param value value to clamp
* @param min minimal allowed value
* @param max maximal allowed value
* @return a clamped value that fits into {@code min..max} interval
* @throws IllegalArgumentException if {@code min > max}
*
* @since 21
*/
public static int clamp(long value, int min, int max) {
return Math.clamp(value, min, max);
}
/**
* Clamps the value to fit between min and max. If the value is less
* than {@code min}, then {@code min} is returned. If the value is greater
* than {@code max}, then {@code max} is returned. Otherwise, the original
* value is returned.
*
* @param value value to clamp
* @param min minimal allowed value
* @param max maximal allowed value
* @return a clamped value that fits into {@code min..max} interval
* @throws IllegalArgumentException if {@code min > max}
*
* @since 21
*/
public static long clamp(long value, long min, long max) {
return Math.clamp(value, min, max);
}
/**
* Clamps the value to fit between min and max. If the value is less
* than {@code min}, then {@code min} is returned. If the value is greater
* than {@code max}, then {@code max} is returned. Otherwise, the original
* value is returned. If value is NaN, the result is also NaN.
* <p>
* Unlike the numerical comparison operators, this method considers
* negative zero to be strictly smaller than positive zero.
* E.g., {@code clamp(-0.0, 0.0, 1.0)} returns 0.0.
*
* @param value value to clamp
* @param min minimal allowed value
* @param max maximal allowed value
* @return a clamped value that fits into {@code min..max} interval
* @throws IllegalArgumentException if either of {@code min} and {@code max}
* arguments is NaN, or {@code min > max}, or {@code min} is +0.0, and
* {@code max} is -0.0.
*
* @since 21
*/
public static double clamp(double value, double min, double max) {
return Math.clamp(value, min, max);
}
/**
* Clamps the value to fit between min and max. If the value is less
* than {@code min}, then {@code min} is returned. If the value is greater
* than {@code max}, then {@code max} is returned. Otherwise, the original
* value is returned. If value is NaN, the result is also NaN.
* <p>
* Unlike the numerical comparison operators, this method considers
* negative zero to be strictly smaller than positive zero.
* E.g., {@code clamp(-0.0f, 0.0f, 1.0f)} returns 0.0f.
*
* @param value value to clamp
* @param min minimal allowed value
* @param max maximal allowed value
* @return a clamped value that fits into {@code min..max} interval
* @throws IllegalArgumentException if either of {@code min} and {@code max}
* arguments is NaN, or {@code min > max}, or {@code min} is +0.0f, and
* {@code max} is -0.0f.
*
* @since 21
*/
public static float clamp(float value, float min, float max) {
return Math.clamp(value, min, max);
}
/**
* Returns the fused multiply add of the three arguments; that is,
* returns the exact product of the first two arguments summed