com.dautelle.math.numbers
Class Rational

java.lang.Object
  java.lang.Number
      com.dautelle.math.numbers.RealtimeNumber
          com.dautelle.math.numbers.Rational

All Implemented Interfaces:

java.lang.Comparable, Operable, Realtime, Representable, java.io.Serializable

public final class Rational

extends RealtimeNumber

implements java.lang.Comparable

This class represents the ratio of two LargeInteger numbers.

Instances of this class are immutable and can be used to find exact solutions to linear equations with the Matrix class.

Version:

6.0, February 1, 2004

Author:

Jean-Marie Dautelle

See Also:

Serialized Form

Nested Class Summary

static class

Rational.Value This inner class represents a mutable image of an immutable Rational.

Nested classes inherited from class com.dautelle.math.numbers.RealtimeNumber

RealtimeNumber.Factory

Field Summary

static Rational	ONE The Rational representing the multiplicative identity.
static Rational	ZERO The Rational representing the additive identity.

Method Summary

Rational	abs() Returns the absolute value of this Rational.
Rational	add(Rational that) Returns the sum of this Rational with the one specified.
java.lang.StringBuffer	appendTo(java.lang.StringBuffer sb, int radix) Appends the text representation of this Rational to the StringBuffer argument in the specified radix.
int	compareTo(java.lang.Object that) Compares two Rational numerically.
Rational	divide(Rational that) Returns this Rational divided by the one specified.
double	doubleValue() Returns the value of this Rational as a double.
boolean	equals(java.lang.Object that) Compares this Rational against the specified object.
java.lang.Object	export() Exports this object out of the current pool context.
float	floatValue() Returns the value of this Rational as a float.
LargeInteger	getDividend() Returns the smallest dividend of the fraction representing this Rational.
LargeInteger	getDivisor() Returns the smallest divisor of the fraction representing this Rational (always positive).
int	hashCode() Returns the hash code for this Rational number.
int	intValue() Returns the value of this Rational as an int.
long	longValue() Returns the value of this Rational as a long.
Rational	multiply(Rational that) Returns the product of this Rational with the one specified.
Rational	negate() Returns the negation of this Rational.
Operable	opposite() Returns the additive inverse of this object.
Operable	plus(Operable that) Returns the sum of this object with the one specified.
Operable	reciprocal() Returns the multiplicative inverse of this object.
LargeInteger	round() Returns the closest Integer to this Rational.
Rational	subtract(Rational that) Returns the difference between this Rational and the one specified.
Operable	times(Operable that) Returns the product of this object with the one specified.
java.lang.Object	toHeap() Moves this object to the heap.
java.lang.String	toString() Returns the decimal text representation of this Rational.
java.lang.String	toString(int radix) Returns the text representation of this Rational in the specified radix.
void	toXml(XmlElement xml) Sets the attributes and content of the XML element corresponding to this object.
static Rational	valueOf(java.lang.CharSequence chars) Returns the Rational for the specified character sequence.
static Rational	valueOf(LargeInteger dividend, LargeInteger divisor) Returns the Rational from the specified dividend and divisor.
static Rational	valueOf(XmlElement xml) XML factory method.

Methods inherited from class com.dautelle.math.numbers.RealtimeNumber

clone, isLocalObject, isPoolObject, pow, recycle

Methods inherited from class java.lang.Number

byteValue, shortValue

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

ZERO

public static final Rational ZERO

The Rational representing the additive identity.

ONE

public static final Rational ONE

The Rational representing the multiplicative identity.

Method Detail

valueOf

public static Rational valueOf(LargeInteger dividend,
                               LargeInteger divisor)

Returns the Rational from the specified dividend and divisor.

Parameters:

dividend - the dividend value.

divisor - the divisor value.

Returns:

dividend / divisor

Throws:

java.lang.ArithmeticException - if divisor.isZero()

valueOf

public static Rational valueOf(java.lang.CharSequence chars)

Returns the Rational for the specified character sequence.

Parameters:

chars - the character sequence.

Returns:

the corresponding Rational number.

valueOf

public static Rational valueOf(XmlElement xml)

XML factory method.

Parameters:

xml - the XML element describing the rational to return (e.g. <math:Rational value="2/3"/>).

Returns:

a new rational number as described by the specified xml element.

See Also:

valueOf(CharSequence)

getDividend

public LargeInteger getDividend()

Returns the smallest dividend of the fraction representing this Rational.

Returns:

this rational's dividend.

getDivisor

public LargeInteger getDivisor()

Returns the smallest divisor of the fraction representing this Rational (always positive).

Returns:

this rational's divisor.

round

public LargeInteger round()

Returns the closest Integer to this Rational.

Returns:

this rational rounded to the nearest integer.

negate

public Rational negate()

Returns the negation of this Rational.

Returns:

-this.

add

public Rational add(Rational that)

Returns the sum of this Rational with the one specified.

Parameters:

that - the Rational to be added.

Returns:

this + that.

subtract

public Rational subtract(Rational that)

Returns the difference between this Rational and the one specified.

Parameters:

that - the Rational to be subtracted.

Returns:

this - that.

multiply

public Rational multiply(Rational that)

Returns the product of this Rational with the one specified.

Parameters:

that - the Rational multiplier.

Returns:

this * that.

divide

public Rational divide(Rational that)

Returns this Rational divided by the one specified.

Parameters:

that - the Rational divisor.

Returns:

this / that.

Throws:

java.lang.ArithmeticException - if that.equals(ZERO)

abs

public Rational abs()

Returns the absolute value of this Rational.

Returns:

abs(this).

appendTo

public java.lang.StringBuffer appendTo(java.lang.StringBuffer sb,
                                       int radix)

Appends the text representation of this Rational to the StringBuffer argument in the specified radix.

Parameters:

sb - the StringBuffer to append.

radix - the radix of the representation.

Returns:

the specified StringBuffer.

toString

public java.lang.String toString()

Returns the decimal text representation of this Rational.

Returns:

the text representation of this Rational number.

toString

public java.lang.String toString(int radix)

Returns the text representation of this Rational in the specified radix.

Parameters:

radix - the radix of the representation.

Returns:

the text representation of this rational number.

equals

public boolean equals(java.lang.Object that)

Compares this Rational against the specified object.

Parameters:

that - the object to compare with.

Returns:

true if the objects are the same; false otherwise.

hashCode

public int hashCode()

Returns the hash code for this Rational number.

Returns:

the hash code value.

intValue

public int intValue()

Returns the value of this Rational as an int.

Returns:

the numeric value represented by this rational after conversion to type int.

longValue

public long longValue()

Returns the value of this Rational as a long.

Returns:

the numeric value represented by this rational after conversion to type long.

floatValue

public float floatValue()

Returns the value of this Rational as a float.

Returns:

the numeric value represented by this rational after conversion to type float.

doubleValue

public double doubleValue()

Returns the value of this Rational as a double.

Returns:

the numeric value represented by this rational after conversion to type double.

compareTo

public int compareTo(java.lang.Object that)

Compares two Rational numerically.

Specified by:

compareTo in interface java.lang.Comparable

Parameters:

that - the Rational to compare with.

Returns:

-1, 0 or 1 as this Rational is numerically less than, equal to, or greater than that.

Throws:

java.lang.ClassCastException - that is not an Rational.

plus

public Operable plus(Operable that)

Description copied from interface: Operable

Returns the sum of this object with the one specified.

Specified by:

plus in interface Operable

Parameters:

that - the object to be added.

Returns:

this + that.

opposite

public Operable opposite()

Description copied from interface: Operable

Returns the additive inverse of this object. It is the object such as this.plus(this.opposite()) == ZERO, with ZERO being the additive identity.

Specified by:

opposite in interface Operable

Returns:

-this.

times

public Operable times(Operable that)

Description copied from interface: Operable

Returns the product of this object with the one specified.

Specified by:

times in interface Operable

Parameters:

that - the object multiplier.

Returns:

this * that.

reciprocal

public Operable reciprocal()

Description copied from interface: Operable

Returns the multiplicative inverse of this object. It it the object such as this.times(this.reciprocal()) == ONE , with ONE being the multiplicative identity.

Specified by:

reciprocal in interface Operable

Returns:

ONE / this.

toXml

public void toXml(XmlElement xml)

Description copied from interface: Representable

Sets the attributes and content of the XML element corresponding to this object.

Specified by:

toXml in interface Representable

Parameters:

xml - the XML element to set according to this object's desired XML representation.

export

public java.lang.Object export()

Description copied from interface: Realtime

Exports this object out of the current pool context. Realtime members are exported as well (recursion). This method affects only objects belonging to the current pool context. To avoid pool depletion, a "free" object from the outer pool is moved to replace the object being exported.

Specified by:

export in interface Realtime

Overrides:

export in class RealtimeNumber

toHeap

public java.lang.Object toHeap()

Description copied from interface: Realtime

Moves this object to the heap. Realtime members are moved to the heap as well (recursion). This method affects only objects belonging to a pool context (current or not).

Specified by:

toHeap in interface Realtime

Overrides:

toHeap in class RealtimeNumber