RationalNumber (JUMP Ultimate Math Package 0.5)

java.lang.Object
- java.lang.Number
- - org.znerd.math.RealNumber
  - - 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:
- 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.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

Constructors
Modifier	Constructor and Description
`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

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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 thisⁿ, 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 thisⁿ, 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.

Class RationalNumber

Field Summary

Fields inherited from class org.znerd.math.RealNumber

Fields inherited from interface org.znerd.math.RoundingModes

Constructor Summary

Method Summary

Methods inherited from class org.znerd.math.RealNumber

Methods inherited from class java.lang.Object

Constructor Detail

RationalNumber

RationalNumber

Method Detail

compareToImpl

compareToImpl2

compareTo

compareToImpl

negate

invert

add

add

subtract

subtract

multiply

multiply

divide

divide

powImpl

pow

powImpl

doubleValue

toBigDecimal

toBigDecimal

trunc

getNumerator

getDenominator