|
Generated by JDiff |
||||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packagejava.math
as colored differences. Deletions are shownlike 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/10scale). BigDecimal provides operations for basic arithmetic scale manipulation comparison hashing and format conversion.Class BigDecimal, constructor BigDecimal(BigInteger, int)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
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 aClass BigDecimal, int compareTo(Object)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 valis equal toifDouble.NEGATIVE_INFINITYvalDouble.POSITIVE_INFINITYis infinite orDouble.NaN.
Compares this BigDecimal with the specified Object. If the Object is a BigDecimal this method behaves likeClass BigDecimal, double doubleValue()#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
Converts this BigDecimal to aClass BigDecimal, boolean equals(Object)double
.Similar to theThis conversion isdouble-similar to-floatthe narrowing primitive conversion fromdouble
tofloat
as defined inThethe Java Language Specification: if this BigDecimal has too great a magnitudetorepresent as adouble
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 adouble
.
Compares this BigDecimal with the specified Object for equality. UnlikeClass BigDecimal, float floatValue()#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)
Converts this BigDecimal to aClass BigDecimal, int intValue()float
.Similar to theThis conversion isdouble-similar to-floatthe narrowing primitive conversion fromdouble
tofloat
defined inThethe Java Language Specification: if this BigDecimal has too great a magnitude to represent as afloat
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 afloat
.
Converts this BigDecimal to anClass BigDecimal, long longValue()int
. This conversion isstandardanalogous to a narrowing primitive conversion fromdouble
toshort
as defined inThethe Java Language Specification: any fractional part of this BigDecimal will be discarded and if the resulting""BigInteger"" is too big to fit in anint
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 anint
.
Converts this BigDecimal to aClass BigDecimal, BigDecimal max(BigDecimal)long
. This conversion isstandardanalogous to a narrowing primitive conversion fromdouble
toshort
as defined inThethe Java Language Specification: any fractional part of this BigDecimal will be discarded and if the resulting""BigInteger"" is too big to fit in along
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 anintlong
.
Returns the maximum of this BigDecimal and val. @param val value withClass BigDecimal, BigDecimal min(BigDecimal)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)
Returns the minimum of this BigDecimal and val. @param val value withClass BigDecimal, BigDecimal setScale(int)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)
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.Class BigDecimal, BigDecimal setScale(int, int)
Note that thisThiscallmethod 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 fieldX
. InsteadsetScale
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)
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.Class BigDecimal, BigInteger toBigInteger()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 fieldX
. InsteadsetScale
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
Converts this BigDecimal to a BigInteger.Class BigDecimal, BigDecimal valueOf(long)StandardThis conversion is analogous to a narrowing primitive conversion fromdouble
tolong
as defined inThethe 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.
Translates aClass BigDecimal, BigDecimal valueOf(long, int)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.
Translates along
unscaled value and anint
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).
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.Class BigInteger, constructor BigInteger(String, int)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
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 CharacterClass BigInteger, constructor BigInteger(int, int, Random).#MIN_RADIX(2)to Character.#MAX_RADIX(36)inclusive. @see Character#digit
Constructs a randomly generated positive BigInteger that is probably prime with the specified bitLength.Class BigInteger, double doubleValue()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
Converts this BigInteger to aClass BigInteger, float floatValue()double
.Similar to theThis conversion isdouble-similar to-floatthe narrowing primitive conversion fromdouble
tofloat
defined inThethe Java Language Specification: if this BigInteger has too great a magnitude to represent as adouble
it will be converted toinfinityDouble#NEGATIVE_INFINITY ornegativeDouble#POSITIVE_INFINITYinfinityas 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 adouble
.
Converts this BigInteger to aClass BigInteger, int intValue()float
.Similar to theThis conversion isdouble-similar to-floatthe narrowing primitive conversion fromdouble
tofloat
defined inThethe Java Language Specification: if this BigInteger has too great a magnitude to represent as afloat
it will be converted toinfinityFloat#NEGATIVE_INFINITY ornegativeFloat#POSITIVE_INFINITYinfinityas 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 afloat
.
Converts this BigInteger to anClass BigInteger, boolean isProbablePrime(int)int
. This conversion isstandardanalogous to a narrowing primitive conversion fromlong
toint
as defined inThethe Java Language Specification: if this BigInteger is too big to fit in anint
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 anint
.
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 aClass BigInteger, byte[] toByteArray()long
. This conversion isstandardanalogous to a narrowing primitive conversion fromlong
toint
as defined inThethe Java Language Specification: if this BigInteger is too big to fit in along
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 along
.
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 CharacterClass BigInteger, BigInteger valueOf(long).#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 (Stringint
)} 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)
Returns a BigInteger whose value is equal to that of the specifiedlong
. 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.