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 public enum RoundingMode {
  94 
  95         /**
  96          * Rounding mode to round away from zero.  Always increments the
  97          * digit prior to a non-zero discarded fraction.  Note that this
  98          * rounding mode never decreases the magnitude of the calculated
  99          * value.
 100          *
 101          *<p>Example:
 102          *<table border>
 103          * <caption><b>Rounding mode UP Examples</b></caption>
 104          *<tr valign=top><th>Input Number</th>
 105          *    <th>Input rounded to one digit<br> with {@code UP} rounding
 106          *<tr align=right><td>5.5</td>  <td>6</td>
 107          *<tr align=right><td>2.5</td>  <td>3</td>
 108          *<tr align=right><td>1.6</td>  <td>2</td>
 109          *<tr align=right><td>1.1</td>  <td>2</td>
 110          *<tr align=right><td>1.0</td>  <td>1</td>
 111          *<tr align=right><td>-1.0</td> <td>-1</td>
 112          *<tr align=right><td>-1.1</td> <td>-2</td>
 113          *<tr align=right><td>-1.6</td> <td>-2</td>
 114          *<tr align=right><td>-2.5</td> <td>-3</td>
 115          *<tr align=right><td>-5.5</td> <td>-6</td>
 116          *</table>
 117          */
 118     UP(BigDecimal.ROUND_UP),
 119 
 120         /**
 121          * Rounding mode to round towards zero.  Never increments the digit
 122          * prior to a discarded fraction (i.e., truncates).  Note that this
 123          * rounding mode never increases the magnitude of the calculated value.
 124          *
 125          *<p>Example:
 126          *<table border>
 127          * <caption><b>Rounding mode DOWN Examples</b></caption>
 128          *<tr valign=top><th>Input Number</th>
 129          *    <th>Input rounded to one digit<br> with {@code DOWN} rounding
 130          *<tr align=right><td>5.5</td>  <td>5</td>
 131          *<tr align=right><td>2.5</td>  <td>2</td>
 132          *<tr align=right><td>1.6</td>  <td>1</td>
 133          *<tr align=right><td>1.1</td>  <td>1</td>
 134          *<tr align=right><td>1.0</td>  <td>1</td>
 135          *<tr align=right><td>-1.0</td> <td>-1</td>
 136          *<tr align=right><td>-1.1</td> <td>-1</td>
 137          *<tr align=right><td>-1.6</td> <td>-1</td>
 138          *<tr align=right><td>-2.5</td> <td>-2</td>
 139          *<tr align=right><td>-5.5</td> <td>-5</td>
 140          *</table>
 141          */
 142     DOWN(BigDecimal.ROUND_DOWN),
 143 
 144         /**
 145          * Rounding mode to round towards positive infinity.  If the
 146          * result is positive, behaves as for {@code RoundingMode.UP};
 147          * if negative, behaves as for {@code RoundingMode.DOWN}.  Note
 148          * that this rounding mode never decreases the calculated value.
 149          *
 150          *<p>Example:
 151          *<table border>
 152          * <caption><b>Rounding mode CEILING Examples</b></caption>
 153          *<tr valign=top><th>Input Number</th>
 154          *    <th>Input rounded to one digit<br> with {@code CEILING} rounding
 155          *<tr align=right><td>5.5</td>  <td>6</td>
 156          *<tr align=right><td>2.5</td>  <td>3</td>
 157          *<tr align=right><td>1.6</td>  <td>2</td>
 158          *<tr align=right><td>1.1</td>  <td>2</td>
 159          *<tr align=right><td>1.0</td>  <td>1</td>
 160          *<tr align=right><td>-1.0</td> <td>-1</td>
 161          *<tr align=right><td>-1.1</td> <td>-1</td>
 162          *<tr align=right><td>-1.6</td> <td>-1</td>
 163          *<tr align=right><td>-2.5</td> <td>-2</td>
 164          *<tr align=right><td>-5.5</td> <td>-5</td>
 165          *</table>
 166          */
 167     CEILING(BigDecimal.ROUND_CEILING),
 168 
 169         /**
 170          * Rounding mode to round towards negative infinity.  If the
 171          * result is positive, behave as for {@code RoundingMode.DOWN};
 172          * if negative, behave as for {@code RoundingMode.UP}.  Note that
 173          * this rounding mode never increases the calculated value.
 174          *
 175          *<p>Example:
 176          *<table border>
 177          * <caption><b>Rounding mode FLOOR Examples</b></caption>
 178          *<tr valign=top><th>Input Number</th>
 179          *    <th>Input rounded to one digit<br> with {@code FLOOR} rounding
 180          *<tr align=right><td>5.5</td>  <td>5</td>
 181          *<tr align=right><td>2.5</td>  <td>2</td>
 182          *<tr align=right><td>1.6</td>  <td>1</td>
 183          *<tr align=right><td>1.1</td>  <td>1</td>
 184          *<tr align=right><td>1.0</td>  <td>1</td>
 185          *<tr align=right><td>-1.0</td> <td>-1</td>
 186          *<tr align=right><td>-1.1</td> <td>-2</td>
 187          *<tr align=right><td>-1.6</td> <td>-2</td>
 188          *<tr align=right><td>-2.5</td> <td>-3</td>
 189          *<tr align=right><td>-5.5</td> <td>-6</td>
 190          *</table>
 191          */
 192     FLOOR(BigDecimal.ROUND_FLOOR),
 193 
 194         /**
 195          * Rounding mode to round towards {@literal "nearest neighbor"}
 196          * unless both neighbors are equidistant, in which case round up.
 197          * Behaves as for {@code RoundingMode.UP} if the discarded
 198          * fraction is &ge; 0.5; otherwise, behaves as for
 199          * {@code RoundingMode.DOWN}.  Note that this is the rounding
 200          * mode commonly taught at school.
 201          *
 202          *<p>Example:
 203          *<table border>
 204          * <caption><b>Rounding mode HALF_UP Examples</b></caption>
 205          *<tr valign=top><th>Input Number</th>
 206          *    <th>Input rounded to one digit<br> with {@code HALF_UP} rounding
 207          *<tr align=right><td>5.5</td>  <td>6</td>
 208          *<tr align=right><td>2.5</td>  <td>3</td>
 209          *<tr align=right><td>1.6</td>  <td>2</td>
 210          *<tr align=right><td>1.1</td>  <td>1</td>
 211          *<tr align=right><td>1.0</td>  <td>1</td>
 212          *<tr align=right><td>-1.0</td> <td>-1</td>
 213          *<tr align=right><td>-1.1</td> <td>-1</td>
 214          *<tr align=right><td>-1.6</td> <td>-2</td>
 215          *<tr align=right><td>-2.5</td> <td>-3</td>
 216          *<tr align=right><td>-5.5</td> <td>-6</td>
 217          *</table>
 218          */
 219     HALF_UP(BigDecimal.ROUND_HALF_UP),
 220 
 221         /**
 222          * Rounding mode to round towards {@literal "nearest neighbor"}
 223          * unless both neighbors are equidistant, in which case round
 224          * down.  Behaves as for {@code RoundingMode.UP} if the discarded
 225          * fraction is &gt; 0.5; otherwise, behaves as for
 226          * {@code RoundingMode.DOWN}.
 227          *
 228          *<p>Example:
 229          *<table border>
 230          * <caption><b>Rounding mode HALF_DOWN Examples</b></caption>
 231          *<tr valign=top><th>Input Number</th>
 232          *    <th>Input rounded to one digit<br> with {@code HALF_DOWN} rounding
 233          *<tr align=right><td>5.5</td>  <td>5</td>
 234          *<tr align=right><td>2.5</td>  <td>2</td>
 235          *<tr align=right><td>1.6</td>  <td>2</td>
 236          *<tr align=right><td>1.1</td>  <td>1</td>
 237          *<tr align=right><td>1.0</td>  <td>1</td>
 238          *<tr align=right><td>-1.0</td> <td>-1</td>
 239          *<tr align=right><td>-1.1</td> <td>-1</td>
 240          *<tr align=right><td>-1.6</td> <td>-2</td>
 241          *<tr align=right><td>-2.5</td> <td>-2</td>
 242          *<tr align=right><td>-5.5</td> <td>-5</td>
 243          *</table>
 244          */
 245     HALF_DOWN(BigDecimal.ROUND_HALF_DOWN),
 246 
 247         /**
 248          * Rounding mode to round towards the {@literal "nearest neighbor"}
 249          * unless both neighbors are equidistant, in which case, round
 250          * towards the even neighbor.  Behaves as for
 251          * {@code RoundingMode.HALF_UP} if the digit to the left of the
 252          * discarded fraction is odd; behaves as for
 253          * {@code RoundingMode.HALF_DOWN} if it's even.  Note that this
 254          * is the rounding mode that statistically minimizes cumulative
 255          * error when applied repeatedly over a sequence of calculations.
 256          * It is sometimes known as {@literal "Banker's rounding,"} and is
 257          * chiefly used in the USA.  This rounding mode is analogous to
 258          * the rounding policy used for {@code float} and {@code double}
 259          * arithmetic in Java.
 260          *
 261          *<p>Example:
 262          *<table border>
 263          * <caption><b>Rounding mode HALF_EVEN Examples</b></caption>
 264          *<tr valign=top><th>Input Number</th>
 265          *    <th>Input rounded to one digit<br> with {@code HALF_EVEN} rounding
 266          *<tr align=right><td>5.5</td>  <td>6</td>
 267          *<tr align=right><td>2.5</td>  <td>2</td>
 268          *<tr align=right><td>1.6</td>  <td>2</td>
 269          *<tr align=right><td>1.1</td>  <td>1</td>
 270          *<tr align=right><td>1.0</td>  <td>1</td>
 271          *<tr align=right><td>-1.0</td> <td>-1</td>
 272          *<tr align=right><td>-1.1</td> <td>-1</td>
 273          *<tr align=right><td>-1.6</td> <td>-2</td>
 274          *<tr align=right><td>-2.5</td> <td>-2</td>
 275          *<tr align=right><td>-5.5</td> <td>-6</td>
 276          *</table>
 277          */
 278     HALF_EVEN(BigDecimal.ROUND_HALF_EVEN),
 279 
 280         /**
 281          * Rounding mode to assert that the requested operation has an exact
 282          * result, hence no rounding is necessary.  If this rounding mode is
 283          * specified on an operation that yields an inexact result, an
 284          * {@code ArithmeticException} is thrown.
 285          *<p>Example:
 286          *<table border>
 287          * <caption><b>Rounding mode UNNECESSARY Examples</b></caption>
 288          *<tr valign=top><th>Input Number</th>
 289          *    <th>Input rounded to one digit<br> with {@code UNNECESSARY} rounding
 290          *<tr align=right><td>5.5</td>  <td>throw {@code ArithmeticException}</td>
 291          *<tr align=right><td>2.5</td>  <td>throw {@code ArithmeticException}</td>
 292          *<tr align=right><td>1.6</td>  <td>throw {@code ArithmeticException}</td>
 293          *<tr align=right><td>1.1</td>  <td>throw {@code ArithmeticException}</td>
 294          *<tr align=right><td>1.0</td>  <td>1</td>
 295          *<tr align=right><td>-1.0</td> <td>-1</td>
 296          *<tr align=right><td>-1.1</td> <td>throw {@code ArithmeticException}</td>
 297          *<tr align=right><td>-1.6</td> <td>throw {@code ArithmeticException}</td>
 298          *<tr align=right><td>-2.5</td> <td>throw {@code ArithmeticException}</td>
 299          *<tr align=right><td>-5.5</td> <td>throw {@code ArithmeticException}</td>
 300          *</table>
 301          */
 302     UNNECESSARY(BigDecimal.ROUND_UNNECESSARY);
 303 
 304     // Corresponding BigDecimal rounding constant
 305     final int oldMode;
 306 
 307     /**
 308      * Constructor
 309      *
 310      * @param oldMode The {@code BigDecimal} constant corresponding to
 311      *        this mode
 312      */
 313     private RoundingMode(int oldMode) {
 314         this.oldMode = oldMode;
 315     }
 316 
 317     /**
 318      * Returns the {@code RoundingMode} object corresponding to a
 319      * legacy integer rounding mode constant in {@link BigDecimal}.
 320      *
 321      * @param  rm legacy integer rounding mode to convert
 322      * @return {@code RoundingMode} corresponding to the given integer.
 323      * @throws IllegalArgumentException integer is out of range
 324      */
 325     public static RoundingMode valueOf(int rm) {
 326         switch(rm) {
 327 
 328         case BigDecimal.ROUND_UP:
 329             return UP;
 330 
 331         case BigDecimal.ROUND_DOWN:
 332             return DOWN;
 333 
 334         case BigDecimal.ROUND_CEILING:
 335             return CEILING;
 336 
 337         case BigDecimal.ROUND_FLOOR:
 338             return FLOOR;
 339 
 340         case BigDecimal.ROUND_HALF_UP:
 341             return HALF_UP;
 342 
 343         case BigDecimal.ROUND_HALF_DOWN:
 344             return HALF_DOWN;
 345 
 346         case BigDecimal.ROUND_HALF_EVEN:
 347             return HALF_EVEN;
 348 
 349         case BigDecimal.ROUND_UNNECESSARY:
 350             return UNNECESSARY;
 351 
 352         default:
 353             throw new IllegalArgumentException("argument out of range");
 354         }
 355     }
 356 }