org.znerd.math
Class RealNumber

java.lang.Object
  |
  +--java.lang.Number
        |
        +--org.znerd.math.RealNumber
Direct Known Subclasses:
CompositeNumber, RationalNumber

public abstract class RealNumber
extends Number
implements Comparable, RoundingModes

An immutable real number. A number of basic numeric operations are defined, like:

negate()
Computes -this
invert()
Computes 1/this
add(RealNumber)
Computes this + n
subtract(RealNumber)
Computes this - n
multiply(RealNumber)
Computes this * n
divide(RealNumber)
Computes this / n
pow(RealNumber)
Computes thisn

Examples of real numbers are 3, -1.68, the square root of 3, 2/3, pi, 18.22.3 and e.

Real numbers can be cast to native Java numbers with these conversion methods:

longValue()
Converts this number to a long. Use fitsLong() to make sure the conversion will succeed
intValue()
Converts this number to an int. Use fitsInt() to make sure the conversion will succeed
shortValue()
Converts this number to a short. Use fitsShort() to make sure the conversion will succeed
byteValue()
Converts this number to a byte. Use fitsByte() to make sure the conversion will succeed
doubleValue()
Converts this number to a double. Use fitsDouble() to make sure the conversion will succeed
floatValue()
Converts this number to a float. Use fitsFloat() to make sure the conversion will succeed

Use the NumberCentral to obtain RealNumber instances. For instance:

RealNumber n = NumberCentral.valueOf(0.399);

PENDING: The names of the following methods may be changed in the future to reflect the expected change in the syntax of the Java language syntax to include operator overloading based on method names (see the section Operator Overloading in The Evolution of Numerical Computing in Java by James Gosling.)

Concrete subclasses should provide implementations for the following methods:

toBigDecimal(int,int)
Converts the value of this number to a BigDecimal with the specified precision, using the specified rounding mode.
trunc()
Truncates the value of this number to an IntegerNumber.

Version:
$Revision: 1.10 $ $Date: 2002/06/19 20:51:05 $
Author:
Ernst de Haan (znerd@FreeBSD.org)
See Also:
NumberCentral, Serialized Form

Field Summary
static int MAXIMUM_RADIX
          The maximum value for a radix.
 
Fields inherited from interface org.znerd.math.RoundingModes
ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_UP
 
Constructor Summary
protected RealNumber(int sign, String asString)
          Constructs a new RealNumber object.
 
Method Summary
 RealNumber abs()
          Computes |this|.
 RealNumber add(RealNumber n)
          Computes this + n, where n is a real number.
 byte byteValue()
          Returns the value of this number as a byte.
 int compareTo(Object o)
          Compares this object with the specified object.
 int compareTo(RealNumber n)
          Compares this number with the specified number.
protected  int compareToImpl(RealNumber n)
          Compares this number with the specified number, second level.
 RealNumber divide(RealNumber n)
          Computes this/n, where n is a real number.
 double doubleValue()
          Returns the value of this number as a double.
 boolean equals(Object o)
           
 boolean fitsByte()
          Determines if the truncated value of this number fits in a byte.
 boolean fitsDouble()
          Determines if the rounded value of this number fits in a double.
 boolean fitsFloat()
          Determines if the rounded value of this number fits in a float.
 boolean fitsInt()
          Determines if the truncated value of this number fits in an int.
 boolean fitsLong()
          Determines if the truncated value of this number fits in a long.
 boolean fitsShort()
          Determines if the truncated value of this number fits in a short.
 float floatValue()
          Returns the value of this number as a float.
 int getSign()
          Determines the sign of this number.
 int intValue()
          Returns the value of this number as an int.
 RealNumber invert()
          Computes 1/this.
 long longValue()
          Returns the value of this number as a long.
 RealNumber multiply(RealNumber n)
          Computes this * n, where n is a real number.
 RealNumber negate()
          Computes -this.
 RealNumber pow(RealNumber n)
          Computes thisn, where n is a real number.
 short shortValue()
          Returns the value of this number as a short.
 RealNumber subtract(RealNumber n)
          Computes this - n, where n is a real number.
 BigDecimal toBigDecimal(int precision)
          Converts the value of this number to a BigDecimal with the specified precision.
abstract  BigDecimal toBigDecimal(int precision, int roundingMode)
          Converts the value of this number to a BigDecimal with the specified precision and rounding mode.
 BigInteger toBigInteger()
          Converts the value of this number to a BigInteger.
 String toString()
           
 IntegerNumber trunc()
          Rounds to an integer number towards 0.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

MAXIMUM_RADIX

public static final int MAXIMUM_RADIX
The maximum value for a radix. The value of this field is 255.
Constructor Detail

RealNumber

protected RealNumber(int sign,
                     String asString)
Constructs a new RealNumber object.

The sign of the value needs to be specified. Any negative value is interpreted as meaning that the value of this number is negative. Any positive value is interpreted as meaning that the value of this number is positive.

Parameters:
sign - the sign of this number.
asString - textual presentation of this number, not null.
Throws:
IllegalArgumentException - if asString == null.
Method Detail

toString

public final String toString()
Overrides:
toString in class Object

equals

public final boolean equals(Object o)
Overrides:
equals in class Object

getSign

public final int getSign()
Determines the sign of this number. This method returns -1, 0, or 1 as this number is negative, zero, or positive.
Returns:
the sign of this number, either -1, 0 or 1.

compareTo

public final int compareTo(Object o)
                    throws NullPointerException,
                           ClassCastException
Compares this object with the specified object.

This method calls compareTo(RealNumber).

Specified by:
compareTo in interface Comparable
Parameters:
o - the object to compare to, not null.
Returns:
-1 if this object is considered less than o, 0 if this object is considered equal n, 1 if this object is greater than n.
Throws:
NullPointerException - if n == null.
ClassCastException - if (n instanceof RealNumber) == false.

compareTo

public final int compareTo(RealNumber n)
                    throws NullPointerException
Compares this number with the specified number.

This method attempts to compare this number with the specified number based on the sign. If the signs are equal, compareToImpl(RealNumber) is called. If that method throws a CanNotCompareException, then it is attempted to return the negated result of n.compareToImpl(RealNumber). If that method throws an exception as well, then it is thrown up to the caller of this method.

Parameters:
n - the number to compare to, not null.
Returns:
-1 if this < n, 0 if this == n, 1 if this > n.
Throws:
NullPointerException - if n == null.

compareToImpl

protected int compareToImpl(RealNumber n)
                     throws CanNotCompareException
Compares this number with the specified number, second level.

The implementation of this method in class RealNumber throws a CanNotCompareException. Concrete subclasses are encouraged to improve this behaviour by overriding this method.

Note that this method does not check if n == null. This is already done in compareTo(RealNumber).

Parameters:
n - the number to compare to, guaranteed to be not null.
Returns:
-1 if this < n, 0 if this == n, 1 if this > n.
Throws:
CanNotCompareException - if the comparison failed.

abs

public RealNumber abs()
Computes |this|. The returned value is allways >= 0.
Returns:
the absolute of this, not null and always with a value >= 0.

negate

public RealNumber negate()
Computes -this.
Returns:
the negative of this, not null.

invert

public RealNumber invert()
                  throws ArithmeticException
Computes 1/this.
Returns:
the inverse of this, not null.
Throws:
ArithmeticException - if the value of this is zero.

add

public RealNumber add(RealNumber n)
               throws IllegalArgumentException
Computes this + n, where n is a real number.

The implementation of this method in class RealNumber calls NumberCentral.add(RealNumber,RealNumber).

Parameters:
n - the number to add to this, not null.
Returns:
the sum of this and n, not null.
Throws:
IllegalArgumentException - if n == null.

subtract

public RealNumber subtract(RealNumber n)
                    throws IllegalArgumentException
Computes this - n, where n is a real number.

The implementation of this method in class RealNumber calls add(RealNumber) with n.negate() as the argument.

Parameters:
n - the number to subtract from this, not null.
Returns:
this minus n, not null.
Throws:
IllegalArgumentException - if n == null.

multiply

public RealNumber multiply(RealNumber n)
                    throws IllegalArgumentException
Computes this * n, where n is a real number.

The implementation of this method in class RealNumber calls NumberCentral.multiply(RealNumber,RealNumber).

Parameters:
n - the factor, the number to multiply this by, not null.
Returns:
the product of this and n.
Throws:
IllegalArgumentException - if n == null.

divide

public RealNumber divide(RealNumber n)
                  throws IllegalArgumentException,
                         ArithmeticException
Computes this/n, where n is a real number.

The implementation of this method in class RealNumber calls multiply(RealNumber) with n.invert() as the argument.

Parameters:
n - the number to divide this by, not null.
Returns:
this divided by n, not null.
Throws:
IllegalArgumentException - if n == null.
ArithmeticException - if the value of n is zero.

pow

public RealNumber pow(RealNumber n)
               throws IllegalArgumentException
Computes thisn, where n is a real number.

The implementation of this method in class RealNumber calls NumberCentral.pow(RealNumber,RealNumber).

Parameters:
n - the exponent, not null.
Returns:
this raised to the power of n.
Throws:
IllegalArgumentException - if n == null.

fitsLong

public boolean fitsLong()
Determines if the truncated value of this number fits in a long.
Returns:
true iff this value fits in a long.

fitsInt

public boolean fitsInt()
Determines if the truncated value of this number fits in an int.
Returns:
true iff this value fits in an int.

fitsShort

public boolean fitsShort()
Determines if the truncated value of this number fits in a short.
Returns:
true iff this value fits in a short.

fitsByte

public boolean fitsByte()
Determines if the truncated value of this number fits in a byte.
Returns:
true iff this value fits in a byte.

fitsDouble

public boolean fitsDouble()
Determines if the rounded value of this number fits in a double.
Returns:
true iff this value fits in a double.

fitsFloat

public boolean fitsFloat()
Determines if the rounded value of this number fits in a float.
Returns:
true iff this value fits in a float.

longValue

public long longValue()
Returns the value of this number as a long. This may involve rounding.
Overrides:
longValue in class Number
Returns:
the numeric value represented by this object after conversion to type long.

intValue

public int intValue()
Returns the value of this number as an int. This may involve rounding.
Overrides:
intValue in class Number
Returns:
the numeric value represented by this object after conversion to type int.

shortValue

public short shortValue()
Returns the value of this number as a short. This may involve rounding.
Overrides:
shortValue in class Number
Returns:
the numeric value represented by this object after conversion to type short.

byteValue

public byte byteValue()
Returns the value of this number as a byte. This may involve rounding.
Overrides:
byteValue in class Number
Returns:
the numeric value represented by this object after conversion to type byte.

doubleValue

public double doubleValue()
Returns the value of this number as a double. This may involve rounding.
Overrides:
doubleValue in class Number
Returns:
the numeric value represented by this object after conversion to type double.

floatValue

public float floatValue()
Returns the value of this number as a float. This may involve rounding.
Overrides:
floatValue in class Number
Returns:
the numeric value represented by this object after conversion to type float.

toBigDecimal

public BigDecimal toBigDecimal(int precision)
                        throws IllegalArgumentException
Converts the value of this number to a BigDecimal with the specified precision. This method uses the ROUND_HALF_UP rounding mode as defined in BigDecimal.
Parameters:
precision - the number of digits behind the decimal point.
Returns:
a BigDecimal with the rounded value of this.
Throws:
IllegalArgumentException - if precision < 0.

toBigDecimal

public abstract BigDecimal toBigDecimal(int precision,
                                        int roundingMode)
                                 throws IllegalArgumentException
Converts the value of this number to a BigDecimal with the specified precision and rounding mode.
Parameters:
precision - the number of digits behind the decimal point, >= 0.
roundingMode - the rounding mode to use, one of the modes defined in class BigDecimal.
Returns:
a BigDecimal with the rounded value of this, never null.
Throws:
IllegalArgumentException - if one of the following applies:
  1. precision < 0
  2. roundingMode is not one of the valid rounding modes defined in class BigDecimal

toBigInteger

public BigInteger toBigInteger()
Converts the value of this number to a BigInteger. This may involve rounding.
Returns:
the numeric value represented by this object after conversion to type BigInteger.

trunc

public IntegerNumber trunc()
Rounds to an integer number towards 0.
Returns:
this real number truncated to an integer, never null.


See http://jump-math.sourceforge.net/.