/* |
|
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. |
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
|
* |
|
* This code is free software; you can redistribute it and/or modify it |
|
* under the terms of the GNU General Public License version 2 only, as |
|
* published by the Free Software Foundation. Oracle designates this |
|
* particular file as subject to the "Classpath" exception as provided |
|
* by Oracle in the LICENSE file that accompanied this code. |
|
* |
|
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
* version 2 for more details (a copy is included in the LICENSE file that |
|
* accompanied this code). |
|
* |
|
* You should have received a copy of the GNU General Public License version |
|
* 2 along with this work; if not, write to the Free Software Foundation, |
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
* |
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
|
* or visit www.oracle.com if you need additional information or have any |
|
* questions. |
|
*/ |
|
/* |
|
* Portions Copyright IBM Corporation, 2001. All Rights Reserved. |
|
*/ |
|
package java.math; |
|
/** |
|
* Specifies a <i>rounding behavior</i> for numerical operations |
|
* capable of discarding precision. Each rounding mode indicates how |
|
* the least significant returned digit of a rounded result is to be |
|
* calculated. If fewer digits are returned than the digits needed to |
|
* represent the exact numerical result, the discarded digits will be |
|
* referred to as the <i>discarded fraction</i> regardless the digits' |
|
* contribution to the value of the number. In other words, |
|
* considered as a numerical value, the discarded fraction could have |
|
* an absolute value greater than one. |
|
* |
|
* <p>Each rounding mode description includes a table listing how |
|
* different two-digit decimal values would round to a one digit |
|
* decimal value under the rounding mode in question. The result |
|
* column in the tables could be gotten by creating a |
|
* {@code BigDecimal} number with the specified value, forming a |
|
* {@link MathContext} object with the proper settings |
|
* ({@code precision} set to {@code 1}, and the |
|
* {@code roundingMode} set to the rounding mode in question), and |
|
* calling {@link BigDecimal#round round} on this number with the |
|
* proper {@code MathContext}. A summary table showing the results |
|
* of these rounding operations for all rounding modes appears below. |
|
* |
|
*<table border> |
|
* <caption><b>Summary of Rounding Operations Under Different Rounding Modes</b></caption> |
|
* <tr><th></th><th colspan=8>Result of rounding input to one digit with the given |
|
* rounding mode</th> |
|
* <tr valign=top> |
|
* <th>Input Number</th> <th>{@code UP}</th> |
|
* <th>{@code DOWN}</th> |
|
* <th>{@code CEILING}</th> |
|
* <th>{@code FLOOR}</th> |
|
* <th>{@code HALF_UP}</th> |
|
* <th>{@code HALF_DOWN}</th> |
|
* <th>{@code HALF_EVEN}</th> |
|
* <th>{@code UNNECESSARY}</th> |
|
* |
|
* <tr align=right><td>5.5</td> <td>6</td> <td>5</td> <td>6</td> <td>5</td> <td>6</td> <td>5</td> <td>6</td> <td>throw {@code ArithmeticException}</td> |
|
* <tr align=right><td>2.5</td> <td>3</td> <td>2</td> <td>3</td> <td>2</td> <td>3</td> <td>2</td> <td>2</td> <td>throw {@code ArithmeticException}</td> |
|
* <tr align=right><td>1.6</td> <td>2</td> <td>1</td> <td>2</td> <td>1</td> <td>2</td> <td>2</td> <td>2</td> <td>throw {@code ArithmeticException}</td> |
|
* <tr align=right><td>1.1</td> <td>2</td> <td>1</td> <td>2</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>throw {@code ArithmeticException}</td> |
|
* <tr align=right><td>1.0</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> |
|
* <tr align=right><td>-1.0</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> |
|
* <tr align=right><td>-1.1</td> <td>-2</td> <td>-1</td> <td>-1</td> <td>-2</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>throw {@code ArithmeticException}</td> |
|
* <tr align=right><td>-1.6</td> <td>-2</td> <td>-1</td> <td>-1</td> <td>-2</td> <td>-2</td> <td>-2</td> <td>-2</td> <td>throw {@code ArithmeticException}</td> |
|
* <tr align=right><td>-2.5</td> <td>-3</td> <td>-2</td> <td>-2</td> <td>-3</td> <td>-3</td> <td>-2</td> <td>-2</td> <td>throw {@code ArithmeticException}</td> |
|
* <tr align=right><td>-5.5</td> <td>-6</td> <td>-5</td> <td>-5</td> <td>-6</td> <td>-6</td> <td>-5</td> <td>-6</td> <td>throw {@code ArithmeticException}</td> |
|
*</table> |
|
* |
|
* |
|
* <p>This {@code enum} is intended to replace the integer-based |
|
* enumeration of rounding mode constants in {@link BigDecimal} |
|
* ({@link BigDecimal#ROUND_UP}, {@link BigDecimal#ROUND_DOWN}, |
|
* etc. ). |
|
* |
|
* @see BigDecimal |
|
* @see MathContext |
|
* @author Josh Bloch |
|
* @author Mike Cowlishaw |
|
* @author Joseph D. Darcy |
|
* @since 1.5 |
|
*/ |
|
public enum RoundingMode { |
|
/** |
|
* Rounding mode to round away from zero. Always increments the |
|
* digit prior to a non-zero discarded fraction. Note that this |
|
* rounding mode never decreases the magnitude of the calculated |
|
* value. |
|
* |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode UP Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code UP} rounding |
|
*<tr align=right><td>5.5</td> <td>6</td> |
|
*<tr align=right><td>2.5</td> <td>3</td> |
|
*<tr align=right><td>1.6</td> <td>2</td> |
|
*<tr align=right><td>1.1</td> <td>2</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>-2</td> |
|
*<tr align=right><td>-1.6</td> <td>-2</td> |
|
*<tr align=right><td>-2.5</td> <td>-3</td> |
|
*<tr align=right><td>-5.5</td> <td>-6</td> |
|
*</table> |
|
*/ |
|
UP(BigDecimal.ROUND_UP), |
|
/** |
|
* Rounding mode to round towards zero. Never increments the digit |
|
* prior to a discarded fraction (i.e., truncates). Note that this |
|
* rounding mode never increases the magnitude of the calculated value. |
|
* |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode DOWN Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code DOWN} rounding |
|
*<tr align=right><td>5.5</td> <td>5</td> |
|
*<tr align=right><td>2.5</td> <td>2</td> |
|
*<tr align=right><td>1.6</td> <td>1</td> |
|
*<tr align=right><td>1.1</td> <td>1</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>-1</td> |
|
*<tr align=right><td>-1.6</td> <td>-1</td> |
|
*<tr align=right><td>-2.5</td> <td>-2</td> |
|
*<tr align=right><td>-5.5</td> <td>-5</td> |
|
*</table> |
|
*/ |
|
DOWN(BigDecimal.ROUND_DOWN), |
|
/** |
|
* Rounding mode to round towards positive infinity. If the |
|
* result is positive, behaves as for {@code RoundingMode.UP}; |
|
* if negative, behaves as for {@code RoundingMode.DOWN}. Note |
|
* that this rounding mode never decreases the calculated value. |
|
* |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode CEILING Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code CEILING} rounding |
|
*<tr align=right><td>5.5</td> <td>6</td> |
|
*<tr align=right><td>2.5</td> <td>3</td> |
|
*<tr align=right><td>1.6</td> <td>2</td> |
|
*<tr align=right><td>1.1</td> <td>2</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>-1</td> |
|
*<tr align=right><td>-1.6</td> <td>-1</td> |
|
*<tr align=right><td>-2.5</td> <td>-2</td> |
|
*<tr align=right><td>-5.5</td> <td>-5</td> |
|
*</table> |
|
*/ |
|
CEILING(BigDecimal.ROUND_CEILING), |
|
/** |
|
* Rounding mode to round towards negative infinity. If the |
|
* result is positive, behave as for {@code RoundingMode.DOWN}; |
|
* if negative, behave as for {@code RoundingMode.UP}. Note that |
|
* this rounding mode never increases the calculated value. |
|
* |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode FLOOR Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code FLOOR} rounding |
|
*<tr align=right><td>5.5</td> <td>5</td> |
|
*<tr align=right><td>2.5</td> <td>2</td> |
|
*<tr align=right><td>1.6</td> <td>1</td> |
|
*<tr align=right><td>1.1</td> <td>1</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>-2</td> |
|
*<tr align=right><td>-1.6</td> <td>-2</td> |
|
*<tr align=right><td>-2.5</td> <td>-3</td> |
|
*<tr align=right><td>-5.5</td> <td>-6</td> |
|
*</table> |
|
*/ |
|
FLOOR(BigDecimal.ROUND_FLOOR), |
|
/** |
|
* Rounding mode to round towards {@literal "nearest neighbor"} |
|
* unless both neighbors are equidistant, in which case round up. |
|
* Behaves as for {@code RoundingMode.UP} if the discarded |
|
* fraction is ≥ 0.5; otherwise, behaves as for |
|
* {@code RoundingMode.DOWN}. Note that this is the rounding |
|
* mode commonly taught at school. |
|
* |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode HALF_UP Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code HALF_UP} rounding |
|
*<tr align=right><td>5.5</td> <td>6</td> |
|
*<tr align=right><td>2.5</td> <td>3</td> |
|
*<tr align=right><td>1.6</td> <td>2</td> |
|
*<tr align=right><td>1.1</td> <td>1</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>-1</td> |
|
*<tr align=right><td>-1.6</td> <td>-2</td> |
|
*<tr align=right><td>-2.5</td> <td>-3</td> |
|
*<tr align=right><td>-5.5</td> <td>-6</td> |
|
*</table> |
|
*/ |
|
HALF_UP(BigDecimal.ROUND_HALF_UP), |
|
/** |
|
* Rounding mode to round towards {@literal "nearest neighbor"} |
|
* unless both neighbors are equidistant, in which case round |
|
* down. Behaves as for {@code RoundingMode.UP} if the discarded |
|
* fraction is > 0.5; otherwise, behaves as for |
|
* {@code RoundingMode.DOWN}. |
|
* |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode HALF_DOWN Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code HALF_DOWN} rounding |
|
*<tr align=right><td>5.5</td> <td>5</td> |
|
*<tr align=right><td>2.5</td> <td>2</td> |
|
*<tr align=right><td>1.6</td> <td>2</td> |
|
*<tr align=right><td>1.1</td> <td>1</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>-1</td> |
|
*<tr align=right><td>-1.6</td> <td>-2</td> |
|
*<tr align=right><td>-2.5</td> <td>-2</td> |
|
*<tr align=right><td>-5.5</td> <td>-5</td> |
|
*</table> |
|
*/ |
|
HALF_DOWN(BigDecimal.ROUND_HALF_DOWN), |
|
/** |
|
* Rounding mode to round towards the {@literal "nearest neighbor"} |
|
* unless both neighbors are equidistant, in which case, round |
|
* towards the even neighbor. Behaves as for |
|
* {@code RoundingMode.HALF_UP} if the digit to the left of the |
|
* discarded fraction is odd; behaves as for |
|
* {@code RoundingMode.HALF_DOWN} if it's even. Note that this |
|
* is the rounding mode that statistically minimizes cumulative |
|
* error when applied repeatedly over a sequence of calculations. |
|
* It is sometimes known as {@literal "Banker's rounding,"} and is |
|
* chiefly used in the USA. This rounding mode is analogous to |
|
* the rounding policy used for {@code float} and {@code double} |
|
* arithmetic in Java. |
|
* |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode HALF_EVEN Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code HALF_EVEN} rounding |
|
*<tr align=right><td>5.5</td> <td>6</td> |
|
*<tr align=right><td>2.5</td> <td>2</td> |
|
*<tr align=right><td>1.6</td> <td>2</td> |
|
*<tr align=right><td>1.1</td> <td>1</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>-1</td> |
|
*<tr align=right><td>-1.6</td> <td>-2</td> |
|
*<tr align=right><td>-2.5</td> <td>-2</td> |
|
*<tr align=right><td>-5.5</td> <td>-6</td> |
|
*</table> |
|
*/ |
|
HALF_EVEN(BigDecimal.ROUND_HALF_EVEN), |
|
/** |
|
* Rounding mode to assert that the requested operation has an exact |
|
* result, hence no rounding is necessary. If this rounding mode is |
|
* specified on an operation that yields an inexact result, an |
|
* {@code ArithmeticException} is thrown. |
|
*<p>Example: |
|
*<table border> |
|
* <caption><b>Rounding mode UNNECESSARY Examples</b></caption> |
|
*<tr valign=top><th>Input Number</th> |
|
* <th>Input rounded to one digit<br> with {@code UNNECESSARY} rounding |
|
*<tr align=right><td>5.5</td> <td>throw {@code ArithmeticException}</td> |
|
*<tr align=right><td>2.5</td> <td>throw {@code ArithmeticException}</td> |
|
*<tr align=right><td>1.6</td> <td>throw {@code ArithmeticException}</td> |
|
*<tr align=right><td>1.1</td> <td>throw {@code ArithmeticException}</td> |
|
*<tr align=right><td>1.0</td> <td>1</td> |
|
*<tr align=right><td>-1.0</td> <td>-1</td> |
|
*<tr align=right><td>-1.1</td> <td>throw {@code ArithmeticException}</td> |
|
*<tr align=right><td>-1.6</td> <td>throw {@code ArithmeticException}</td> |
|
*<tr align=right><td>-2.5</td> <td>throw {@code ArithmeticException}</td> |
|
*<tr align=right><td>-5.5</td> <td>throw {@code ArithmeticException}</td> |
|
*</table> |
|
*/ |
|
UNNECESSARY(BigDecimal.ROUND_UNNECESSARY); |
|
// Corresponding BigDecimal rounding constant |
|
final int oldMode; |
|
/** |
|
* Constructor |
|
* |
|
* @param oldMode The {@code BigDecimal} constant corresponding to |
|
* this mode |
|
*/ |
|
private RoundingMode(int oldMode) { |
|
this.oldMode = oldMode; |
|
} |
|
/** |
|
* Returns the {@code RoundingMode} object corresponding to a |
|
* legacy integer rounding mode constant in {@link BigDecimal}. |
|
* |
|
* @param rm legacy integer rounding mode to convert |
|
* @return {@code RoundingMode} corresponding to the given integer. |
|
* @throws IllegalArgumentException integer is out of range |
|
*/ |
|
public static RoundingMode valueOf(int rm) { |
|
switch(rm) { |
|
case BigDecimal.ROUND_UP: |
|
return UP; |
|
case BigDecimal.ROUND_DOWN: |
|
return DOWN; |
|
case BigDecimal.ROUND_CEILING: |
|
return CEILING; |
|
case BigDecimal.ROUND_FLOOR: |
|
return FLOOR; |
|
case BigDecimal.ROUND_HALF_UP: |
|
return HALF_UP; |
|
case BigDecimal.ROUND_HALF_DOWN: |
|
return HALF_DOWN; |
|
case BigDecimal.ROUND_HALF_EVEN: |
|
return HALF_EVEN; |
|
case BigDecimal.ROUND_UNNECESSARY: |
|
return UNNECESSARY; |
|
default: |
|
throw new IllegalArgumentException("argument out of range"); |
|
} |
|
} |
|
} |