added rounding methods.

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

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

@@ -16,6 +16,8 @@
 
 package org.apache.commons.math.util;
 
+import java.math.BigDecimal;
+
 /**
  * Some useful additions to the built-in functions in {@link Math}.
  *
@@ -47,6 +49,59 @@ public final class MathUtils {
     private MathUtils() {
     }
     
+    /**
+     * Round the given value to the specified number of decimal places.  The
+     * value is rounded using the {@link BigDecimal#ROUND_HALF_UP} method.
+     * @param x the value to round.
+     * @param scale the number of digits to the right of the decimal point.
+     * @return the rounded value.
+     */
+    public static double round(double x, int scale) {
+        return round(x, scale, BigDecimal.ROUND_HALF_UP);
+    }
+
+    /**
+     * Round the given value to the specified number of decimal places.  The
+     * value is rounded using the given method which is any method defined in
+     * {@link BigDecimal}.
+     * @param x the value to round.
+     * @param scale the number of digits to the right of the decimal point.
+     * @param roundingMethod the rounding method as defined in
+     *        {@link BigDecimal}. 
+     * @return the rounded value.
+     */
+    public static double round(
+        double x, int scale, int roundingMethod)
+    {
+        return (new BigDecimal(x).setScale(scale, roundingMethod))
+            .doubleValue();
+    }
+    
+    /**
+     * Round the given value to the specified number of decimal places.  The
+     * value is rounding using the {@link BigDecimal#ROUND_HALF_UP} method.
+     * @param x the value to round.
+     * @param scale the number of digits to the right of the decimal point.
+     * @return the rounded value.
+     */
+    public static float round(float x, int scale) {
+        return round(x, scale, BigDecimal.ROUND_HALF_UP);
+    }
+
+    /**
+     * Round the given value to the specified number of decimal places.  The
+     * value is rounded using the given method which is any method defined in
+     * {@link BigDecimal}.
+     * @param x the value to round.
+     * @param scale the number of digits to the right of the decimal point.
+     * @param roundingMethod the rounding method as defined in
+     *        {@link BigDecimal}. 
+     * @return the rounded value.
+     */
+    public static float round(float x, int scale, int roundingMethod) {
+        return (new BigDecimal(x).setScale(scale, roundingMethod)).floatValue();
+    }
+    
     /**
      * Returns the <a href="http://mathworld.wolfram.com/Sign.html">
      * sign</a> for double precision <code>x</code>.

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

@@ -15,6 +15,10 @@
  */
 package org.apache.commons.math.util;
 
+import java.math.BigDecimal;
+
+import org.apache.commons.math.TestUtils;
+
 import junit.framework.Test;
 import junit.framework.TestCase;
 import junit.framework.TestSuite;
@@ -426,4 +430,26 @@ public final class MathUtilsTest extends TestCase {
         assertEquals(150, MathUtils.lcm(a, -b));
         assertEquals(2310, MathUtils.lcm(a, c));
     }
+    
+    public void testRoundFloat() {
+        float x = 1.234567890f;
+        assertEquals(1.23f, MathUtils.round(x, 2), 0.0f);
+        assertEquals(1.235f, MathUtils.round(x, 3), 0.0f);
+        assertEquals(1.2346f, MathUtils.round(x, 4), 0.0f);
+
+        assertEquals(1.23f, MathUtils.round(x, 2, BigDecimal.ROUND_DOWN), 0.0f);
+        assertEquals(1.234f, MathUtils.round(x, 3, BigDecimal.ROUND_DOWN), 0.0f);
+        assertEquals(1.2345f, MathUtils.round(x, 4, BigDecimal.ROUND_DOWN), 0.0f);
+    }
+    
+    public void testRoundDouble() {
+        double x = 1.234567890;
+        assertEquals(1.23, MathUtils.round(x, 2), 0.0);
+        assertEquals(1.235, MathUtils.round(x, 3), 0.0);
+        assertEquals(1.2346, MathUtils.round(x, 4), 0.0);
+
+        assertEquals(1.23, MathUtils.round(x, 2, BigDecimal.ROUND_DOWN), 0.0);
+        assertEquals(1.234, MathUtils.round(x, 3, BigDecimal.ROUND_DOWN), 0.0);
+        assertEquals(1.2345, MathUtils.round(x, 4, BigDecimal.ROUND_DOWN), 0.0);
+    }
 }

xdocs/changes.xml

@@ -39,6 +39,9 @@ The <action> type attribute can be add,update,fix,remove.
   <body>
     <release version="1.1" date="In Development"  
        description="Jakarta Commons Math 1.1 - Development">
+      <action dev="brentworden" type="add">
+        Added convience methods for rounding.
+      </action>
       <action dev="brentworden" type="add" due-to="C. Scott Ananian">
         Added Fraction class based on commons-lang implementation.  With the
         fraction class, FractionFormat and ProperFractionFormat classes were

xdocs/userguide/utilities.xml

@@ -17,7 +17,7 @@
   -->
   
 <?xml-stylesheet type="text/xsl" href="./xdoc.xsl"?>
-<!-- $Revision: 1.9 $ $Date: 2004/07/20 22:29:50 $ -->
+<!-- $Revision: 1.9 $ $Date$ -->
 <document url="utilities.html">
 
 <properties>
@@ -164,7 +164,14 @@
     <li>
     a hash function, <code>hash(double),</code> returning a long-valued
     hash code for a double value.
-    </li></ul>
+    </li>
+    <li>
+    Convience methods to round floating-point number to arbitrary precision.
+    </li>
+    <li>
+    Least common multiple and greatest common denominator functions.
+    </li>
+    </ul>
     </p>
 </subsection>