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