Generated by
JDiff

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.

Class BigDecimal

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/10scale). 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)} in int)} and Eigh 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 retur 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 java.util.SortedMap or elements in a java.util.SortedSet as BigDecimal's natural ordering is inconsistent with equals. See Comparable java.util.SortedMap or 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.36 0940 06/2111/0102 @author Josh Bloch

Class BigDecimal, constructor BigDecimal(BigInteger, int)

Translates a BigInteger unscaled value and an int scale into a BigDecimal. The value of the BigDecimal is (unscaledVal/10scale). @param unscaledVal unscaled value of the BigDecimal. @param scale scale of the BigDecimal. @throws NumberFormatException scale is negative
Class BigDecimal, constructor BigDecimal(double)

Translates a double into a BigDecimal. The scale of the BigDecimal is the smallest value such that (10scale * 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 nonwithstandingnotwithstanding.

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 is equal toif Double.NEGATIVE_INFINITYval Double.POSITIVE_INFINITYis infinite or Double.NaN.

Class BigDecimal, int compareTo(Object)

Compares this BigDecimal with the specified Object. If the Object is a BigDecimal this method behaves like #compareTo 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 1.2
Class BigDecimal, double doubleValue()

Converts this BigDecimal to a double. Similar to theThis conversion is double-similar to-float the narrowing primitive conversion from double to float as defined in Thethe Java Language Specification: if this BigDecimal has too great a magnitude to represent as a double it will be converted to Double.#NEGATIVE_INFINITY or Double.#POSITIVE_INFINITY as appropriate. Note that even when the return value is finite this conversion can lose information about the precision of the BigDecimal value. @return this BigDecimal converted to a double.
Class BigDecimal, boolean equals(Object)

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 x 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)
Class BigDecimal, float floatValue()

Converts this BigDecimal to a float. Similar to theThis conversion is double-similar to-float the narrowing primitive conversion from double to float defined in Thethe Java Language Specification: if this BigDecimal has too great a magnitude to represent as a float it will be converted to Float.#NEGATIVE_INFINITY or Float.#POSITIVE_INFINITY as appropriate. Note that even when the return value is finite this conversion can lose information about the precision of the BigDecimal value. @return this BigDecimal converted to a float.
Class BigDecimal, int intValue()

Converts this BigDecimal to an int. This conversion is standardanalogous to a narrowing primitive conversion from double to short as defined in Thethe Java Language Specification: any fractional part of this BigDecimal will be discarded and if the resulting ""BigInteger"" is too big to fit in an int only the low-order 32 bits are returned. Note that this conversion can lose information about the overall magnitude and precision of the BigDecimal value as well as return a result with the opposite sign. @return this BigDecimal converted to an int.
Class BigDecimal, long longValue()

Converts this BigDecimal to a long. This conversion is standardanalogous to a narrowing primitive conversion from double to short as defined in Thethe Java Language Specification: any fractional part of this BigDecimal will be discarded and if the resulting ""BigInteger"" is too big to fit in a long only the low-order 64 bits are returned. Note that this conversion can lose information about the overall magnitude and precision of the BigDecimal value as well as return a result with the opposite sign. @return this BigDecimal converted to an intlong.
Class BigDecimal, BigDecimal max(BigDecimal)

Returns the maximum of this BigDecimal and val. @param val value with withwhich the maximum is to be computed. @return the BigDecimal whose value is the greater of this BigDecimal and val. If they are equal as defined by the #compareTo method either may be returned. @see #compareTo(java.math.BigDecimal)
Class BigDecimal, BigDecimal min(BigDecimal)

Returns the minimum of this BigDecimal and val. @param val value with withwhich the minimum is to be computed. @return the BigDecimal whose value is the lesser of this BigDecimal and val. If they are equal as defined by the #compareTo method either may be returned. @see #compareTo(java.math.BigDecimal)
Class BigDecimal, BigDecimal setScale(int)

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.

Note that thisThis callmethod 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.

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. @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 the specified scaling operation would require rounding. @see #setScale(int int)

Class BigDecimal, BigDecimal setScale(int, int)

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

Class BigDecimal, BigInteger toBigInteger()

Converts this BigDecimal to a BigInteger. StandardThis conversion is analogous to a narrowing primitive conversion from double to long as defined in Thethe Java Language Specification: any fractional part of this BigDecimal will be discarded. Note that this conversion can lose information about the precision of the BigDecimal value. @return this BigDecimal converted to a BigInteger.
Class BigDecimal, BigDecimal valueOf(long)

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.
Class BigDecimal, BigDecimal valueOf(long, int)

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/10scale).

Class BigInteger

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.

All methods and constructors in this class throw NullPointerException when passed a null object reference for any input parameter. @see BigDecimal @version 1.49 0953 06/1211/0102 @author Josh Bloch @author Michael McCloskey @since JDK1.1

Class BigInteger, constructor BigInteger(String, int)

Translates the String representation of a BigInteger in the specified radix into a BigInteger. The String representation consists of an optional minus sign followed by a sequence of one or more digits in the specified radix. The character-to-digit mapping is provided by Character.digit. The String may not contain any extraneous characters (whitespace for example). @param val String representation of BigInteger. @param radix radix to be used in interpreting val. @throws NumberFormatException val is not a valid representation of a BigInteger in the specified radix or radix is outside the range from Character.#MIN_RADIX (2) to Character.#MAX_RADIX (36) inclusive. @see Character#digit
Class BigInteger, constructor BigInteger(int, int, Random)

Constructs a randomly generated positive BigInteger that is probably prime with the specified bitLength.

It is recommended that the probablePrime method be used in preference to this constructor unless there is a compelling need to specify a certainty. @param bitLength bitLength of the returned BigInteger. @param certainty a measure of the uncertainty that the caller is willing to tolerate. The probability that the new BigInteger represents a prime number will exceed (1 - 1/2certainty). The execution time of this constructor is proportional to the value of this parameter. @param rnd source of random bits used to select candidates to be tested for primality. @throws ArithmeticException bitLength < 2. @see #bitLength

Class BigInteger, double doubleValue()

Converts this BigInteger to a double. Similar to theThis conversion is double-similar to-float the narrowing primitive conversion from double to float defined in Thethe Java Language Specification: if this BigInteger has too great a magnitude to represent as a double it will be converted to infinityDouble#NEGATIVE_INFINITY or negativeDouble#POSITIVE_INFINITY infinity as appropriate. Note that even when the return value is finite this conversion can lose information about the precision of the BigInteger value. @return this BigInteger converted to a double.
Class BigInteger, float floatValue()

Converts this BigInteger to a float. Similar to theThis conversion is double-similar to-float the narrowing primitive conversion from double to float defined in Thethe Java Language Specification: if this BigInteger has too great a magnitude to represent as a float it will be converted to infinityFloat#NEGATIVE_INFINITY or negativeFloat#POSITIVE_INFINITY infinity as appropriate. Note that even when the return value is finite this conversion can lose information about the precision of the BigInteger value. @return this BigInteger converted to a float.
Class BigInteger, int intValue()

Converts this BigInteger to an int. This conversion is standardanalogous to a narrowing primitive conversion from long to int as defined in Thethe Java Language Specification: if this BigInteger is too big to fit in an int only the low-order 32 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigInteger value as well as return a result with the opposite sign. @return this BigInteger converted to an int.
Class BigInteger, boolean isProbablePrime(int)

Returns true if this BigInteger is probably prime false if it's definitely composite. If certainty is <= 0 true is returned. @param certainty a measure of the uncertainty that the caller is willing to tolerate: if the call returns true the probability that this BigInteger is prime exceeds (1 - 1/2certainty). The execution time of this method is proportional to the value of this parameter. @return true if this BigInteger is probably prime false if it's definitely composite.
Class BigInteger, long longValue()

Converts this BigInteger to a long. This conversion is standardanalogous to a narrowing primitive conversion from long to int as defined in Thethe Java Language Specification: if this BigInteger is too big to fit in a long only the low-order 64 bits are returned. Note that this conversion can lose information about the overall magnitude of the BigInteger value as well as return a result with the opposite sign. @return this BigInteger converted to a long.
Class BigInteger, byte[] toByteArray()

Returns a byte array containing the two's-complement representation of this BigInteger. The byte array will be in big-endian byte-order: the most significant byte is in the zeroth element. The array will contain the minimum number of bytes required to represent this BigInteger including at least one sign bit which is (ceil((this.bitLength() + 1)/8)). (This representation is compatible with the (byte[]) constructor.) @return a byte array containing the two's-complement representation of this BigInteger. @see #BigInteger(byte[])
Class BigInteger, String toString()

Returns the decimal String representation of this BigInteger. The digit-to-character mapping provided by Character.forDigit is used and a minus sign is prepended if appropriate. (This representation is compatible with the (String) constructor and allows for String concatenation with Java's + operator.) @return decimal String representation of this BigInteger. @see Character#forDigit @see #BigInteger(java.lang.String)
Class BigInteger, String toString(int)

Returns the String representation of this BigInteger in the given radix. If the radix is outside the range from Character.#MIN_RADIX (2) to Character.#MAX_RADIX (36) inclusive it will default to 10 (as is the case for Integer.toString). The digit-to-character mapping provided by Character.forDigit is used and a minus sign is prepended if appropriate. (This representation is compatible with the int (String int)} constructor.) @param radix radix of the String representation. @return String representation of this BigInteger in the given radix. @see Integer#toString @see Character#forDigit @see #BigInteger(java.lang.String int)
Class BigInteger, BigInteger valueOf(long)

Returns a BigInteger whose value is equal to that of the specified long. This "static factory method" is provided in preference to a (long) constructor because it allows for reuse of frequently used BigIntegers. @param val value of the BigInteger to return. @return a BigInteger with the specified value.