1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/emul/compact/src/main/java/java/math/RoundingMode.java Sat Sep 07 13:51:24 2013 +0200
1.3 @@ -0,0 +1,349 @@
1.4 +/*
1.5 + * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Oracle designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Oracle in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
1.25 + * or visit www.oracle.com if you need additional information or have any
1.26 + * questions.
1.27 + */
1.28 +
1.29 +/*
1.30 + * Portions Copyright IBM Corporation, 2001. All Rights Reserved.
1.31 + */
1.32 +package java.math;
1.33 +
1.34 +/**
1.35 + * Specifies a <i>rounding behavior</i> for numerical operations
1.36 + * capable of discarding precision. Each rounding mode indicates how
1.37 + * the least significant returned digit of a rounded result is to be
1.38 + * calculated. If fewer digits are returned than the digits needed to
1.39 + * represent the exact numerical result, the discarded digits will be
1.40 + * referred to as the <i>discarded fraction</i> regardless the digits'
1.41 + * contribution to the value of the number. In other words,
1.42 + * considered as a numerical value, the discarded fraction could have
1.43 + * an absolute value greater than one.
1.44 + *
1.45 + * <p>Each rounding mode description includes a table listing how
1.46 + * different two-digit decimal values would round to a one digit
1.47 + * decimal value under the rounding mode in question. The result
1.48 + * column in the tables could be gotten by creating a
1.49 + * {@code BigDecimal} number with the specified value, forming a
1.50 + * {@link MathContext} object with the proper settings
1.51 + * ({@code precision} set to {@code 1}, and the
1.52 + * {@code roundingMode} set to the rounding mode in question), and
1.53 + * calling {@link BigDecimal#round round} on this number with the
1.54 + * proper {@code MathContext}. A summary table showing the results
1.55 + * of these rounding operations for all rounding modes appears below.
1.56 + *
1.57 + *<p>
1.58 + *<table border>
1.59 + * <caption><b>Summary of Rounding Operations Under Different Rounding Modes</b></caption>
1.60 + * <tr><th></th><th colspan=8>Result of rounding input to one digit with the given
1.61 + * rounding mode</th>
1.62 + * <tr valign=top>
1.63 + * <th>Input Number</th> <th>{@code UP}</th>
1.64 + * <th>{@code DOWN}</th>
1.65 + * <th>{@code CEILING}</th>
1.66 + * <th>{@code FLOOR}</th>
1.67 + * <th>{@code HALF_UP}</th>
1.68 + * <th>{@code HALF_DOWN}</th>
1.69 + * <th>{@code HALF_EVEN}</th>
1.70 + * <th>{@code UNNECESSARY}</th>
1.71 + *
1.72 + * <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>
1.73 + * <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>
1.74 + * <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>
1.75 + * <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>
1.76 + * <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>
1.77 + * <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>
1.78 + * <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>
1.79 + * <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>
1.80 + * <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>
1.81 + * <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>
1.82 + *</table>
1.83 + *
1.84 + *
1.85 + * <p>This {@code enum} is intended to replace the integer-based
1.86 + * enumeration of rounding mode constants in {@link BigDecimal}
1.87 + * ({@link BigDecimal#ROUND_UP}, {@link BigDecimal#ROUND_DOWN},
1.88 + * etc. ).
1.89 + *
1.90 + * @see BigDecimal
1.91 + * @see MathContext
1.92 + * @author Josh Bloch
1.93 + * @author Mike Cowlishaw
1.94 + * @author Joseph D. Darcy
1.95 + * @since 1.5
1.96 + */
1.97 +public enum RoundingMode {
1.98 +
1.99 + /**
1.100 + * Rounding mode to round away from zero. Always increments the
1.101 + * digit prior to a non-zero discarded fraction. Note that this
1.102 + * rounding mode never decreases the magnitude of the calculated
1.103 + * value.
1.104 + *
1.105 + *<p>Example:
1.106 + *<table border>
1.107 + *<tr valign=top><th>Input Number</th>
1.108 + * <th>Input rounded to one digit<br> with {@code UP} rounding
1.109 + *<tr align=right><td>5.5</td> <td>6</td>
1.110 + *<tr align=right><td>2.5</td> <td>3</td>
1.111 + *<tr align=right><td>1.6</td> <td>2</td>
1.112 + *<tr align=right><td>1.1</td> <td>2</td>
1.113 + *<tr align=right><td>1.0</td> <td>1</td>
1.114 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.115 + *<tr align=right><td>-1.1</td> <td>-2</td>
1.116 + *<tr align=right><td>-1.6</td> <td>-2</td>
1.117 + *<tr align=right><td>-2.5</td> <td>-3</td>
1.118 + *<tr align=right><td>-5.5</td> <td>-6</td>
1.119 + *</table>
1.120 + */
1.121 + UP(BigDecimal.ROUND_UP),
1.122 +
1.123 + /**
1.124 + * Rounding mode to round towards zero. Never increments the digit
1.125 + * prior to a discarded fraction (i.e., truncates). Note that this
1.126 + * rounding mode never increases the magnitude of the calculated value.
1.127 + *
1.128 + *<p>Example:
1.129 + *<table border>
1.130 + *<tr valign=top><th>Input Number</th>
1.131 + * <th>Input rounded to one digit<br> with {@code DOWN} rounding
1.132 + *<tr align=right><td>5.5</td> <td>5</td>
1.133 + *<tr align=right><td>2.5</td> <td>2</td>
1.134 + *<tr align=right><td>1.6</td> <td>1</td>
1.135 + *<tr align=right><td>1.1</td> <td>1</td>
1.136 + *<tr align=right><td>1.0</td> <td>1</td>
1.137 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.138 + *<tr align=right><td>-1.1</td> <td>-1</td>
1.139 + *<tr align=right><td>-1.6</td> <td>-1</td>
1.140 + *<tr align=right><td>-2.5</td> <td>-2</td>
1.141 + *<tr align=right><td>-5.5</td> <td>-5</td>
1.142 + *</table>
1.143 + */
1.144 + DOWN(BigDecimal.ROUND_DOWN),
1.145 +
1.146 + /**
1.147 + * Rounding mode to round towards positive infinity. If the
1.148 + * result is positive, behaves as for {@code RoundingMode.UP};
1.149 + * if negative, behaves as for {@code RoundingMode.DOWN}. Note
1.150 + * that this rounding mode never decreases the calculated value.
1.151 + *
1.152 + *<p>Example:
1.153 + *<table border>
1.154 + *<tr valign=top><th>Input Number</th>
1.155 + * <th>Input rounded to one digit<br> with {@code CEILING} rounding
1.156 + *<tr align=right><td>5.5</td> <td>6</td>
1.157 + *<tr align=right><td>2.5</td> <td>3</td>
1.158 + *<tr align=right><td>1.6</td> <td>2</td>
1.159 + *<tr align=right><td>1.1</td> <td>2</td>
1.160 + *<tr align=right><td>1.0</td> <td>1</td>
1.161 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.162 + *<tr align=right><td>-1.1</td> <td>-1</td>
1.163 + *<tr align=right><td>-1.6</td> <td>-1</td>
1.164 + *<tr align=right><td>-2.5</td> <td>-2</td>
1.165 + *<tr align=right><td>-5.5</td> <td>-5</td>
1.166 + *</table>
1.167 + */
1.168 + CEILING(BigDecimal.ROUND_CEILING),
1.169 +
1.170 + /**
1.171 + * Rounding mode to round towards negative infinity. If the
1.172 + * result is positive, behave as for {@code RoundingMode.DOWN};
1.173 + * if negative, behave as for {@code RoundingMode.UP}. Note that
1.174 + * this rounding mode never increases the calculated value.
1.175 + *
1.176 + *<p>Example:
1.177 + *<table border>
1.178 + *<tr valign=top><th>Input Number</th>
1.179 + * <th>Input rounded to one digit<br> with {@code FLOOR} rounding
1.180 + *<tr align=right><td>5.5</td> <td>5</td>
1.181 + *<tr align=right><td>2.5</td> <td>2</td>
1.182 + *<tr align=right><td>1.6</td> <td>1</td>
1.183 + *<tr align=right><td>1.1</td> <td>1</td>
1.184 + *<tr align=right><td>1.0</td> <td>1</td>
1.185 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.186 + *<tr align=right><td>-1.1</td> <td>-2</td>
1.187 + *<tr align=right><td>-1.6</td> <td>-2</td>
1.188 + *<tr align=right><td>-2.5</td> <td>-3</td>
1.189 + *<tr align=right><td>-5.5</td> <td>-6</td>
1.190 + *</table>
1.191 + */
1.192 + FLOOR(BigDecimal.ROUND_FLOOR),
1.193 +
1.194 + /**
1.195 + * Rounding mode to round towards {@literal "nearest neighbor"}
1.196 + * unless both neighbors are equidistant, in which case round up.
1.197 + * Behaves as for {@code RoundingMode.UP} if the discarded
1.198 + * fraction is ≥ 0.5; otherwise, behaves as for
1.199 + * {@code RoundingMode.DOWN}. Note that this is the rounding
1.200 + * mode commonly taught at school.
1.201 + *
1.202 + *<p>Example:
1.203 + *<table border>
1.204 + *<tr valign=top><th>Input Number</th>
1.205 + * <th>Input rounded to one digit<br> with {@code HALF_UP} rounding
1.206 + *<tr align=right><td>5.5</td> <td>6</td>
1.207 + *<tr align=right><td>2.5</td> <td>3</td>
1.208 + *<tr align=right><td>1.6</td> <td>2</td>
1.209 + *<tr align=right><td>1.1</td> <td>1</td>
1.210 + *<tr align=right><td>1.0</td> <td>1</td>
1.211 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.212 + *<tr align=right><td>-1.1</td> <td>-1</td>
1.213 + *<tr align=right><td>-1.6</td> <td>-2</td>
1.214 + *<tr align=right><td>-2.5</td> <td>-3</td>
1.215 + *<tr align=right><td>-5.5</td> <td>-6</td>
1.216 + *</table>
1.217 + */
1.218 + HALF_UP(BigDecimal.ROUND_HALF_UP),
1.219 +
1.220 + /**
1.221 + * Rounding mode to round towards {@literal "nearest neighbor"}
1.222 + * unless both neighbors are equidistant, in which case round
1.223 + * down. Behaves as for {@code RoundingMode.UP} if the discarded
1.224 + * fraction is > 0.5; otherwise, behaves as for
1.225 + * {@code RoundingMode.DOWN}.
1.226 + *
1.227 + *<p>Example:
1.228 + *<table border>
1.229 + *<tr valign=top><th>Input Number</th>
1.230 + * <th>Input rounded to one digit<br> with {@code HALF_DOWN} rounding
1.231 + *<tr align=right><td>5.5</td> <td>5</td>
1.232 + *<tr align=right><td>2.5</td> <td>2</td>
1.233 + *<tr align=right><td>1.6</td> <td>2</td>
1.234 + *<tr align=right><td>1.1</td> <td>1</td>
1.235 + *<tr align=right><td>1.0</td> <td>1</td>
1.236 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.237 + *<tr align=right><td>-1.1</td> <td>-1</td>
1.238 + *<tr align=right><td>-1.6</td> <td>-2</td>
1.239 + *<tr align=right><td>-2.5</td> <td>-2</td>
1.240 + *<tr align=right><td>-5.5</td> <td>-5</td>
1.241 + *</table>
1.242 + */
1.243 + HALF_DOWN(BigDecimal.ROUND_HALF_DOWN),
1.244 +
1.245 + /**
1.246 + * Rounding mode to round towards the {@literal "nearest neighbor"}
1.247 + * unless both neighbors are equidistant, in which case, round
1.248 + * towards the even neighbor. Behaves as for
1.249 + * {@code RoundingMode.HALF_UP} if the digit to the left of the
1.250 + * discarded fraction is odd; behaves as for
1.251 + * {@code RoundingMode.HALF_DOWN} if it's even. Note that this
1.252 + * is the rounding mode that statistically minimizes cumulative
1.253 + * error when applied repeatedly over a sequence of calculations.
1.254 + * It is sometimes known as {@literal "Banker's rounding,"} and is
1.255 + * chiefly used in the USA. This rounding mode is analogous to
1.256 + * the rounding policy used for {@code float} and {@code double}
1.257 + * arithmetic in Java.
1.258 + *
1.259 + *<p>Example:
1.260 + *<table border>
1.261 + *<tr valign=top><th>Input Number</th>
1.262 + * <th>Input rounded to one digit<br> with {@code HALF_EVEN} rounding
1.263 + *<tr align=right><td>5.5</td> <td>6</td>
1.264 + *<tr align=right><td>2.5</td> <td>2</td>
1.265 + *<tr align=right><td>1.6</td> <td>2</td>
1.266 + *<tr align=right><td>1.1</td> <td>1</td>
1.267 + *<tr align=right><td>1.0</td> <td>1</td>
1.268 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.269 + *<tr align=right><td>-1.1</td> <td>-1</td>
1.270 + *<tr align=right><td>-1.6</td> <td>-2</td>
1.271 + *<tr align=right><td>-2.5</td> <td>-2</td>
1.272 + *<tr align=right><td>-5.5</td> <td>-6</td>
1.273 + *</table>
1.274 + */
1.275 + HALF_EVEN(BigDecimal.ROUND_HALF_EVEN),
1.276 +
1.277 + /**
1.278 + * Rounding mode to assert that the requested operation has an exact
1.279 + * result, hence no rounding is necessary. If this rounding mode is
1.280 + * specified on an operation that yields an inexact result, an
1.281 + * {@code ArithmeticException} is thrown.
1.282 + *<p>Example:
1.283 + *<table border>
1.284 + *<tr valign=top><th>Input Number</th>
1.285 + * <th>Input rounded to one digit<br> with {@code UNNECESSARY} rounding
1.286 + *<tr align=right><td>5.5</td> <td>throw {@code ArithmeticException}</td>
1.287 + *<tr align=right><td>2.5</td> <td>throw {@code ArithmeticException}</td>
1.288 + *<tr align=right><td>1.6</td> <td>throw {@code ArithmeticException}</td>
1.289 + *<tr align=right><td>1.1</td> <td>throw {@code ArithmeticException}</td>
1.290 + *<tr align=right><td>1.0</td> <td>1</td>
1.291 + *<tr align=right><td>-1.0</td> <td>-1</td>
1.292 + *<tr align=right><td>-1.1</td> <td>throw {@code ArithmeticException}</td>
1.293 + *<tr align=right><td>-1.6</td> <td>throw {@code ArithmeticException}</td>
1.294 + *<tr align=right><td>-2.5</td> <td>throw {@code ArithmeticException}</td>
1.295 + *<tr align=right><td>-5.5</td> <td>throw {@code ArithmeticException}</td>
1.296 + *</table>
1.297 + */
1.298 + UNNECESSARY(BigDecimal.ROUND_UNNECESSARY);
1.299 +
1.300 + // Corresponding BigDecimal rounding constant
1.301 + final int oldMode;
1.302 +
1.303 + /**
1.304 + * Constructor
1.305 + *
1.306 + * @param oldMode The {@code BigDecimal} constant corresponding to
1.307 + * this mode
1.308 + */
1.309 + private RoundingMode(int oldMode) {
1.310 + this.oldMode = oldMode;
1.311 + }
1.312 +
1.313 + /**
1.314 + * Returns the {@code RoundingMode} object corresponding to a
1.315 + * legacy integer rounding mode constant in {@link BigDecimal}.
1.316 + *
1.317 + * @param rm legacy integer rounding mode to convert
1.318 + * @return {@code RoundingMode} corresponding to the given integer.
1.319 + * @throws IllegalArgumentException integer is out of range
1.320 + */
1.321 + public static RoundingMode valueOf(int rm) {
1.322 + switch(rm) {
1.323 +
1.324 + case BigDecimal.ROUND_UP:
1.325 + return UP;
1.326 +
1.327 + case BigDecimal.ROUND_DOWN:
1.328 + return DOWN;
1.329 +
1.330 + case BigDecimal.ROUND_CEILING:
1.331 + return CEILING;
1.332 +
1.333 + case BigDecimal.ROUND_FLOOR:
1.334 + return FLOOR;
1.335 +
1.336 + case BigDecimal.ROUND_HALF_UP:
1.337 + return HALF_UP;
1.338 +
1.339 + case BigDecimal.ROUND_HALF_DOWN:
1.340 + return HALF_DOWN;
1.341 +
1.342 + case BigDecimal.ROUND_HALF_EVEN:
1.343 + return HALF_EVEN;
1.344 +
1.345 + case BigDecimal.ROUND_UNNECESSARY:
1.346 + return UNNECESSARY;
1.347 +
1.348 + default:
1.349 + throw new IllegalArgumentException("argument out of range");
1.350 + }
1.351 + }
1.352 +}