From 328513f3adbcb683aebda8f1b38a0cb14d33de4e Mon Sep 17 00:00:00 2001
From: Phil Steitz <psteitz@apache.org>
Date: Mon, 4 Apr 2011 04:51:37 +0000
Subject: [PATCH] Changed MathUtils.round(double,int,int) to propagate rather
 than wrap runtime exceptions.  Instead of MathRuntimeException, this method
 now throws IllegalArgumentException or ArithmeticException under the
 conditions specified in the javadoc. JIRA: MATH-555

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/math/trunk@1088473 13f79535-47bb-0310-9956-ffa450edef68
---
 .../org/apache/commons/math/util/MathUtils.java    | 14 +++++++++-----
 src/site/xdoc/changes.xml                          |  6 ++++++
 .../apache/commons/math/util/MathUtilsTest.java    |  8 ++++----
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/src/main/java/org/apache/commons/math/util/MathUtils.java b/src/main/java/org/apache/commons/math/util/MathUtils.java
index 85d9a048f..52ebeb6ea 100644
--- a/src/main/java/org/apache/commons/math/util/MathUtils.java
+++ b/src/main/java/org/apache/commons/math/util/MathUtils.java
@@ -33,7 +33,6 @@ import org.apache.commons.math.exception.NullArgumentException;
 import org.apache.commons.math.exception.NotPositiveException;
 import org.apache.commons.math.exception.MathArithmeticException;
 import org.apache.commons.math.exception.MathIllegalArgumentException;
-import org.apache.commons.math.exception.MathRuntimeException;
 import org.apache.commons.math.exception.NumberIsTooLargeException;
 import org.apache.commons.math.exception.NotFiniteNumberException;
 
@@ -1333,15 +1332,22 @@ public final class MathUtils {
     }
 
     /**
-     * Round the given value to the specified number of decimal places. The
+     * <p>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}.
+     * {@link BigDecimal}.</p>
+     *
+     * <p>If {@code x} is infinite or NaN, then the value of {@code x} is
+     * returned unchanged, regardless of the other parameters.</p>
      *
      * @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.
+     * @throws ArithmeticException if roundingMethod==ROUND_UNNECESSARY and the
+     * specified scaling operation would require rounding.
+     * @throws IllegalArgumentException if roundingMethod does not represent a
+     * valid rounding mode.
      * @since 1.1
      */
     public static double round(double x, int scale, int roundingMethod) {
@@ -1356,8 +1362,6 @@ public final class MathUtils {
             } else {
                 return Double.NaN;
             }
-        } catch (RuntimeException ex) {
-            throw new MathRuntimeException(ex);
         }
     }
 
diff --git a/src/site/xdoc/changes.xml b/src/site/xdoc/changes.xml
index 45a699128..a953b91d2 100644
--- a/src/site/xdoc/changes.xml
+++ b/src/site/xdoc/changes.xml
@@ -52,6 +52,12 @@ The <action> type attribute can be add,update,fix,remove.
     If the output is not quite correct, check for invisible trailing spaces!
      -->
     <release version="3.0" date="TBD" description="TBD">
+      <action dev="psteitz" type="update" issue="MATH-555">
+        Changed MathUtils.round(double,int,int) to propagate rather than
+        wrap runtime exceptions.  Instead of MathRuntimeException, this method
+        now throws IllegalArgumentException or ArithmeticException under
+        the conditions specified in the javadoc.
+      </action>
       <action dev="luc" type="fix" issue="MATH-554" >
         Reduced cancellation errors in Vector3D.crossProduct
       </action>
diff --git a/src/test/java/org/apache/commons/math/util/MathUtilsTest.java b/src/test/java/org/apache/commons/math/util/MathUtilsTest.java
index d446bc720..d03efbbaa 100644
--- a/src/test/java/org/apache/commons/math/util/MathUtilsTest.java
+++ b/src/test/java/org/apache/commons/math/util/MathUtilsTest.java
@@ -1136,8 +1136,8 @@ public final class MathUtilsTest {
         try {
             MathUtils.round(1.234, 2, BigDecimal.ROUND_UNNECESSARY);
             Assert.fail();
-        } catch (MathRuntimeException ex) { // XXX Loosing semantics?
-            // success
+        } catch (ArithmeticException ex) { 
+            // expected
         }
 
         Assert.assertEquals(1.24, MathUtils.round(x, 2, BigDecimal.ROUND_UP), 0.0);
@@ -1150,8 +1150,8 @@ public final class MathUtilsTest {
         try {
             MathUtils.round(1.234, 2, 1923);
             Assert.fail();
-        } catch (MathRuntimeException ex) { // XXX Loosing semantics?
-            // success
+        } catch (IllegalArgumentException ex) {
+            // expected
         }
 
         // MATH-151