java.math.BigDecimal Maven / Gradle / Ivy

Neither this file nor any files generated from it describe a complete specification, and they may only be used as described below. For example, no permission is given for you to incorporate this file, in whole or in part, in an implementation of a Java specification.

Sun Microsystems Inc. owns the copyright in this file and it is provided to you for informative, as opposed to normative, use. The file and any files generated from it may be used to generate other informative documentation, such as a unified set of documents of API signatures for a platform that includes technologies expressed as Java APIs. The file may also be used to produce "compilation stubs," which allow applications to be compiled and validated for such platforms.

Any work generated from this file, such as unified javadocs or compiled stub files, must be accompanied by this notice in its entirety.

This work corresponds to the API signatures of JSR 219: Foundation Profile 1.1. In the event of a discrepency between this work and the JSR 219 specification, which is available at http://www.jcp.org/en/jsr/detail?id=219, the latter takes precedence. */ package java.math; /** * Immutable, arbitrary-precision signed decimal numbers. A BigDecimal * consists of an arbitrary precision integer unscaled value and a * non-negative 32-bit integer scale, which represents the number of * digits to the right of the decimal point. The number represented by the * BigDecimal is (unscaledValue/10^scale). BigDecimal * provides operations for basic arithmetic, scale manipulation, comparison, * hashing, and format conversion. *

* The BigDecimal class gives its user complete control over rounding * behavior, forcing the user to explicitly specify a rounding * behavior for operations capable of discarding precision ({@link * #divide(BigDecimal, int)}, {@link #divide(BigDecimal, int, int)}, * and {@link #setScale}). Eight rounding modes are provided * for this purpose. *

* Two types of operations are provided for manipulating the scale of a * BigDecimal: scaling/rounding operations and decimal point motion * operations. Scaling/rounding operations (setScale) return a * BigDecimal whose value is approximately (or exactly) equal to that of the * operand, but whose scale is the specified value; that is, they increase or * decrease the precision of the number with minimal effect on its value. * Decimal point motion operations ({@link #movePointLeft} and * {@link #movePointRight}) return a BigDecimal created from the operand by * moving the decimal point a specified distance in the specified direction; * that is, they change a number's value without affecting its precision. *

* For the sake of brevity and clarity, pseudo-code is used throughout the * descriptions of BigDecimal methods. The pseudo-code expression * (i + j) is shorthand for "a BigDecimal whose value is * that of the BigDecimal i plus that of the BigDecimal j." * The pseudo-code expression (i == j) is shorthand for * "true if and only if the BigDecimal i represents the same * value as the the BigDecimal j." Other pseudo-code expressions are * interpreted similarly. *

* Note: care should be exercised if BigDecimals are to be used as * keys in a {@link java.util.SortedMap} or elements in a {@link * java.util.SortedSet}, as BigDecimal's natural ordering is * inconsistent with equals. See {@link Comparable}, {@link * java.util.SortedMap} or {@link java.util.SortedSet} for more * information. *

* All methods and constructors for this class * throw NullPointerException when passed * a null object reference for any input parameter. * * @see BigInteger * @see java.util.SortedMap * @see java.util.SortedSet * @version 1.33, 08/19/02 * @author Josh Bloch */ public class BigDecimal extends Number implements Comparable { /** * Rounding mode to round away from zero. Always increments the * digit prior to a non-zero discarded fraction. Note that this rounding * mode never decreases the magnitude of the calculated value. */ public static final int ROUND_UP = 0; /** * Rounding mode to round towards zero. Never increments the digit * prior to a discarded fraction (i.e., truncates). Note that this * rounding mode never increases the magnitude of the calculated value. */ public static final int ROUND_DOWN = 1; /** * Rounding mode to round towards positive infinity. If the * BigDecimal is positive, behaves as for ROUND_UP; if negative, * behaves as for ROUND_DOWN. Note that this rounding mode never * decreases the calculated value. */ public static final int ROUND_CEILING = 2; /** * Rounding mode to round towards negative infinity. If the * BigDecimal is positive, behave as for ROUND_DOWN; if negative, * behave as for ROUND_UP. Note that this rounding mode never * increases the calculated value. */ public static final int ROUND_FLOOR = 3; /** * Rounding mode to round towards "nearest neighbor" unless both * neighbors are equidistant, in which case round up. * Behaves as for ROUND_UP if the discarded fraction is >= .5; * otherwise, behaves as for ROUND_DOWN. Note that this is the * rounding mode that most of us were taught in grade school. */ public static final int ROUND_HALF_UP = 4; /** * Rounding mode to round towards "nearest neighbor" unless both * neighbors are equidistant, in which case round down. * Behaves as for ROUND_UP if the discarded fraction is > .5; * otherwise, behaves as for ROUND_DOWN. */ public static final int ROUND_HALF_DOWN = 5; /** * Rounding mode to round towards the "nearest neighbor" unless both * neighbors are equidistant, in which case, round towards the even * neighbor. Behaves as for ROUND_HALF_UP if the digit to the left of the * discarded fraction is odd; behaves as for ROUND_HALF_DOWN if it's even. * Note that this is the rounding mode that minimizes cumulative error * when applied repeatedly over a sequence of calculations. */ public static final int ROUND_HALF_EVEN = 6; /** * Rounding mode to assert that the requested operation has an exact * result, hence no rounding is necessary. If this rounding mode is * specified on an operation that yields an inexact result, an * ArithmeticException is thrown. */ public static final int ROUND_UNNECESSARY = 7; /** * The unscaled value of this BigDecimal, as returned by unscaledValue(). * * @serial * @see #unscaledValue */ private BigInteger intVal; /** * The scale of this BigDecimal, as returned by scale(). * * @serial * @see #scale */ private int scale; private static final long serialVersionUID = 6108874887143696463L; /** * Translates the String representation of a BigDecimal into a * BigDecimal. The String representation consists of an optional * sign, '+' ('\u002B') or '-' * ('\u002D'), followed by a sequence of zero or more * decimal digits ("the integer"), optionally followed by a * fraction, optionally followed by an exponent. * *

The fraction consists of of a decimal point followed by zero or more * decimal digits. The string must contain at least one digit in either * the integer or the fraction. The number formed by the sign, the * integer and the fraction is referred to as the significand. * *

The exponent consists of the character 'e' * ('\u0075') or 'E' ('\u0045') * followed by one or more decimal digits. The value of the * exponent must lie between -{@link Integer#MAX_VALUE} ({@link * Integer#MIN_VALUE}+1) and {@link Integer#MAX_VALUE}, inclusive. * *

More formally, the strings this constructor accepts are * described by the following grammar: *

*

*

BigDecimalString: *

Sign_opt Significand Exponent_opt *

*

Sign: *

+ *

- *

*

Significand: *

IntegerPart . FractionPart_opt *

. FractionPart *

IntegerPart *

*

IntegerPart: *

Digits *

*

FractionPart: *

Digits *

*

Exponent: *

ExponentIndicator SignedInteger *

*

ExponentIndicator: *

e *

E *

*

SignedInteger: *

Sign_opt Digits *

*

Digits: *

Digit *

Digits Digit *

*

Digit: *

any character for which {@link Character#isDigit} * returns true, including 0, 1, 2 ... *

*

The scale of the returned BigDecimal will be the number of digits in * the fraction, or zero if the string contains no decimal point, subject * to adjustment for any exponent: If the string contains an exponent, the * exponent is subtracted from the scale. If the resulting scale is * negative, the scale of the returned BigDecimal is zero and the unscaled * value is multiplied by the appropriate power of ten so that, in every * case, the resulting BigDecimal is equal to significand × * 10^exponent. (If in the future this specification is * amended to permit negative scales, the final step of zeroing the scale * and adjusting the unscaled value will be eliminated.) * *

The character-to-digit mapping is provided by {@link * java.lang.Character#digit} set to convert to radix 10. The * String may not contain any extraneous characters (whitespace, * for example). * *

Note: For values other float and double * NaN and ±Infinity, this constructor is compatible with * the values returned by {@link Float#toString} and {@link * Double#toString}. This is generally the preferred way to * convert a float or double into a BigDecimal, * as it doesn't suffer from the unpredictability of the {@link * #BigDecimal(double)} constructor. * *

Note: the optional leading plus sign and trailing exponent were * added in release 1.3. * * @param val String representation of BigDecimal. * @throws NumberFormatException val is not a valid representation * of a BigDecimal. */ public BigDecimal(String val) { } /** * Translates a double into a BigDecimal. The scale * of the BigDecimal is the smallest value such that * (10^scale * val) is an integer. *

* Note: the results of this constructor can be somewhat unpredictable. * One might assume that new BigDecimal(.1) is exactly equal * to .1, but it is actually equal * to .1000000000000000055511151231257827021181583404541015625. * This is so because .1 cannot be represented exactly as a double * (or, for that matter, as a binary fraction of any finite length). * Thus, the long value that is being passed in to the constructor * is not exactly equal to .1, appearances notwithstanding. *

* The (String) constructor, on the other hand, is perfectly predictable: * new BigDecimal(".1") is exactly equal to .1, as one * would expect. Therefore, it is generally recommended that the (String) * constructor be used in preference to this one. * * @param val double value to be converted to BigDecimal. * @throws NumberFormatException val if val is * infinite or NaN. */ public BigDecimal(double val) { } /** * Translates a BigInteger into a BigDecimal. The scale of the BigDecimal * is zero. * * @param val BigInteger value to be converted to BigDecimal. */ public BigDecimal(BigInteger val) { } /** * Translates a BigInteger unscaled value and an int * scale into a BigDecimal. The value of the BigDecimal is * (unscaledVal/10^scale). * * @param unscaledVal unscaled value of the BigDecimal. * @param scale scale of the BigDecimal. * @throws NumberFormatException scale is negative */ public BigDecimal(BigInteger unscaledVal, int scale) { } /** * Translates a long unscaled value and an * int scale into a BigDecimal. This "static factory * method" is provided in preference to a (long, * int) constructor because it allows for reuse of * frequently used BigDecimals. * * @param unscaledVal unscaled value of the BigDecimal. * @param scale scale of the BigDecimal. * @return a BigDecimal whose value is * (unscaledVal/10^scale). */ public static BigDecimal valueOf(long unscaledVal, int scale) { return null; } /** * Translates a long value into a BigDecimal with a * scale of zero. This "static factory method" is provided in * preference to a (long) constructor because it * allows for reuse of frequently used BigDecimals. * * @param val value of the BigDecimal. * @return a BigDecimal whose value is val. */ public static BigDecimal valueOf(long val) { return null; } /** * Returns a BigDecimal whose value is (this + val), and whose * scale is max(this.scale(), val.scale()). * * @param val value to be added to this BigDecimal. * @return this + val */ public BigDecimal add(BigDecimal val) { return null; } /** * Returns a BigDecimal whose value is (this - val), and whose * scale is max(this.scale(), val.scale()). * * @param val value to be subtracted from this BigDecimal. * @return this - val */ public BigDecimal subtract(BigDecimal val) { return null; } /** * Returns a BigDecimal whose value is (this * val), and whose * scale is (this.scale() + val.scale()). * * @param val value to be multiplied by this BigDecimal. * @return this * val */ public BigDecimal multiply(BigDecimal val) { return null; } /** * Returns a BigDecimal whose value is (this / val), and whose * scale is as specified. If rounding must be performed to generate a * result with the specified scale, the specified rounding mode is * applied. * * @param val value by which this BigDecimal is to be divided. * @param scale scale of the BigDecimal quotient to be returned. * @param roundingMode rounding mode to apply. * @return this / val * @throws ArithmeticException val is zero, scale is * negative, or roundingMode==ROUND_UNNECESSARY and * the specified scale is insufficient to represent the result * of the division exactly. * @throws IllegalArgumentException roundingMode does not * represent a valid rounding mode. * @see #ROUND_UP * @see #ROUND_DOWN * @see #ROUND_CEILING * @see #ROUND_FLOOR * @see #ROUND_HALF_UP * @see #ROUND_HALF_DOWN * @see #ROUND_HALF_EVEN * @see #ROUND_UNNECESSARY */ public BigDecimal divide(BigDecimal val, int scale, int roundingMode) { return null; } /** * Returns a BigDecimal whose value is (this / val), and whose * scale is this.scale(). If rounding must be performed to * generate a result with the given scale, the specified rounding mode is * applied. * * @param val value by which this BigDecimal is to be divided. * @param roundingMode rounding mode to apply. * @return this / val * @throws ArithmeticException val==0, or * roundingMode==ROUND_UNNECESSARY and * this.scale() is insufficient to represent the result * of the division exactly. * @throws IllegalArgumentException roundingMode does not * represent a valid rounding mode. * @see #ROUND_UP * @see #ROUND_DOWN * @see #ROUND_CEILING * @see #ROUND_FLOOR * @see #ROUND_HALF_UP * @see #ROUND_HALF_DOWN * @see #ROUND_HALF_EVEN * @see #ROUND_UNNECESSARY */ public BigDecimal divide(BigDecimal val, int roundingMode) { return null; } /** * Returns a BigDecimal whose value is the absolute value of this * BigDecimal, and whose scale is this.scale(). * * @return abs(this) */ public BigDecimal abs() { return null; } /** * Returns a BigDecimal whose value is (-this), and whose scale * is this.scale(). * * @return -this */ public BigDecimal negate() { return null; } /** * Returns the signum function of this BigDecimal. * * @return -1, 0 or 1 as the value of this BigDecimal is negative, zero or * positive. */ public int signum() { return 0; } /** * Returns the scale of this BigDecimal. (The scale is the number * of digits to the right of the decimal point.) * * @return the scale of this BigDecimal. */ public int scale() { return 0; } /** * Returns a BigInteger whose value is the unscaled value of this * BigDecimal. (Computes (this * 10^this.scale()).) * * @return the unscaled value of this BigDecimal. * @since 1.2 */ public BigInteger unscaledValue() { return null; } /** * Returns a BigDecimal whose scale is the specified value, and whose * unscaled value is determined by multiplying or dividing this * BigDecimal's unscaled value by the appropriate power of ten to maintain * its overall value. If the scale is reduced by the operation, the * unscaled value must be divided (rather than multiplied), and the value * may be changed; in this case, the specified rounding mode is applied to * the division. *

* Note that since BigDecimal objects are immutable, calls of this * method do not result in the original object being * modified, contrary to the usual convention of having methods * named setX mutate field * X. Instead, setScale returns * an object with the proper scale; the returned object may or may * not be newly allocated. * * @param scale scale of the BigDecimal value to be returned. * @param roundingMode The rounding mode to apply. * @return a BigDecimal whose scale is the specified value, and whose * unscaled value is determined by multiplying or dividing this * BigDecimal's unscaled value by the appropriate power of ten to * maintain its overall value. * @throws ArithmeticException scale is negative, or * roundingMode==ROUND_UNNECESSARY and the specified * scaling operation would require rounding. * @throws IllegalArgumentException roundingMode does not * represent a valid rounding mode. * @see #ROUND_UP * @see #ROUND_DOWN * @see #ROUND_CEILING * @see #ROUND_FLOOR * @see #ROUND_HALF_UP * @see #ROUND_HALF_DOWN * @see #ROUND_HALF_EVEN * @see #ROUND_UNNECESSARY */ public BigDecimal setScale(int scale, int roundingMode) { return null; } /** * Returns a BigDecimal whose scale is the specified value, and whose * value is numerically equal to this BigDecimal's. Throws an * ArithmeticException if this is not possible. This call is typically * used to increase the scale, in which case it is guaranteed that there * exists a BigDecimal of the specified scale and the correct value. The * call can also be used to reduce the scale if the caller knows that the * BigDecimal has sufficiently many zeros at the end of its fractional * part (i.e., factors of ten in its integer value) to allow for the * rescaling without loss of precision. *

* This method returns the same result as the two argument version * of setScale, but saves the caller the trouble of specifying a * rounding mode in cases where it is irrelevant. *