MATH-561

Map a value to the interval [O, period).


git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1097088 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/math/util/MathUtils.java

@@ -1281,6 +1281,22 @@ public final class MathUtils {
          return a - TWO_PI * FastMath.floor((a + FastMath.PI - center) / TWO_PI);
      }
 
+    /**
+     * Reduce to the primary interval {@code [0 period)}.
+     *
+     * @param a Value to reduce.
+     * @param period Period.
+     * @param offset Value that will be mapped to {@code 0}.
+     * @return the value, within the interval {@code [0 period)},
+     * that corresponds to {@code a}.
+     */
+    public static double reduce(double a,
+                                double period,
+                                double offset) {
+        final double p = Math.abs(period);
+        return a - p * Math.floor((a - offset) / p) - offset;
+    }
+
      /**
       * <p>Normalizes an array to make it sum to a specified value.
       * Returns the result of the transformation <pre>

src/test/java/org/apache/commons/math/util/MathUtilsTest.java

@@ -1053,6 +1053,55 @@ public final class MathUtilsTest {
         }
     }
 
+    @Test
+    public void testReduce() {
+        final double period = -12.222;
+        final double offset = 13;
+
+        final double delta = 1.5;
+
+        double orig = offset + 122456789 * period + delta;
+        double expected = delta;
+        Assert.assertEquals(expected,
+                            MathUtils.reduce(orig, period, offset),
+                            1e-7);
+        Assert.assertEquals(expected,
+                            MathUtils.reduce(orig, -period, offset),
+                            1e-7);
+
+        orig = offset - 123356789 * period - delta;
+        expected = Math.abs(period) - delta;
+        Assert.assertEquals(expected,
+                            MathUtils.reduce(orig, period, offset),
+                            1e-6);
+        Assert.assertEquals(expected,
+                            MathUtils.reduce(orig, -period, offset),
+                            1e-6);
+
+        orig = offset - 123446789 * period + delta;
+        expected = delta;
+        Assert.assertEquals(expected,
+                            MathUtils.reduce(orig, period, offset),
+                            1e-6);
+        Assert.assertEquals(expected,
+                            MathUtils.reduce(orig, -period, offset),
+                            1e-6);
+    }
+
+    @Test
+    public void testReduceComparedWithNormalizeAngle() {
+        final double tol = Math.ulp(1d);
+        final double period = 2 * Math.PI;
+        for (double a = -15; a <= 15; a += 0.5) {
+            for (double center = -15; center <= 15; center += 1) {
+                final double nA = MathUtils.normalizeAngle(a, center);
+                final double offset = center - Math.PI;
+                final double r = MathUtils.reduce(a, period, offset);
+                Assert.assertEquals(nA, r + offset, tol);
+            }
+        }
+    }
+
     @Test
     public void testNormalizeArray() {
         double[] testValues1 = new double[] {1, 1, 2};