View Javadoc
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 }