Add {Int,Long}Math.saturatedAbs.

RELNOTES=Add {Int,Long}Math.saturatedAbs.
PiperOrigin-RevId: 755417595

Author: lowasser

android/guava-tests/test/com/google/common/math/IntMathTest.java

@@ -692,6 +692,17 @@ public void testIsPrime() {
     }
   }
 
+  public void testSaturatedAbs() {
+    assertEquals(Integer.MAX_VALUE, IntMath.saturatedAbs(Integer.MIN_VALUE));
+    assertEquals(Integer.MAX_VALUE, IntMath.saturatedAbs(Integer.MAX_VALUE));
+    assertEquals(Integer.MAX_VALUE, IntMath.saturatedAbs(-Integer.MAX_VALUE));
+    assertEquals(0, IntMath.saturatedAbs(0));
+    assertEquals(1, IntMath.saturatedAbs(1));
+    assertEquals(1, IntMath.saturatedAbs(-1));
+    assertEquals(10, IntMath.saturatedAbs(10));
+    assertEquals(10, IntMath.saturatedAbs(-10));
+  }
+
   private static int force32(int value) {
     // GWT doesn't consistently overflow values to make them 32-bit, so we need to force it.
     return value & 0xffffffff;

android/guava-tests/test/com/google/common/math/LongMathTest.java

@@ -923,6 +923,17 @@ public void testRoundToDoubleAgainstBigIntegerUnnecessary() {
     }
   }
 
+  public void testSaturatedAbs() {
+    assertEquals(Long.MAX_VALUE, LongMath.saturatedAbs(Long.MIN_VALUE));
+    assertEquals(Long.MAX_VALUE, LongMath.saturatedAbs(Long.MAX_VALUE));
+    assertEquals(Long.MAX_VALUE, LongMath.saturatedAbs(-Long.MAX_VALUE));
+    assertEquals(0, LongMath.saturatedAbs(0));
+    assertEquals(1, LongMath.saturatedAbs(1));
+    assertEquals(1, LongMath.saturatedAbs(-1));
+    assertEquals(10, LongMath.saturatedAbs(10));
+    assertEquals(10, LongMath.saturatedAbs(-10));
+  }
+
   private static void failFormat(String template, Object... args) {
     assertWithMessage(template, args).fail();
   }

android/guava/src/com/google/common/math/IntMath.java

@@ -717,5 +717,35 @@ public static boolean isPrime(int n) {
     return LongMath.isPrime(n);
   }
 
+  /**
+   * Returns the closest representable {@code int} to the absolute value of {@code x}.
+   *
+   * <p>This is the same thing as the true absolute value of {@code x} except in the case when
+   * {@code x} is {@link Integer#MIN_VALUE}, in which case this returns {@link Integer#MAX_VALUE}.
+   * (Note that {@code Integer.MAX_VALUE} is mathematically equal to {@code -Integer.MIN_VALUE -
+   * 1}.)
+   *
+   * <p>There are three common APIs for determining the absolute value of an integer, all of which
+   * behave identically except when passed {@code Integer.MIN_VALUE}. Those methods are:
+   *
+   * <ul>
+   *   <li>{@link Math#abs(int)}, which returns {@code Integer.MIN_VALUE} when passed {@code
+   *       Integer.MIN_VALUE}
+   *   <li>{@link Math#absExact(int)}, which throws {@link ArithmeticException} when passed {@code
+   *       Integer.MIN_VALUE}
+   *   <li>this method, {@code IntMath.saturatedAbs(int)}, which returns {@code Integer.MAX_VALUE}
+   *       when passed {@code Integer.MIN_VALUE}
+   * </ul>
+   *
+   * <p>Note that if your only goal is to turn a well-distributed `int` (such as a random number or
+   * hash code) into a well-distributed nonnegative number, the most even distribution is achieved
+   * not by this method or other absolute value methods, but by {@code x & Integer.MAX_VALUE}.
+   *
+   * @since NEXT
+   */
+  public static int saturatedAbs(int x) {
+    return (x == Integer.MIN_VALUE) ? Integer.MAX_VALUE : Math.abs(x);
+  }
+
   private IntMath() {}
 }

android/guava/src/com/google/common/math/LongMath.java

@@ -1345,5 +1345,34 @@ public static double roundToDouble(long x, RoundingMode mode) {
     throw new AssertionError("impossible");
   }
 
+  /**
+   * Returns the closest representable {@code long} to the absolute value of {@code x}.
+   *
+   * <p>This is the same thing as the true absolute value of {@code x} except in the case when
+   * {@code x} is {@link Long#MIN_VALUE}, in which case this returns {@link Long#MAX_VALUE}. (Note
+   * that {@code Long.MAX_VALUE} is mathematically equal to {@code -Long.MIN_VALUE - 1}.)
+   *
+   * <p>There are three common APIs for determining the absolute value of a long, all of which
+   * behave identically except when passed {@code Long.MIN_VALUE}. Those methods are:
+   *
+   * <ul>
+   *   <li>{@link Math#abs(long)}, which returns {@code Long.MIN_VALUE} when passed {@code
+   *       Long.MIN_VALUE}
+   *   <li>{@link Math#absExact(long)}, which throws {@link ArithmeticException} when passed {@code
+   *       Long.MIN_VALUE}
+   *   <li>this method, {@code LongMath.saturatedAbs(long)}, which returns {@code Long.MAX_VALUE}
+   *       when passed {@code Long.MIN_VALUE}
+   * </ul>
+   *
+   * <p>Note that if your only goal is to turn a well-distributed `long` (such as a random number)
+   * into a well-distributed nonnegative number, the most even distribution is achieved not by this
+   * method or other absolute value methods, but by {@code x & Long.MAX_VALUE}.
+   *
+   * @since NEXT
+   */
+  public static long saturatedAbs(long x) {
+    return (x == Long.MIN_VALUE) ? Long.MAX_VALUE : Math.abs(x);
+  }
+
   private LongMath() {}
 }

guava-tests/test/com/google/common/math/IntMathTest.java

@@ -692,6 +692,17 @@ public void testIsPrime() {
     }
   }
 
+  public void testSaturatedAbs() {
+    assertEquals(Integer.MAX_VALUE, IntMath.saturatedAbs(Integer.MIN_VALUE));
+    assertEquals(Integer.MAX_VALUE, IntMath.saturatedAbs(Integer.MAX_VALUE));
+    assertEquals(Integer.MAX_VALUE, IntMath.saturatedAbs(-Integer.MAX_VALUE));
+    assertEquals(0, IntMath.saturatedAbs(0));
+    assertEquals(1, IntMath.saturatedAbs(1));
+    assertEquals(1, IntMath.saturatedAbs(-1));
+    assertEquals(10, IntMath.saturatedAbs(10));
+    assertEquals(10, IntMath.saturatedAbs(-10));
+  }
+
   private static int force32(int value) {
     // GWT doesn't consistently overflow values to make them 32-bit, so we need to force it.
     return value & 0xffffffff;

guava-tests/test/com/google/common/math/LongMathTest.java

@@ -923,6 +923,17 @@ public void testRoundToDoubleAgainstBigIntegerUnnecessary() {
     }
   }
 
+  public void testSaturatedAbs() {
+    assertEquals(Long.MAX_VALUE, LongMath.saturatedAbs(Long.MIN_VALUE));
+    assertEquals(Long.MAX_VALUE, LongMath.saturatedAbs(Long.MAX_VALUE));
+    assertEquals(Long.MAX_VALUE, LongMath.saturatedAbs(-Long.MAX_VALUE));
+    assertEquals(0, LongMath.saturatedAbs(0));
+    assertEquals(1, LongMath.saturatedAbs(1));
+    assertEquals(1, LongMath.saturatedAbs(-1));
+    assertEquals(10, LongMath.saturatedAbs(10));
+    assertEquals(10, LongMath.saturatedAbs(-10));
+  }
+
   private static void failFormat(String template, Object... args) {
     assertWithMessage(template, args).fail();
   }

guava/src/com/google/common/math/IntMath.java

@@ -717,5 +717,35 @@ public static boolean isPrime(int n) {
     return LongMath.isPrime(n);
   }
 
+  /**
+   * Returns the closest representable {@code int} to the absolute value of {@code x}.
+   *
+   * <p>This is the same thing as the true absolute value of {@code x} except in the case when
+   * {@code x} is {@link Integer#MIN_VALUE}, in which case this returns {@link Integer#MAX_VALUE}.
+   * (Note that {@code Integer.MAX_VALUE} is mathematically equal to {@code -Integer.MIN_VALUE -
+   * 1}.)
+   *
+   * <p>There are three common APIs for determining the absolute value of an integer, all of which
+   * behave identically except when passed {@code Integer.MIN_VALUE}. Those methods are:
+   *
+   * <ul>
+   *   <li>{@link Math#abs(int)}, which returns {@code Integer.MIN_VALUE} when passed {@code
+   *       Integer.MIN_VALUE}
+   *   <li>{@link Math#absExact(int)}, which throws {@link ArithmeticException} when passed {@code
+   *       Integer.MIN_VALUE}
+   *   <li>this method, {@code IntMath.saturatedAbs(int)}, which returns {@code Integer.MAX_VALUE}
+   *       when passed {@code Integer.MIN_VALUE}
+   * </ul>
+   *
+   * <p>Note that if your only goal is to turn a well-distributed `int` (such as a random number or
+   * hash code) into a well-distributed nonnegative number, the most even distribution is achieved
+   * not by this method or other absolute value methods, but by {@code x & Integer.MAX_VALUE}.
+   *
+   * @since NEXT
+   */
+  public static int saturatedAbs(int x) {
+    return (x == Integer.MIN_VALUE) ? Integer.MAX_VALUE : Math.abs(x);
+  }
+
   private IntMath() {}
 }

guava/src/com/google/common/math/LongMath.java

@@ -1345,5 +1345,34 @@ public static double roundToDouble(long x, RoundingMode mode) {
     throw new AssertionError("impossible");
   }
 
+  /**
+   * Returns the closest representable {@code long} to the absolute value of {@code x}.
+   *
+   * <p>This is the same thing as the true absolute value of {@code x} except in the case when
+   * {@code x} is {@link Long#MIN_VALUE}, in which case this returns {@link Long#MAX_VALUE}. (Note
+   * that {@code Long.MAX_VALUE} is mathematically equal to {@code -Long.MIN_VALUE - 1}.)
+   *
+   * <p>There are three common APIs for determining the absolute value of a long, all of which
+   * behave identically except when passed {@code Long.MIN_VALUE}. Those methods are:
+   *
+   * <ul>
+   *   <li>{@link Math#abs(long)}, which returns {@code Long.MIN_VALUE} when passed {@code
+   *       Long.MIN_VALUE}
+   *   <li>{@link Math#absExact(long)}, which throws {@link ArithmeticException} when passed {@code
+   *       Long.MIN_VALUE}
+   *   <li>this method, {@code LongMath.saturatedAbs(long)}, which returns {@code Long.MAX_VALUE}
+   *       when passed {@code Long.MIN_VALUE}
+   * </ul>
+   *
+   * <p>Note that if your only goal is to turn a well-distributed `long` (such as a random number)
+   * into a well-distributed nonnegative number, the most even distribution is achieved not by this
+   * method or other absolute value methods, but by {@code x & Long.MAX_VALUE}.
+   *
+   * @since NEXT
+   */
+  public static long saturatedAbs(long x) {
+    return (x == Long.MIN_VALUE) ? Long.MAX_VALUE : Math.abs(x);
+  }
+
   private LongMath() {}
 }