1 /*
   2  * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 /*
  27  * Portions Copyright IBM Corporation, 2001. All Rights Reserved.
  28  */
  29 package java.math;
  30 
  31 /**
  32  * Specifies a <i>rounding behavior</i> for numerical operations
  33  * capable of discarding precision. Each rounding mode indicates how
  34  * the least significant returned digit of a rounded result is to be
  35  * calculated.  If fewer digits are returned than the digits needed to
  36  * represent the exact numerical result, the discarded digits will be
  37  * referred to as the <i>discarded fraction</i> regardless the digits'
  38  * contribution to the value of the number.  In other words,
  39  * considered as a numerical value, the discarded fraction could have
  40  * an absolute value greater than one.
  41  *
  42  * <p>Each rounding mode description includes a table listing how
  43  * different two-digit decimal values would round to a one digit
  44  * decimal value under the rounding mode in question.  The result
  45  * column in the tables could be gotten by creating a
  46  * {@code BigDecimal} number with the specified value, forming a
  47  * {@link MathContext} object with the proper settings
  48  * ({@code precision} set to {@code 1}, and the
  49  * {@code roundingMode} set to the rounding mode in question), and
  50  * calling {@link BigDecimal#round round} on this number with the
  51  * proper {@code MathContext}.  A summary table showing the results
  52  * of these rounding operations for all rounding modes appears below.
  53  *
  54  *<table border>
  55  * <caption><b>Summary of Rounding Operations Under Different Rounding Modes</b></caption>
  56  * <tr><th></th><th colspan=8>Result of rounding input to one digit with the given
  57  *                           rounding mode</th>
  58  * <tr valign=top>
  59  * <th>Input Number</th>         <th>{@code UP}</th>
  60  *                                           <th>{@code DOWN}</th>
  61  *                                                        <th>{@code CEILING}</th>
  62  *                                                                       <th>{@code FLOOR}</th>
  63  *                                                                                    <th>{@code HALF_UP}</th>
  64  *                                                                                                   <th>{@code HALF_DOWN}</th>
  65  *                                                                                                                    <th>{@code HALF_EVEN}</th>
  66  *                                                                                                                                     <th>{@code UNNECESSARY}</th>
  67  *
  68  * <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>
  69  * <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>
  70  * <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>
  71  * <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>
  72  * <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>
  73  * <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>
  74  * <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>
  75  * <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>
  76  * <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>
  77  * <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>
  78  *</table>
  79  *
  80  *
  81  * <p>This {@code enum} is intended to replace the integer-based
  82  * enumeration of rounding mode constants in {@link BigDecimal}
  83  * ({@link BigDecimal#ROUND_UP}, {@link BigDecimal#ROUND_DOWN},
  84  * etc. ).
  85  *
  86  * @see     BigDecimal
  87  * @see     MathContext
  88  * @author  Josh Bloch
  89  * @author  Mike Cowlishaw
  90  * @author  Joseph D. Darcy
  91  * @since 1.5
  92  */
  93 @SuppressWarnings("deprecation") // Legacy rounding mode constants in BigDecimal
  94 public enum RoundingMode {
  95 
  96         /**
  97          * Rounding mode to round away from zero.  Always increments the
  98          * digit prior to a non-zero discarded fraction.  Note that this
  99          * rounding mode never decreases the magnitude of the calculated
 100          * value.
 101          *
 102          *<p>Example:
 103          *<table border>
 104          * <caption><b>Rounding mode UP Examples</b></caption>
 105          *<tr valign=top><th>Input Number</th>
 106          *    <th>Input rounded to one digit<br> with {@code UP} rounding
 107          *<tr align=right><td>5.5</td>  <td>6</td>
 108          *<tr align=right><td>2.5</td>  <td>3</td>
 109          *<tr align=right><td>1.6</td>  <td>2</td>
 110          *<tr align=right><td>1.1</td>  <td>2</td>
 111          *<tr align=right><td>1.0</td>  <td>1</td>
 112          *<tr align=right><td>-1.0</td> <td>-1</td>
 113          *<tr align=right><td>-1.1</td> <td>-2</td>
 114          *<tr align=right><td>-1.6</td> <td>-2</td>
 115          *<tr align=right><td>-2.5</td> <td>-3</td>
 116          *<tr align=right><td>-5.5</td> <td>-6</td>
 117          *</table>
 118          */
 119     UP(BigDecimal.ROUND_UP),
 120 
 121         /**
 122          * Rounding mode to round towards zero.  Never increments the digit
 123          * prior to a discarded fraction (i.e., truncates).  Note that this
 124          * rounding mode never increases the magnitude of the calculated value.
 125          *
 126          *<p>Example:
 127          *<table border>
 128          * <caption><b>Rounding mode DOWN Examples</b></caption>
 129          *<tr valign=top><th>Input Number</th>
 130          *    <th>Input rounded to one digit<br> with {@code DOWN} rounding
 131          *<tr align=right><td>5.5</td>  <td>5</td>
 132          *<tr align=right><td>2.5</td>  <td>2</td>
 133          *<tr align=right><td>1.6</td>  <td>1</td>
 134          *<tr align=right><td>1.1</td>  <td>1</td>
 135          *<tr align=right><td>1.0</td>  <td>1</td>
 136          *<tr align=right><td>-1.0</td> <td>-1</td>
 137          *<tr align=right><td>-1.1</td> <td>-1</td>
 138          *<tr align=right><td>-1.6</td> <td>-1</td>
 139          *<tr align=right><td>-2.5</td> <td>-2</td>
 140          *<tr align=right><td>-5.5</td> <td>-5</td>
 141          *</table>
 142          */
 143     DOWN(BigDecimal.ROUND_DOWN),
 144 
 145         /**
 146          * Rounding mode to round towards positive infinity.  If the
 147          * result is positive, behaves as for {@code RoundingMode.UP};
 148          * if negative, behaves as for {@code RoundingMode.DOWN}.  Note
 149          * that this rounding mode never decreases the calculated value.
 150          *
 151          *<p>Example:
 152          *<table border>
 153          * <caption><b>Rounding mode CEILING Examples</b></caption>
 154          *<tr valign=top><th>Input Number</th>
 155          *    <th>Input rounded to one digit<br> with {@code CEILING} rounding
 156          *<tr align=right><td>5.5</td>  <td>6</td>
 157          *<tr align=right><td>2.5</td>  <td>3</td>
 158          *<tr align=right><td>1.6</td>  <td>2</td>
 159          *<tr align=right><td>1.1</td>  <td>2</td>
 160          *<tr align=right><td>1.0</td>  <td>1</td>
 161          *<tr align=right><td>-1.0</td> <td>-1</td>
 162          *<tr align=right><td>-1.1</td> <td>-1</td>
 163          *<tr align=right><td>-1.6</td> <td>-1</td>
 164          *<tr align=right><td>-2.5</td> <td>-2</td>
 165          *<tr align=right><td>-5.5</td> <td>-5</td>
 166          *</table>
 167          */
 168     CEILING(BigDecimal.ROUND_CEILING),
 169 
 170         /**
 171          * Rounding mode to round towards negative infinity.  If the
 172          * result is positive, behave as for {@code RoundingMode.DOWN};
 173          * if negative, behave as for {@code RoundingMode.UP}.  Note that
 174          * this rounding mode never increases the calculated value.
 175          *
 176          *<p>Example:
 177          *<table border>
 178          * <caption><b>Rounding mode FLOOR Examples</b></caption>
 179          *<tr valign=top><th>Input Number</th>
 180          *    <th>Input rounded to one digit<br> with {@code FLOOR} rounding
 181          *<tr align=right><td>5.5</td>  <td>5</td>
 182          *<tr align=right><td>2.5</td>  <td>2</td>
 183          *<tr align=right><td>1.6</td>  <td>1</td>
 184          *<tr align=right><td>1.1</td>  <td>1</td>
 185          *<tr align=right><td>1.0</td>  <td>1</td>
 186          *<tr align=right><td>-1.0</td> <td>-1</td>
 187          *<tr align=right><td>-1.1</td> <td>-2</td>
 188          *<tr align=right><td>-1.6</td> <td>-2</td>
 189          *<tr align=right><td>-2.5</td> <td>-3</td>
 190          *<tr align=right><td>-5.5</td> <td>-6</td>
 191          *</table>
 192          */
 193     FLOOR(BigDecimal.ROUND_FLOOR),
 194 
 195         /**
 196          * Rounding mode to round towards {@literal "nearest neighbor"}
 197          * unless both neighbors are equidistant, in which case round up.
 198          * Behaves as for {@code RoundingMode.UP} if the discarded
 199          * fraction is &ge; 0.5; otherwise, behaves as for
 200          * {@code RoundingMode.DOWN}.  Note that this is the rounding
 201          * mode commonly taught at school.
 202          *
 203          *<p>Example:
 204          *<table border>
 205          * <caption><b>Rounding mode HALF_UP Examples</b></caption>
 206          *<tr valign=top><th>Input Number</th>
 207          *    <th>Input rounded to one digit<br> with {@code HALF_UP} rounding
 208          *<tr align=right><td>5.5</td>  <td>6</td>
 209          *<tr align=right><td>2.5</td>  <td>3</td>
 210          *<tr align=right><td>1.6</td>  <td>2</td>
 211          *<tr align=right><td>1.1</td>  <td>1</td>
 212          *<tr align=right><td>1.0</td>  <td>1</td>
 213          *<tr align=right><td>-1.0</td> <td>-1</td>
 214          *<tr align=right><td>-1.1</td> <td>-1</td>
 215          *<tr align=right><td>-1.6</td> <td>-2</td>
 216          *<tr align=right><td>-2.5</td> <td>-3</td>
 217          *<tr align=right><td>-5.5</td> <td>-6</td>
 218          *</table>
 219          */
 220     HALF_UP(BigDecimal.ROUND_HALF_UP),
 221 
 222         /**
 223          * Rounding mode to round towards {@literal "nearest neighbor"}
 224          * unless both neighbors are equidistant, in which case round
 225          * down.  Behaves as for {@code RoundingMode.UP} if the discarded
 226          * fraction is &gt; 0.5; otherwise, behaves as for
 227          * {@code RoundingMode.DOWN}.
 228          *
 229          *<p>Example:
 230          *<table border>
 231          * <caption><b>Rounding mode HALF_DOWN Examples</b></caption>
 232          *<tr valign=top><th>Input Number</th>
 233          *    <th>Input rounded to one digit<br> with {@code HALF_DOWN} rounding
 234          *<tr align=right><td>5.5</td>  <td>5</td>
 235          *<tr align=right><td>2.5</td>  <td>2</td>
 236          *<tr align=right><td>1.6</td>  <td>2</td>
 237          *<tr align=right><td>1.1</td>  <td>1</td>
 238          *<tr align=right><td>1.0</td>  <td>1</td>
 239          *<tr align=right><td>-1.0</td> <td>-1</td>
 240          *<tr align=right><td>-1.1</td> <td>-1</td>
 241          *<tr align=right><td>-1.6</td> <td>-2</td>
 242          *<tr align=right><td>-2.5</td> <td>-2</td>
 243          *<tr align=right><td>-5.5</td> <td>-5</td>
 244          *</table>
 245          */
 246     HALF_DOWN(BigDecimal.ROUND_HALF_DOWN),
 247 
 248         /**
 249          * Rounding mode to round towards the {@literal "nearest neighbor"}
 250          * unless both neighbors are equidistant, in which case, round
 251          * towards the even neighbor.  Behaves as for
 252          * {@code RoundingMode.HALF_UP} if the digit to the left of the
 253          * discarded fraction is odd; behaves as for
 254          * {@code RoundingMode.HALF_DOWN} if it's even.  Note that this
 255          * is the rounding mode that statistically minimizes cumulative
 256          * error when applied repeatedly over a sequence of calculations.
 257          * It is sometimes known as {@literal "Banker's rounding,"} and is
 258          * chiefly used in the USA.  This rounding mode is analogous to
 259          * the rounding policy used for {@code float} and {@code double}
 260          * arithmetic in Java.
 261          *
 262          *<p>Example:
 263          *<table border>
 264          * <caption><b>Rounding mode HALF_EVEN Examples</b></caption>
 265          *<tr valign=top><th>Input Number</th>
 266          *    <th>Input rounded to one digit<br> with {@code HALF_EVEN} rounding
 267          *<tr align=right><td>5.5</td>  <td>6</td>
 268          *<tr align=right><td>2.5</td>  <td>2</td>
 269          *<tr align=right><td>1.6</td>  <td>2</td>
 270          *<tr align=right><td>1.1</td>  <td>1</td>
 271          *<tr align=right><td>1.0</td>  <td>1</td>
 272          *<tr align=right><td>-1.0</td> <td>-1</td>
 273          *<tr align=right><td>-1.1</td> <td>-1</td>
 274          *<tr align=right><td>-1.6</td> <td>-2</td>
 275          *<tr align=right><td>-2.5</td> <td>-2</td>
 276          *<tr align=right><td>-5.5</td> <td>-6</td>
 277          *</table>
 278          */
 279     HALF_EVEN(BigDecimal.ROUND_HALF_EVEN),
 280 
 281         /**
 282          * Rounding mode to assert that the requested operation has an exact
 283          * result, hence no rounding is necessary.  If this rounding mode is
 284          * specified on an operation that yields an inexact result, an
 285          * {@code ArithmeticException} is thrown.
 286          *<p>Example:
 287          *<table border>
 288          * <caption><b>Rounding mode UNNECESSARY Examples</b></caption>
 289          *<tr valign=top><th>Input Number</th>
 290          *    <th>Input rounded to one digit<br> with {@code UNNECESSARY} rounding
 291          *<tr align=right><td>5.5</td>  <td>throw {@code ArithmeticException}</td>
 292          *<tr align=right><td>2.5</td>  <td>throw {@code ArithmeticException}</td>
 293          *<tr align=right><td>1.6</td>  <td>throw {@code ArithmeticException}</td>
 294          *<tr align=right><td>1.1</td>  <td>throw {@code ArithmeticException}</td>
 295          *<tr align=right><td>1.0</td>  <td>1</td>
 296          *<tr align=right><td>-1.0</td> <td>-1</td>
 297          *<tr align=right><td>-1.1</td> <td>throw {@code ArithmeticException}</td>
 298          *<tr align=right><td>-1.6</td> <td>throw {@code ArithmeticException}</td>
 299          *<tr align=right><td>-2.5</td> <td>throw {@code ArithmeticException}</td>
 300          *<tr align=right><td>-5.5</td> <td>throw {@code ArithmeticException}</td>
 301          *</table>
 302          */
 303     UNNECESSARY(BigDecimal.ROUND_UNNECESSARY);
 304 
 305     // Corresponding BigDecimal rounding constant
 306     final int oldMode;
 307 
 308     /**
 309      * Constructor
 310      *
 311      * @param oldMode The {@code BigDecimal} constant corresponding to
 312      *        this mode
 313      */
 314     private RoundingMode(int oldMode) {
 315         this.oldMode = oldMode;
 316     }
 317 
 318     /**
 319      * Returns the {@code RoundingMode} object corresponding to a
 320      * legacy integer rounding mode constant in {@link BigDecimal}.
 321      *
 322      * @param  rm legacy integer rounding mode to convert
 323      * @return {@code RoundingMode} corresponding to the given integer.
 324      * @throws IllegalArgumentException integer is out of range
 325      */
 326     public static RoundingMode valueOf(int rm) {
 327         switch(rm) {
 328 
 329         case BigDecimal.ROUND_UP:
 330             return UP;
 331 
 332         case BigDecimal.ROUND_DOWN:
 333             return DOWN;
 334 
 335         case BigDecimal.ROUND_CEILING:
 336             return CEILING;
 337 
 338         case BigDecimal.ROUND_FLOOR:
 339             return FLOOR;
 340 
 341         case BigDecimal.ROUND_HALF_UP:
 342             return HALF_UP;
 343 
 344         case BigDecimal.ROUND_HALF_DOWN:
 345             return HALF_DOWN;
 346 
 347         case BigDecimal.ROUND_HALF_EVEN:
 348             return HALF_EVEN;
 349 
 350         case BigDecimal.ROUND_UNNECESSARY:
 351             return UNNECESSARY;
 352 
 353         default:
 354             throw new IllegalArgumentException("argument out of range");
 355         }
 356     }
 357 }