Allow DD creation from an unsigned long value.

Added to support interpolation of ordered long values in STATISTICS-94.

Author: aherbert

commons-numbers-core/src/main/java/org/apache/commons/numbers/core/DD.java

@@ -361,6 +361,33 @@ public static DD of(long x) {
         return fastTwoSum(a, b);
     }
 
+    /**
+     * Creates the double-double number using the argument {@code x} as an unsigned
+     * 64-bit integer.
+     *
+     * <p>Note this method preserves all 64-bits of precision. It can be used to
+     * represent the positive difference between two ordered {@code long} values
+     * without using {@link DD#subtract(DD)}.
+     *
+     * <p>Given two {@code long} values {@code a <= b} the following are equivalent:
+     * <pre>
+     * DD.of(b).subtract(DD.of(a))
+     *
+     * DD.ofUnsigned(b - a)
+     * </pre>
+     *
+     * @param x Value.
+     * @return the double-double
+     */
+    public static DD ofUnsigned(long x) {
+        // Similar to of(long) but the high part is composed as an unsigned double
+        final long a = x & HIGH32_MASK;
+        final long b = x - a;
+        // Convert the unsigned magnitude to a double
+        final double aa = (a >>> 1) * 2.0;
+        return fastTwoSum(aa, b);
+    }
+
     /**
      * Creates the double-double number {@code (z, zz)} using the {@code double} representation
      * of the argument {@code x}; the low part is the {@code double} representation of the

commons-numbers-core/src/test/java/org/apache/commons/numbers/core/DDTest.java

@@ -17,6 +17,7 @@
 package org.apache.commons.numbers.core;
 
 import java.math.BigDecimal;
+import java.math.BigInteger;
 import java.math.MathContext;
 import java.math.RoundingMode;
 import java.util.ArrayList;
@@ -26,6 +27,7 @@
 import java.util.function.Supplier;
 import java.util.function.UnaryOperator;
 import java.util.stream.IntStream;
+import java.util.stream.LongStream;
 import java.util.stream.Stream;
 import org.apache.commons.rng.UniformRandomProvider;
 import org.apache.commons.rng.simple.RandomSource;
@@ -131,8 +133,9 @@ void testOfInt(int x) {
      * to rounding to 2^53 so we have extra cases for this.
      */
     @ParameterizedTest
-    @ValueSource(longs = {0, 1, 42, 89545664, 8263492364L, Long.MIN_VALUE,
-        Long.MAX_VALUE - (1L << 10), Long.MAX_VALUE - 42, Long.MAX_VALUE - 1, Long.MAX_VALUE})
+    @ValueSource(longs = {0, 1, 42, 89545664, 8263492364L,
+        Long.MAX_VALUE - (1L << 10), Long.MAX_VALUE - 42, Long.MAX_VALUE - 1, Long.MAX_VALUE,
+        Long.MIN_VALUE})
     void testOfLong(long x) {
         DD dd = DD.of(x);
         Assertions.assertEquals(x, dd.hi(), "x hi should be (double) x");
@@ -142,6 +145,38 @@ void testOfLong(long x) {
         Assertions.assertEquals(BigDecimal.valueOf(-x).subtract(bd(-x)).doubleValue(), dd.lo(), "-x lo should be remaining bits");
     }
 
+    /**
+     * Test conversion of an unsigned {@code long}.
+     */
+    @ParameterizedTest
+    @ValueSource(longs = {0, 1, 42, 89545664, 8263492364L,
+        -1, -42, -89545664, -8263492364L,
+        Long.MAX_VALUE - (1L << 10), Long.MAX_VALUE - 42, Long.MAX_VALUE - 1, Long.MAX_VALUE,
+        Long.MIN_VALUE + (1L << 10), Long.MIN_VALUE + 42, Long.MIN_VALUE + 1, Long.MIN_VALUE})
+    @MethodSource
+    void testOfUnsignedLong(long x) {
+        final DD dd = DD.ofUnsigned(x);
+        Assertions.assertTrue(dd.hi() >= 0, "x hi should be positive");
+        // Create the exact unsigned value
+        final BigInteger xx;
+        if (x < 0) {
+            // 63-bits plus 2^63
+            xx = BigInteger.valueOf(x & Long.MAX_VALUE).or(BigInteger.ONE.shiftLeft(63));
+        } else {
+            xx = BigInteger.valueOf(x);
+        }
+        final BigDecimal expected = new BigDecimal(xx);
+        final double hi = expected.doubleValue();
+        final double lo = expected.subtract(bd(hi)).doubleValue();
+        Assertions.assertEquals(hi, dd.hi(), "x hi");
+        Assertions.assertEquals(lo, dd.lo(), "x lo");
+    }
+
+    static LongStream testOfUnsignedLong() {
+        // Random
+        return createRNG().longs(10);
+    }
+
     @ParameterizedTest
     @MethodSource(value = {"twoSumAddends"})
     void testFromBigDecimal(double x, double y) {

src/changes/changes.xml

@@ -56,6 +56,9 @@ If the output is not quite correct, check for invisible trailing spaces!
     <release version="1.3" date="TBD" description="
 New features, updates and bug fixes.
 ">
+      <action dev="aherbert" type="add">
+        "DD": Allow creation from an unsigned long value.
+      </action>
       <action dev="aherbert" type="add" issue="NUMBERS-208">
         "Selection": Add support for selection from a long array.
       </action>