org.znerd.math
Class RationalNumber

java.lang.Object
  extended by java.lang.Number
      extended by org.znerd.math.RealNumber
          extended by org.znerd.math.RationalNumber
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable, RoundingModes
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 always return a fraction that cannot be simplified any further, thus 3/9 is illegal, while 1/3 is legal
the denominator should always 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
powImpl(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.13 $ $Date: 2002/10/01 18:56:55 $
Author:
Ernst de Haan (znerd@FreeBSD.org)
See Also:
Serialized Form

Field Summary
 
Fields inherited from class org.znerd.math.RealNumber
MAXIMUM_RADIX
 
Fields inherited from interface org.znerd.math.RoundingModes
ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_UP
 
Constructor Summary
protected RationalNumber(IntegerNumber[] parts)
          Constructs a new RationalNumber with the specified numerator and denominator.
protected RationalNumber(IntegerNumber[] parts, java.lang.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, first level.
protected  int compareToImpl(RationalNumber n)
          Compares this number with the specified rational number, second level.
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)
           
protected  RationalNumber powImpl(IntegerNumber n)
           
 RealNumber powImpl(RealNumber n)
          Computes thisn, where n is a real number, second level.
 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.
 java.math.BigDecimal toBigDecimal(int precision)
          Converts the value of this number to a BigDecimal with the specified precision.
 java.math.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, pow, round, 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 java.lang.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:
java.lang.IllegalArgumentException - if parts == null or parts.length < 2 or parts[0] == null or parts[1] == null.

RationalNumber

protected RationalNumber(IntegerNumber[] parts,
                         java.lang.String asString)
                  throws java.lang.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:
java.lang.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, first level.

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
Compares this number with the specified rational number, second level.

This method is called from compareTo(RationalNumber). The implementation of this method in class RationalNumber just throws a CanNotCompareException to indicate it does not provide an optimized algorithm for comparing this integer number with the argument integer number. Subclasses are encouraged to override this method.

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.

negate

public RealNumber negate()
Description copied from class: RealNumber
Computes -this.

Overrides:
negate in 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
Returns:
the inverse of this, not null.

add

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

Overrides:
add in class RealNumber
Parameters:
n - the number to add to this, not null.
Returns:
the sum of this and n, not null.

add

public RationalNumber add(RationalNumber n)
                   throws java.lang.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:
java.lang.IllegalArgumentException - if n == null.

subtract

public RealNumber subtract(RealNumber n)
                    throws java.lang.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
Parameters:
n - the number to subtract from this, not null.
Returns:
this minus n, not null.
Throws:
java.lang.IllegalArgumentException - if n == null.

subtract

public RationalNumber subtract(RationalNumber n)
                        throws java.lang.IllegalArgumentException
Computes this-n, where n is a rational number.

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

multiply

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

Overrides:
multiply in class RealNumber
Parameters:
n - the factor, the number to multiply this by, not null.
Returns:
the product of this and n.

multiply

public RationalNumber multiply(RationalNumber n)
                        throws java.lang.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:
java.lang.IllegalArgumentException - if n == null.

divide

public RealNumber divide(RealNumber n)
                  throws java.lang.IllegalArgumentException,
                         java.lang.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
Parameters:
n - the number to divide this by, not null.
Returns:
this divided by n, not null.
Throws:
java.lang.IllegalArgumentException - if n == null.
java.lang.ArithmeticException - if the value of n is zero.

divide

public RationalNumber divide(RationalNumber n)
                      throws java.lang.IllegalArgumentException,
                             java.lang.ArithmeticException
Computes this/n, where n is a rational number.

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

powImpl

public final RealNumber powImpl(RealNumber n)
                         throws java.lang.UnsupportedOperationException
Description copied from class: RealNumber
Computes thisn, where n is a real number, second level.

This method may be implemented by subclasses. The implementation of this method in class RealNumber throws an UnsupportedOperationException.

Overrides:
powImpl in class RealNumber
Parameters:
n - the exponent, guaranteed not to be null if called by RealNumber.pow(RealNumber).
Returns:
this raised to the power of n, never null.
Throws:
java.lang.UnsupportedOperationException - if this operation is not supported by this class.

pow

public final RationalNumber pow(IntegerNumber n)

powImpl

protected RationalNumber powImpl(IntegerNumber n)

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
Returns:
the numeric value represented by this object after conversion to type double.

toBigDecimal

public java.math.BigDecimal toBigDecimal(int precision)
                                  throws java.lang.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
Parameters:
precision - the number of digits behind the decimal point.
Returns:
a BigDecimal with the rounded value of this.
Throws:
java.lang.IllegalArgumentException - if precision < 0.

toBigDecimal

public java.math.BigDecimal toBigDecimal(int precision,
                                         int roundingMode)
                                  throws java.lang.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.

Specified by:
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:
java.lang.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
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 always be a positive integer number.

Returns:
the denominator, not null.


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