org.josef.science.math

Class CRational

java.lang.Object

org.josef.science.math.CRational

All Implemented Interfaces:

Serializable

@Status(stage=PRODUCTION,
        unitTests=COMPLETE)
 @Review(by="Kees Schotanus",
        at="2009-09-28")
 @ThreadSafety(level=IMMUTABLE)
public class CRational
extends Object
implements Serializable

Abstraction of a Rational number.
A rational number is a number that can be described as the ratio of two integer numbers. For example, a half can be described as 1/2 where 1 is the numerator and 2 is the denominator. The denominator may never be zero since dividing by zero is not allowed.
Note: This class does not protect against overflow.

Version:

1.0 $Revision: 6488 $

Author:

Kees Schotanus

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static CRational	ZERO A rational value of zero.

Constructor Summary

Constructors

Constructor and Description
CRational(long numerator) Constructs a rational number from the supplied numerator and an implied denominator of one.
CRational(long numerator, long denominator) Constructs a rational number from the supplied numerator and denominator.

Method Summary

Modifier and Type	Method and Description
CRational	add(CRational rational) Adds the supplied rational number to this rational number.
static CRational	add(CRational left, CRational right) Adds the right rational number to the left rational number.
int	compareTo(CRational rational) Compares the supplied rational with this CRational.
CRational	divide(CRational rational) Divides this rational number by the supplied rational number.
static CRational	divide(CRational left, CRational right) Divides the left rational number by the right rational number.
double	doubleValue() Gets the value of this CRational as a double.
boolean	equals(Object object) Determines whether the supplied object is equal to this CRational.
long	getDenominator() Gets the denominator.
long	getNumerator() Gets the numerator.
int	hashCode() Computes a hash code for this object.
CRational	multiply(CRational rational) Multiplies this rational number by the supplied rational number.
static CRational	multiply(CRational left, CRational right) Multiplies the left rational number by the right rational number.
CRational	subtract(CRational rational) Subtracts the supplied rational number from this rational number.
static CRational	subtract(CRational left, CRational right) Subtracts the right rational number from the left rational number.
String	toString() Creates a String representation of this CRational.
static CRational	valueOf(double value) Converts the supplied value to a CRational.

Methods inherited from class java.lang.Object

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

Field Detail

ZERO

public static final CRational ZERO

A rational value of zero.

Constructor Detail

CRational

public CRational(long numerator)

Constructs a rational number from the supplied numerator and an implied denominator of one.

Parameters:

numerator - The numerator.

CRational

public CRational(long numerator,
                 long denominator)

Constructs a rational number from the supplied numerator and denominator.
When possible, the numerator and denominator are simplified. See the following table:

Supplied numerator	Supplied denominator	Stored numerator	Stored denominator
1	2	1	2
2	4	1	2
6	8	3	4
-6	-8	3	4
6	-8	-6	8
6	6	1	1

After construction it is guaranteed that the denominator is a positive number (the numerator carries the sign).

Parameters:

numerator - The numerator.

denominator - The non zero denominator.

Throws:

ArithmeticException - When the supplied denominator is zero.

Method Detail

getNumerator

public long getNumerator()

Gets the numerator.

Returns:

The numerator.

getDenominator

public long getDenominator()

Gets the denominator.

Returns:

The denominator.

add

public CRational add(CRational rational)

Adds the supplied rational number to this rational number.

Parameters:

rational - The rational number to add to this rational number.

Returns:

The result of the addition.

Throws:

NullPointerException - When the supplied rational number is null.

add

public static CRational add(CRational left,
                            CRational right)

Adds the right rational number to the left rational number.

Parameters:

left - The left rational number.

right - The right rational number.

Returns:

The result of the addition.

Throws:

NullPointerException - When either the supplied left or right rational number is null.

subtract

public CRational subtract(CRational rational)

Subtracts the supplied rational number from this rational number.

Parameters:

rational - The rational number to subtract from this rational number.

Returns:

The result of the subtraction.

Throws:

NullPointerException - When the supplied rational number is null.

subtract

public static CRational subtract(CRational left,
                                 CRational right)

Subtracts the right rational number from the left rational number.

Parameters:

left - The left rational number.

right - The right rational number.

Returns:

The result of the subtraction.

Throws:

NullPointerException - When either the supplied left or right rational number is null.

multiply

public CRational multiply(CRational rational)

Multiplies this rational number by the supplied rational number.

Parameters:

rational - The rational number to multiply by.

Returns:

The result of the multiplication.

Throws:

NullPointerException - When the supplied rational number is null.

multiply

public static CRational multiply(CRational left,
                                 CRational right)

Multiplies the left rational number by the right rational number.

Parameters:

left - The left rational number.

right - The right rational number.

Returns:

The result of the multiplication.

Throws:

NullPointerException - When either the supplied left or right rational number is null.

divide

public CRational divide(CRational rational)

Divides this rational number by the supplied rational number.

Parameters:

rational - The rational number to divide by.

Returns:

The result of the division.

Throws:

NullPointerException - When the supplied rational number is null.

divide

public static CRational divide(CRational left,
                               CRational right)

Divides the left rational number by the right rational number.

Parameters:

left - The left rational number.

right - The right rational number.

Returns:

The result of the division.

Throws:

ArithmeticException - When the numerator of the right operand is 0.

NullPointerException - When either the supplied left or right rational number is null.

equals

public boolean equals(Object object)

Determines whether the supplied object is equal to this CRational.
The supplied object is equal to this CRational when all of the following conditions are met:

1. The supplied object is not null
2. The supplied object is of type CRational
3. this.nominator * object.denominator = this.denominator * object.nominator

Overrides:

equals in class Object

Parameters:

object - The CRational object to compare with.

Returns:

true When both objects are equal, false otherwise.

hashCode

public int hashCode()

Computes a hash code for this object.

Overrides:

hashCode in class Object

Returns:

A hash code value for this object.

compareTo

public int compareTo(CRational rational)

Compares the supplied rational with this CRational.

Parameters:

rational - The CRational to compare with this CRational.

Returns:

-1 when this < rational, 0 when this == rational, 1 when this > rational.

Throws:

NullPointerException - When the supplied rational is null.

See Also:

Comparable

toString

public String toString()

Creates a String representation of this CRational.
The format is: [sign][integer][ ][numerator/denominator]
In words it is:

1. An optional sign (when the numerator is negative)
2. An optional integer value (when numerator > denominator)
3. An optional space (when there is a fraction)
4. Optionally "numerator/denominator" (when denominator != 1)

Simply put, it is what you mathematically would expect!

Overrides:

toString in class Object

Returns:

A String representation of this CRational.

doubleValue

public double doubleValue()

Gets the value of this CRational as a double.

Returns:

The decimal value of this CRational.

valueOf

public static CRational valueOf(double value)

Converts the supplied value to a CRational.

Parameters:

value - The value to be converted.

Returns:

The CRational that corresponds to the supplied value.

Throws:

IllegalArgumentException - When the supplied value is infinite or Not a Number.