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 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

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:

• getNumerator() -- Returns the numerator of this fraction
• getDenominator() -- Returns the denominator of this fraction

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

• getSign() -- The implementation in this class returns the sign of the numerator, which is this in an IntegerNumber implementation
• negate() -- The implementation in this class returns a fraction with a negated numerator, which is this in an IntegerNumber implementation
• toString() -- The implementation in this class returns a string representation of the numerator and the string representation of the denominator; in an IntegerNumber implementation the numerator is this

Version:

$Revision: 1.12 $ $Date: 2002/08/16 21:54:40 $

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, 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) 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, 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 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, 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

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.

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.

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 thisⁿ, 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 always be a positive integer number.

Returns:

the denominator, not null.