org.znerd.math
Class RationalNumber

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

public abstract class RationalNumber
extends RealNumber

Rational number. It is a specialisation of RealNumber that offers narrowed numeric computations for rational numbers.

All rational values can be written as a fraction x/y, where both x and y are integer numbers.

RationalNumber derivates must obey these rules:

they should be normalized
the fraction properties should allways return a fraction that cannot be simplified any further, thus 3/9 is illegal, while 1/3 is legal
the denominator should allways be positive
if the fraction is negative, the numerator should be negative and the denominator positive, otherwise both should be positive, thus both -1/-3 and 1/-3 are illegal, while 1/3 and -1/3 are legal

Some RationalNumber numeric computations are narrowed compared to their more general RealNumber equivalents. For instance, adding two rational numbers will result in a rational number. The computations concerned are:

add(RationalNumber)
adding two rational numbers will result in another rational number
subtract(RationalNumber)
subtracting one rational number from another will result in a rational number
multiply(RationalNumber)
multiplying two rational numbers will result in another rational number
divide(RationalNumber)
dividing one rational number by another will result in a rational number
pow(IntegerNumber)
raising a rational number to an integer power will result in a rational number

Concrete subclasses should at least provide an implementations for the following methods:

IntegerNumber implementations based on this class must override the following methods:

Version:
$Revision: 1.7 $ $Date: 2002/06/24 21:41:44 $
Author:
Ernst de Haan (znerd@FreeBSD.org)
See Also:
Serialized Form

Fields inherited from class org.znerd.math.RealNumber
MAXIMUM_RADIX
 
Constructor Summary
protected RationalNumber(IntegerNumber[] parts)
          Constructs a new RationalNumber with the specified numerator and denominator.
protected RationalNumber(IntegerNumber[] parts, String asString)
          Constructs a new RationalNumber with the specified numerator, denominator and textual presentation.
 
Method Summary
 RationalNumber add(RationalNumber n)
          Computes this+n, where n is a rational number.
 RealNumber add(RealNumber n)
          Computes this + n, where n is a real number.
protected  int compareTo(RationalNumber n)
          Compares this number with the specified rational number.
protected  int compareToImpl(RationalNumber n)
           
protected  int compareToImpl(RealNumber n)
          Compares this number with the specified number, second level.
protected  int compareToImpl2(RealNumber n)
          Compares this number with the specified number, third level.
 RationalNumber divide(RationalNumber n)
          Computes this/n, where n is a rational number.
 RealNumber divide(RealNumber n)
          Computes this/n, where n is a real number.
 double doubleValue()
          Returns the value of this number as a double.
 IntegerNumber getDenominator()
          Returns the denominator of this fraction.
 IntegerNumber getNumerator()
          Returns the numerator of this fraction.
 RealNumber invert()
          Computes 1/this.
 RationalNumber multiply(RationalNumber n)
          Computes this*n, where n is a rational number.
 RealNumber multiply(RealNumber n)
          Computes this * n, where n is a real number.
 RealNumber negate()
          Computes -this.
 RationalNumber pow(IntegerNumber n)
          Computes this**n, where n is an integer number.
 RealNumber pow(RealNumber n)
          Computes thisn, where n is a real number.
 RationalNumber subtract(RationalNumber n)
          Computes this-n, where n is a rational number.
 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.
 BigDecimal toBigDecimal(int precision, int roundingMode)
          Converts the value of this number to a BigDecimal with the specified precision and rounding mode.
 IntegerNumber trunc()
          Rounds to an integer number towards 0.
 
Methods inherited from class org.znerd.math.RealNumber
abs, byteValue, compareTo, compareTo, equals, fitsByte, fitsDouble, fitsFloat, fitsInt, fitsLong, fitsShort, floatValue, getSign, intValue, longValue, shortValue, toBigInteger, toString
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RationalNumber

protected RationalNumber(IntegerNumber[] parts)
                  throws IllegalArgumentException
Constructs a new RationalNumber with the specified numerator and denominator.
Parameters:
parts - an array containing the numerator and denonimator, not null, having at least 2 elements and not having a null at index 0 or 1.
Throws:
IllegalArgumentException - if parts == null or parts.length < 2 or parts[0] == null or parts[1] == null.

RationalNumber

protected RationalNumber(IntegerNumber[] parts,
                         String asString)
                  throws IllegalArgumentException
Constructs a new RationalNumber with the specified numerator, denominator and textual presentation.
Parameters:
parts - an array containing the numerator and denonimator, not null, having at least 2 elements and not having a null at index 0 or 1.
asString - textual presentation of the number, not null.
Throws:
IllegalArgumentException - if parts == null or parts.length < 2 or parts[0] == null or parts[1] == null.
Method Detail

compareToImpl

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

The implementation of this method in class RationalNumber first checks if n instanceof RationalNumber. If so, then it calls compareTo(RationalNumber). Otherwise, it calls compareToImpl2(RealNumber).

Overrides:
compareToImpl in class 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.

compareToImpl2

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

The implementation of this method in class RationalNumber just throws a CanNotCompareException.

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.

compareTo

protected final int compareTo(RationalNumber n)
                       throws CanNotCompareException
Compares this number with the specified rational number.

The implementation of this method in class RationalNumber returns the result of subtract(n).getSign().

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.

compareToImpl

protected int compareToImpl(RationalNumber n)
                     throws CanNotCompareException

negate

public RealNumber negate()
Description copied from class: RealNumber
Computes -this.
Overrides:
negate in class RealNumber
Tags copied from class: RealNumber
Returns:
the negative of this, not null.

invert

public RealNumber invert()
Description copied from class: RealNumber
Computes 1/this.
Overrides:
invert in class RealNumber
Tags copied from class: RealNumber
Returns:
the inverse of this, not null.
Throws:
ArithmeticException - if the value of this is zero.

add

public RealNumber add(RealNumber n)
Description copied from class: RealNumber
Computes this + n, where n is a real number.

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

Overrides:
add in class RealNumber
Tags copied from class: 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.

add

public RationalNumber add(RationalNumber n)
                   throws IllegalArgumentException
Computes this+n, where n is a rational number.
Parameters:
n - the number to add to this.
Returns:
the sum of this and n.
Throws:
IllegalArgumentException - if n == null.

subtract

public RealNumber subtract(RealNumber n)
                    throws IllegalArgumentException
Description copied from class: RealNumber
Computes this - n, where n is a real number.

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

Overrides:
subtract in class RealNumber
Tags copied from class: RealNumber
Parameters:
n - the number to subtract from this, not null.
Returns:
this minus n, not null.
Throws:
IllegalArgumentException - if n == null.

subtract

public RationalNumber subtract(RationalNumber n)
                        throws IllegalArgumentException
Computes this-n, where n is a rational number.
Parameters:
n - the number to subtract from this.
Returns:
this minus n.
Throws:
IllegalArgumentException - if n == null.

multiply

public RealNumber multiply(RealNumber n)
Description copied from class: RealNumber
Computes this * n, where n is a real number.

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

Overrides:
multiply in class RealNumber
Tags copied from class: 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.

multiply

public RationalNumber multiply(RationalNumber n)
                        throws IllegalArgumentException
Computes this*n, where n is a rational number.
Parameters:
n - the number to multiply this by.
Returns:
the product of this and n.
Throws:
IllegalArgumentException - if n == null.

divide

public RealNumber divide(RealNumber n)
                  throws IllegalArgumentException,
                         ArithmeticException
Description copied from class: RealNumber
Computes this/n, where n is a real number.

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

Overrides:
divide in class RealNumber
Tags copied from class: RealNumber
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.

divide

public RationalNumber divide(RationalNumber n)
                      throws IllegalArgumentException,
                             ArithmeticException
Computes this/n, where n is a rational number.
Parameters:
n - the number to divide this by.
Returns:
this divided by n.
Throws:
IllegalArgumentException - if n == null.
ArithmeticException - if the value of n is zero.

pow

public RationalNumber pow(IntegerNumber n)
                   throws IllegalArgumentException
Computes this**n, where n is an integer number.
Parameters:
n - the exponent.
Returns:
this raised to the power of n.
Throws:
IllegalArgumentException - if n == null.

pow

public RealNumber pow(RealNumber n)
               throws IllegalArgumentException
Description copied from class: RealNumber
Computes thisn, where n is a real number.

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

Overrides:
pow in class RealNumber
Tags copied from class: RealNumber
Parameters:
n - the exponent, not null.
Returns:
this raised to the power of n.
Throws:
IllegalArgumentException - if n == null.

doubleValue

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

toBigDecimal

public BigDecimal toBigDecimal(int precision)
                        throws IllegalArgumentException
Description copied from class: RealNumber
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.
Overrides:
toBigDecimal in class RealNumber
Tags copied from class: RealNumber
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 BigDecimal toBigDecimal(int precision,
                               int roundingMode)
                        throws IllegalArgumentException
Converts the value of this number to a BigDecimal with the specified precision and rounding mode.

The implementation of this method in class RationalNumber first converts both the numerator and the denominator to BigDecimal objects using IntegerNumber.toBigDecimal(). It then calls BigDecimal.divide(BigDecimal,int,int) and returns the result of that call.

Overrides:
toBigDecimal in class RealNumber
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 precision < 0.

trunc

public IntegerNumber trunc()
Description copied from class: RealNumber
Rounds to an integer number towards 0.
Overrides:
trunc in class RealNumber
Tags copied from class: RealNumber
Returns:
this real number truncated to an integer, never null.

getNumerator

public final IntegerNumber getNumerator()
Returns the numerator of this fraction. This numerator may be negative.
Returns:
the numerator, not null.

getDenominator

public final IntegerNumber getDenominator()
Returns the denominator of this fraction. The denominator will allways be a positive integer number.
Returns:
the denominator, not null.


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