java.math Documentation Differences

This file contains all the changes in documentation in the package java.math as colored differences. Deletions are shown like this, and additions are shown like this.

If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.

Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.

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 (divide and 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 (movePointLeft and 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 SortedMap or elements in a SortedSet as BigDecimal's natural ordering is inconsistent with equals. See Comparable SortedMap or SortedSet for more information. @see BigInteger @see java.util.SortedMap @see java.util.SortedSet @version 1.20 0029 02/1102/2300 @author Josh Bloch

Translates the String representation of a BigDecmal into a BigDecimal. The String representation consists of an optional minus sign ('+' or '-') 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 fractional partthe fraction. The scalenumber offormed by the resulting BigDecimal will besign the integer and the numberfraction of digitsis referred to as the rightsignificand.

The exponent consists of the character 'e'(0x75) or E (0x45) followed by one or more decimal pointdigits. The value of the exponenet must lie between Integer.MIN_VALUE and Integer.MAX_VALUE inclusive.

The scale of the returned BigDecimal will be the number of digits in the stringfraction or 0zero 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 Characterjava.digitlang.Character#digit The String may not contain any extraneous characters (whitespace for example).

Note: For floats (and doubles) other that NAN +INFINITY and -INFINITY this constructor is compatible with the values returned by Float.toString (and 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 #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. @see Character#digit

Compares this BigDecimal with the specified Object. If the Object is a BigDecimal this method behaves like compareTo(BigDecimal). Otherwise it throws a ClassCastException (as BigDecimals are comparable only to other BigDecimals). @param o Object to which this BigDecimal is to be compared. @return a negative number zero or a positive number as this BigDecimal is numerically less than equal to or greater than o which must be a BigDecimal. @throws ClassCastException o is not a BigDecimal. @see #compareTo(java.math.BigDecimal) @see Comparable @since JDK11.2

Compares this BigDecimal with the specified Object for equality. Unlike compareTo this method considers two BigDecimals equal only if they are equal in value and scale (thus 2.0 is not equal to 2.00 when compared by this method). @param ox Object to which this BigDecimal is to be compared. @return true if and only if the specified Object is a BigDecimal whose value and scale are equal to this BigDecimal's. @see #compareTo(java.math.BigDecimal)

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. @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

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 JDK11.2

Immutable arbitrary-precision integers. All operations behave as if BigIntegers were represented in two's-complement notation (like Java's primitive integer types). BigInteger provides analogues to all of Java's primitive integer operators and all relevant methods from java.lang.Math. Additionally BigInteger provides operations for modular arithmetic GCD calculation primality testing prime generation bit manipulation and a few other miscellaneous operations.

Semantics of arithmetic operations exactly mimic those of Java's integer arithmetic operators as defined in The Java Language Specification. For example division by zero throws an ArithmeticException and division of a negative by a positive yields a negative (or zero) remainder. All of the details in the Spec concerning overflow are ignored as BigIntegers are made as large as necessary to accommodate the results of an operation.

Semantics of shift operations extend those of Java's shift operators to allow for negative shift distances. A right-shift with a negative shift distance results in a left shift and vice-versa. The unsigned right shift operator (>>>) is omitted as this operation makes little sense in combination with the "infinite word size" abstraction provided by this class.

Semantics of bitwise logical operations exactly mimic those of Java's bitwise integer operators. The binary operators (and or xor) implicitly perform sign extension on the shorter of the two operands prior to performing the operation.

Comparison operations perform signed integer comparisons analogous to those performed by Java's relational and equality operators.

Modular arithmetic operations are provided to compute residues perform exponentiation and compute multiplicative inverses. These methods always return a non-negative result between 0 and (modulus - 1) inclusive.

Bit operations operate on a single bit of the two's-complement representation of their operand. If necessary the operand is sign- extended so that it contains the designated bit. None of the single-bit operations can produce a BigInteger with a different sign from the BigInteger being operated on as they affect only a single bit and the "infinite word size" abstraction provided by this class ensures that there are infinitely many "virtual sign bits" preceding each BigInteger.

For the sake of brevity and clarity pseudo-code is used throughout the descriptions of BigInteger methods. The pseudo-code expression (i + j) is shorthand for "a BigInteger whose value is that of the BigInteger i plus that of the BigInteger j." The pseudo-code expression (i == j) is shorthand for "true if and only if the BigInteger i represents the same value as the the BigInteger j." Other pseudo-code expressions are interpreted similarly. @see BigDecimal @version 1.26 0036 04/1121/2300 @author Josh Bloch @author Michael McCloskey @since JDK1.1

Compares this BigInteger with the specified Object. If the Object is a BigInteger this method behaves like compareTo(BigInteger). Otherwise it throws a ClassCastException (as BigIntegers are comparable only to other BigIntegers). @param o Object to which this BigInteger is to be compared. @return a negative number zero or a positive number as this BigInteger is numerically less than equal to or greater than o which must be a BigInteger. @throws ClassCastException o is not a BigInteger. @see #compareTo(java.math.BigInteger) @see Comparable @since JDK11.2

Compares this BigInteger with the specified Object for equality. @param ox Object to which this BigInteger is to be compared. @return true if and only if the specified Object is a BigInteger whose value is numerically equal to this BigInteger.

Returns a BigInteger whose value is (this^exponent). Returns one if this BigInteger and exponent are both zero. Note that exponent is an integer rather than a BigInteger. @param exponent exponent to which this BigInteger is to be raised. @return this^exponent @throws ArithmeticException exponent is negative. (This would cause the operation to yield a non-integer value.)

The BigInteger constant one. @since JDK11.2

The BigInteger constant zero. @since JDK11.2