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>
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 ≥ 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 > 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
|
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 summary="Summary of rounding operations">
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>
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 summary="Rounding mode UP examples">
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 summary="Rounding mode DOWN examples">
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 summary="Rounding mode CEILING examples">
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 summary="Rounding mode FLOOR examples">
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 ≥ 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 summary="Rounding mode HALF_UP examples">
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 > 0.5; otherwise, behaves as for
226 * {@code RoundingMode.DOWN}.
227 *
228 *<p>Example:
229 *<table border summary="Rounding mode HALF_DOWN examples">
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 summary="Rounding mode HALF_EVEN examples">
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 summary="Rounding mode UNNECESSARY examples">
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
|