70 *
71 * <tr><th scope="row">5.5</th> <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>
72 * <tr><th scope="row">2.5</th> <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>
73 * <tr><th scope="row">1.6</th> <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>
74 * <tr><th scope="row">1.1</th> <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>
75 * <tr><th scope="row">1.0</th> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td>
76 * <tr><th scope="row">-1.0</th> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td>
77 * <tr><th scope="row">-1.1</th> <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>
78 * <tr><th scope="row">-1.6</th> <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>
79 * <tr><th scope="row">-2.5</th> <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>
80 * <tr><th scope="row">-5.5</th> <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>
81 * </tbody>
82 * </table>
83 *
84 *
85 * <p>This {@code enum} is intended to replace the integer-based
86 * enumeration of rounding mode constants in {@link BigDecimal}
87 * ({@link BigDecimal#ROUND_UP}, {@link BigDecimal#ROUND_DOWN},
88 * etc. ).
89 *
90 * @see BigDecimal
91 * @see MathContext
92 * @author Josh Bloch
93 * @author Mike Cowlishaw
94 * @author Joseph D. Darcy
95 * @since 1.5
96 */
97 @SuppressWarnings("deprecation") // Legacy rounding mode constants in BigDecimal
98 public enum RoundingMode {
99
100 /**
101 * Rounding mode to round away from zero. Always increments the
102 * digit prior to a non-zero discarded fraction. Note that this
103 * rounding mode never decreases the magnitude of the calculated
104 * value.
105 *
106 *<p>Example:
107 *<table class="striped">
108 * <caption>Rounding mode UP Examples</caption>
109 *<thead>
113 *<tbody style="text-align:right">
114 *<tr><th scope="row">5.5</th> <td>6</td>
115 *<tr><th scope="row">2.5</th> <td>3</td>
116 *<tr><th scope="row">1.6</th> <td>2</td>
117 *<tr><th scope="row">1.1</th> <td>2</td>
118 *<tr><th scope="row">1.0</th> <td>1</td>
119 *<tr><th scope="row">-1.0</th> <td>-1</td>
120 *<tr><th scope="row">-1.1</th> <td>-2</td>
121 *<tr><th scope="row">-1.6</th> <td>-2</td>
122 *<tr><th scope="row">-2.5</th> <td>-3</td>
123 *<tr><th scope="row">-5.5</th> <td>-6</td>
124 *</tbody>
125 *</table>
126 */
127 UP(BigDecimal.ROUND_UP),
128
129 /**
130 * Rounding mode to round towards zero. Never increments the digit
131 * prior to a discarded fraction (i.e., truncates). Note that this
132 * rounding mode never increases the magnitude of the calculated value.
133 *
134 *<p>Example:
135 *<table class="striped">
136 * <caption>Rounding mode DOWN Examples</caption>
137 *<thead>
138 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
139 * <th scope="col">Input rounded to one digit<br> with {@code DOWN} rounding
140 *</thead>
141 *<tbody style="text-align:right">
142 *<tr><th scope="row">5.5</th> <td>5</td>
143 *<tr><th scope="row">2.5</th> <td>2</td>
144 *<tr><th scope="row">1.6</th> <td>1</td>
145 *<tr><th scope="row">1.1</th> <td>1</td>
146 *<tr><th scope="row">1.0</th> <td>1</td>
147 *<tr><th scope="row">-1.0</th> <td>-1</td>
148 *<tr><th scope="row">-1.1</th> <td>-1</td>
149 *<tr><th scope="row">-1.6</th> <td>-1</td>
150 *<tr><th scope="row">-2.5</th> <td>-2</td>
151 *<tr><th scope="row">-5.5</th> <td>-5</td>
152 *</tbody>
153 *</table>
154 */
155 DOWN(BigDecimal.ROUND_DOWN),
156
157 /**
158 * Rounding mode to round towards positive infinity. If the
159 * result is positive, behaves as for {@code RoundingMode.UP};
160 * if negative, behaves as for {@code RoundingMode.DOWN}. Note
161 * that this rounding mode never decreases the calculated value.
162 *
163 *<p>Example:
164 *<table class="striped">
165 * <caption>Rounding mode CEILING Examples</caption>
166 *<thead>
167 *<tr style="vertical-align:top"><th>Input Number</th>
168 * <th>Input rounded to one digit<br> with {@code CEILING} rounding
169 *</thead>
170 *<tbody style="text-align:right">
171 *<tr><th scope="row">5.5</th> <td>6</td>
172 *<tr><th scope="row">2.5</th> <td>3</td>
173 *<tr><th scope="row">1.6</th> <td>2</td>
174 *<tr><th scope="row">1.1</th> <td>2</td>
175 *<tr><th scope="row">1.0</th> <td>1</td>
176 *<tr><th scope="row">-1.0</th> <td>-1</td>
177 *<tr><th scope="row">-1.1</th> <td>-1</td>
178 *<tr><th scope="row">-1.6</th> <td>-1</td>
179 *<tr><th scope="row">-2.5</th> <td>-2</td>
180 *<tr><th scope="row">-5.5</th> <td>-5</td>
181 *</tbody>
182 *</table>
183 */
184 CEILING(BigDecimal.ROUND_CEILING),
185
186 /**
187 * Rounding mode to round towards negative infinity. If the
188 * result is positive, behave as for {@code RoundingMode.DOWN};
189 * if negative, behave as for {@code RoundingMode.UP}. Note that
190 * this rounding mode never increases the calculated value.
191 *
192 *<p>Example:
193 *<table class="striped">
194 * <caption>Rounding mode FLOOR Examples</caption>
195 *<thead>
196 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
197 * <th scope="col">Input rounded to one digit<br> with {@code FLOOR} rounding
198 *</thead>
199 *<tbody style="text-align:right">
200 *<tr><th scope="row">5.5</th> <td>5</td>
201 *<tr><th scope="row">2.5</th> <td>2</td>
202 *<tr><th scope="row">1.6</th> <td>1</td>
203 *<tr><th scope="row">1.1</th> <td>1</td>
204 *<tr><th scope="row">1.0</th> <td>1</td>
205 *<tr><th scope="row">-1.0</th> <td>-1</td>
206 *<tr><th scope="row">-1.1</th> <td>-2</td>
207 *<tr><th scope="row">-1.6</th> <td>-2</td>
208 *<tr><th scope="row">-2.5</th> <td>-3</td>
209 *<tr><th scope="row">-5.5</th> <td>-6</td>
210 *</tbody>
211 *</table>
212 */
213 FLOOR(BigDecimal.ROUND_FLOOR),
214
215 /**
216 * Rounding mode to round towards {@literal "nearest neighbor"}
217 * unless both neighbors are equidistant, in which case round up.
218 * Behaves as for {@code RoundingMode.UP} if the discarded
219 * fraction is ≥ 0.5; otherwise, behaves as for
220 * {@code RoundingMode.DOWN}. Note that this is the rounding
221 * mode commonly taught at school.
222 *
223 *<p>Example:
224 *<table class="striped">
225 * <caption>Rounding mode HALF_UP Examples</caption>
226 *<thead>
227 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
228 * <th scope="col">Input rounded to one digit<br> with {@code HALF_UP} rounding
229 *</thead>
230 *<tbody style="text-align:right">
231 *<tr><th scope="row">5.5</th> <td>6</td>
232 *<tr><th scope="row">2.5</th> <td>3</td>
233 *<tr><th scope="row">1.6</th> <td>2</td>
234 *<tr><th scope="row">1.1</th> <td>1</td>
235 *<tr><th scope="row">1.0</th> <td>1</td>
236 *<tr><th scope="row">-1.0</th> <td>-1</td>
237 *<tr><th scope="row">-1.1</th> <td>-1</td>
238 *<tr><th scope="row">-1.6</th> <td>-2</td>
239 *<tr><th scope="row">-2.5</th> <td>-3</td>
240 *<tr><th scope="row">-5.5</th> <td>-6</td>
241 *</tbody>
269 *<tr><th scope="row">-2.5</th> <td>-2</td>
270 *<tr><th scope="row">-5.5</th> <td>-5</td>
271 *</tbody>
272 *</table>
273 */
274 HALF_DOWN(BigDecimal.ROUND_HALF_DOWN),
275
276 /**
277 * Rounding mode to round towards the {@literal "nearest neighbor"}
278 * unless both neighbors are equidistant, in which case, round
279 * towards the even neighbor. Behaves as for
280 * {@code RoundingMode.HALF_UP} if the digit to the left of the
281 * discarded fraction is odd; behaves as for
282 * {@code RoundingMode.HALF_DOWN} if it's even. Note that this
283 * is the rounding mode that statistically minimizes cumulative
284 * error when applied repeatedly over a sequence of calculations.
285 * It is sometimes known as {@literal "Banker's rounding,"} and is
286 * chiefly used in the USA. This rounding mode is analogous to
287 * the rounding policy used for {@code float} and {@code double}
288 * arithmetic in Java.
289 *
290 *<p>Example:
291 *<table class="striped">
292 * <caption>Rounding mode HALF_EVEN Examples</caption>
293 *<thead>
294 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
295 * <th scope="col">Input rounded to one digit<br> with {@code HALF_EVEN} rounding
296 *</thead>
297 *<tbody style="text-align:right">
298 *<tr><th scope="row">5.5</th> <td>6</td>
299 *<tr><th scope="row">2.5</th> <td>2</td>
300 *<tr><th scope="row">1.6</th> <td>2</td>
301 *<tr><th scope="row">1.1</th> <td>1</td>
302 *<tr><th scope="row">1.0</th> <td>1</td>
303 *<tr><th scope="row">-1.0</th> <td>-1</td>
304 *<tr><th scope="row">-1.1</th> <td>-1</td>
305 *<tr><th scope="row">-1.6</th> <td>-2</td>
306 *<tr><th scope="row">-2.5</th> <td>-2</td>
307 *<tr><th scope="row">-5.5</th> <td>-6</td>
308 *</tbody>
|
70 *
71 * <tr><th scope="row">5.5</th> <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>
72 * <tr><th scope="row">2.5</th> <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>
73 * <tr><th scope="row">1.6</th> <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>
74 * <tr><th scope="row">1.1</th> <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>
75 * <tr><th scope="row">1.0</th> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td> <td>1</td>
76 * <tr><th scope="row">-1.0</th> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td> <td>-1</td>
77 * <tr><th scope="row">-1.1</th> <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>
78 * <tr><th scope="row">-1.6</th> <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>
79 * <tr><th scope="row">-2.5</th> <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>
80 * <tr><th scope="row">-5.5</th> <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>
81 * </tbody>
82 * </table>
83 *
84 *
85 * <p>This {@code enum} is intended to replace the integer-based
86 * enumeration of rounding mode constants in {@link BigDecimal}
87 * ({@link BigDecimal#ROUND_UP}, {@link BigDecimal#ROUND_DOWN},
88 * etc. ).
89 *
90 * @apiNote
91 * Five of the rounding modes defined in this class correspond to
92 * rounding direction attributes defined in IEEE 754-2019. Where
93 * present, this correspondence will be noted in the documentation of
94 * the particular constant.
95 *
96 * @see BigDecimal
97 * @see MathContext
98 * @author Josh Bloch
99 * @author Mike Cowlishaw
100 * @author Joseph D. Darcy
101 * @since 1.5
102 */
103 @SuppressWarnings("deprecation") // Legacy rounding mode constants in BigDecimal
104 public enum RoundingMode {
105
106 /**
107 * Rounding mode to round away from zero. Always increments the
108 * digit prior to a non-zero discarded fraction. Note that this
109 * rounding mode never decreases the magnitude of the calculated
110 * value.
111 *
112 *<p>Example:
113 *<table class="striped">
114 * <caption>Rounding mode UP Examples</caption>
115 *<thead>
119 *<tbody style="text-align:right">
120 *<tr><th scope="row">5.5</th> <td>6</td>
121 *<tr><th scope="row">2.5</th> <td>3</td>
122 *<tr><th scope="row">1.6</th> <td>2</td>
123 *<tr><th scope="row">1.1</th> <td>2</td>
124 *<tr><th scope="row">1.0</th> <td>1</td>
125 *<tr><th scope="row">-1.0</th> <td>-1</td>
126 *<tr><th scope="row">-1.1</th> <td>-2</td>
127 *<tr><th scope="row">-1.6</th> <td>-2</td>
128 *<tr><th scope="row">-2.5</th> <td>-3</td>
129 *<tr><th scope="row">-5.5</th> <td>-6</td>
130 *</tbody>
131 *</table>
132 */
133 UP(BigDecimal.ROUND_UP),
134
135 /**
136 * Rounding mode to round towards zero. Never increments the digit
137 * prior to a discarded fraction (i.e., truncates). Note that this
138 * rounding mode never increases the magnitude of the calculated value.
139 * This mode corresponds to the IEEE 754-2019 rounding
140 * attribute roundTowardZero.
141 *
142 *<p>Example:
143 *<table class="striped">
144 * <caption>Rounding mode DOWN Examples</caption>
145 *<thead>
146 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
147 * <th scope="col">Input rounded to one digit<br> with {@code DOWN} rounding
148 *</thead>
149 *<tbody style="text-align:right">
150 *<tr><th scope="row">5.5</th> <td>5</td>
151 *<tr><th scope="row">2.5</th> <td>2</td>
152 *<tr><th scope="row">1.6</th> <td>1</td>
153 *<tr><th scope="row">1.1</th> <td>1</td>
154 *<tr><th scope="row">1.0</th> <td>1</td>
155 *<tr><th scope="row">-1.0</th> <td>-1</td>
156 *<tr><th scope="row">-1.1</th> <td>-1</td>
157 *<tr><th scope="row">-1.6</th> <td>-1</td>
158 *<tr><th scope="row">-2.5</th> <td>-2</td>
159 *<tr><th scope="row">-5.5</th> <td>-5</td>
160 *</tbody>
161 *</table>
162 */
163 DOWN(BigDecimal.ROUND_DOWN),
164
165 /**
166 * Rounding mode to round towards positive infinity. If the
167 * result is positive, behaves as for {@code RoundingMode.UP};
168 * if negative, behaves as for {@code RoundingMode.DOWN}. Note
169 * that this rounding mode never decreases the calculated value.
170 * This mode corresponds to the IEEE 754-2019 rounding
171 * attribute roundTowardPositive.
172 *
173 *<p>Example:
174 *<table class="striped">
175 * <caption>Rounding mode CEILING Examples</caption>
176 *<thead>
177 *<tr style="vertical-align:top"><th>Input Number</th>
178 * <th>Input rounded to one digit<br> with {@code CEILING} rounding
179 *</thead>
180 *<tbody style="text-align:right">
181 *<tr><th scope="row">5.5</th> <td>6</td>
182 *<tr><th scope="row">2.5</th> <td>3</td>
183 *<tr><th scope="row">1.6</th> <td>2</td>
184 *<tr><th scope="row">1.1</th> <td>2</td>
185 *<tr><th scope="row">1.0</th> <td>1</td>
186 *<tr><th scope="row">-1.0</th> <td>-1</td>
187 *<tr><th scope="row">-1.1</th> <td>-1</td>
188 *<tr><th scope="row">-1.6</th> <td>-1</td>
189 *<tr><th scope="row">-2.5</th> <td>-2</td>
190 *<tr><th scope="row">-5.5</th> <td>-5</td>
191 *</tbody>
192 *</table>
193 */
194 CEILING(BigDecimal.ROUND_CEILING),
195
196 /**
197 * Rounding mode to round towards negative infinity. If the
198 * result is positive, behave as for {@code RoundingMode.DOWN};
199 * if negative, behave as for {@code RoundingMode.UP}. Note that
200 * this rounding mode never increases the calculated value.
201 * This mode corresponds to the IEEE 754-2019 rounding
202 * attribute roundTowardNegative.
203 *
204 *<p>Example:
205 *<table class="striped">
206 * <caption>Rounding mode FLOOR Examples</caption>
207 *<thead>
208 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
209 * <th scope="col">Input rounded to one digit<br> with {@code FLOOR} rounding
210 *</thead>
211 *<tbody style="text-align:right">
212 *<tr><th scope="row">5.5</th> <td>5</td>
213 *<tr><th scope="row">2.5</th> <td>2</td>
214 *<tr><th scope="row">1.6</th> <td>1</td>
215 *<tr><th scope="row">1.1</th> <td>1</td>
216 *<tr><th scope="row">1.0</th> <td>1</td>
217 *<tr><th scope="row">-1.0</th> <td>-1</td>
218 *<tr><th scope="row">-1.1</th> <td>-2</td>
219 *<tr><th scope="row">-1.6</th> <td>-2</td>
220 *<tr><th scope="row">-2.5</th> <td>-3</td>
221 *<tr><th scope="row">-5.5</th> <td>-6</td>
222 *</tbody>
223 *</table>
224 */
225 FLOOR(BigDecimal.ROUND_FLOOR),
226
227 /**
228 * Rounding mode to round towards {@literal "nearest neighbor"}
229 * unless both neighbors are equidistant, in which case round up.
230 * Behaves as for {@code RoundingMode.UP} if the discarded
231 * fraction is ≥ 0.5; otherwise, behaves as for
232 * {@code RoundingMode.DOWN}. Note that this is the rounding
233 * mode commonly taught at school.
234 * This mode corresponds to the IEEE 754-2019 rounding
235 * attribute roundTiesToAway.
236 *
237 *<p>Example:
238 *<table class="striped">
239 * <caption>Rounding mode HALF_UP Examples</caption>
240 *<thead>
241 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
242 * <th scope="col">Input rounded to one digit<br> with {@code HALF_UP} rounding
243 *</thead>
244 *<tbody style="text-align:right">
245 *<tr><th scope="row">5.5</th> <td>6</td>
246 *<tr><th scope="row">2.5</th> <td>3</td>
247 *<tr><th scope="row">1.6</th> <td>2</td>
248 *<tr><th scope="row">1.1</th> <td>1</td>
249 *<tr><th scope="row">1.0</th> <td>1</td>
250 *<tr><th scope="row">-1.0</th> <td>-1</td>
251 *<tr><th scope="row">-1.1</th> <td>-1</td>
252 *<tr><th scope="row">-1.6</th> <td>-2</td>
253 *<tr><th scope="row">-2.5</th> <td>-3</td>
254 *<tr><th scope="row">-5.5</th> <td>-6</td>
255 *</tbody>
283 *<tr><th scope="row">-2.5</th> <td>-2</td>
284 *<tr><th scope="row">-5.5</th> <td>-5</td>
285 *</tbody>
286 *</table>
287 */
288 HALF_DOWN(BigDecimal.ROUND_HALF_DOWN),
289
290 /**
291 * Rounding mode to round towards the {@literal "nearest neighbor"}
292 * unless both neighbors are equidistant, in which case, round
293 * towards the even neighbor. Behaves as for
294 * {@code RoundingMode.HALF_UP} if the digit to the left of the
295 * discarded fraction is odd; behaves as for
296 * {@code RoundingMode.HALF_DOWN} if it's even. Note that this
297 * is the rounding mode that statistically minimizes cumulative
298 * error when applied repeatedly over a sequence of calculations.
299 * It is sometimes known as {@literal "Banker's rounding,"} and is
300 * chiefly used in the USA. This rounding mode is analogous to
301 * the rounding policy used for {@code float} and {@code double}
302 * arithmetic in Java.
303 * This mode corresponds to the IEEE 754-2019 rounding
304 * attribute roundTiesToEven.
305 *
306 *<p>Example:
307 *<table class="striped">
308 * <caption>Rounding mode HALF_EVEN Examples</caption>
309 *<thead>
310 *<tr style="vertical-align:top"><th scope="col">Input Number</th>
311 * <th scope="col">Input rounded to one digit<br> with {@code HALF_EVEN} rounding
312 *</thead>
313 *<tbody style="text-align:right">
314 *<tr><th scope="row">5.5</th> <td>6</td>
315 *<tr><th scope="row">2.5</th> <td>2</td>
316 *<tr><th scope="row">1.6</th> <td>2</td>
317 *<tr><th scope="row">1.1</th> <td>1</td>
318 *<tr><th scope="row">1.0</th> <td>1</td>
319 *<tr><th scope="row">-1.0</th> <td>-1</td>
320 *<tr><th scope="row">-1.1</th> <td>-1</td>
321 *<tr><th scope="row">-1.6</th> <td>-2</td>
322 *<tr><th scope="row">-2.5</th> <td>-2</td>
323 *<tr><th scope="row">-5.5</th> <td>-6</td>
324 *</tbody>
|