Uncommons Maths API
(Version 1.2.3)

## org.uncommons.maths.number Class Rational

```java.lang.Object
java.lang.Number
org.uncommons.maths.number.Rational
```
All Implemented Interfaces:
Serializable, Comparable<Rational>

`public final class Rationalextends Numberimplements Comparable<Rational>`

Immutable value object for representing a rational number (or vulgar fraction). Instances of this class provide a way to perform arithmetic on fractional values without loss of precision. This implementation automatically simplifies fractions (3/6 is stored as 1/2). The implementation also requires that the denominator is positive. The numerator may be negative.

Since:
1.2
Author:
Daniel Dyer
Serialized Form

Field Summary
`static Rational` `HALF`
Convenient constant representing a value of a half (1/2 as a rational).
`static Rational` `ONE`
Convenient constant representing a value of one (1/1 as a rational).
`static Rational` `QUARTER`
Convenient constant representing a value of a quarter (1/4 as a rational).
`static Rational` `THIRD`
Convenient constant representing a value of a third (1/3 as a rational).
`static Rational` `THREE_QUARTERS`
Convenient constant representing a value of three quarters (3/4 as a rational).
`static Rational` `TWO_THIRDS`
Convenient constant representing a value of two thirds (2/3 as a rational).
`static Rational` `ZERO`
Convenient constant representing a value of zero (0/1 as a rational).

Constructor Summary
`Rational(BigDecimal value)`
Creates a rational value equivalent to the specified decimal value.
`Rational(long value)`
Creates a rational value equivalent to the specified integer value.
```Rational(long numerator, long denominator)```
Creates a vulgar fraction with the specified numerator and denominator.

Method Summary
` Rational` `add(Rational value)`
Add the specified value to this value and return the result as a new object (also a rational).
` int` `compareTo(Rational other)`
Compares this value with the specified object for order.
` Rational` `divide(Rational value)`
Divide this rational by the specified value and return the result as a new object (also a Rational).
` double` `doubleValue()`
Returns the result of dividing the numerator by the denominator.
` boolean` `equals(Object other)`
Determines whether this rational value is equal to some other object.
` float` `floatValue()`
Returns the result of dividing the numerator by the denominator.
` long` `getDenominator()`
Returns the denominator (divisor) of the fraction.
` long` `getNumerator()`
Returns the numerator of the fraction.
` int` `hashCode()`
Over-ridden to be consistent with `equals(Object)`.
` int` `intValue()`
Returns the integer equivalent of this rational number.
` long` `longValue()`
Returns the integer equivalent of this rational number as a long.
` Rational` `multiply(Rational value)`
Multiply this rational by the specified value and return the result as a new object (also a Rational).
` Rational` `subtract(Rational value)`
Subtract the specified value from this value and return the result as a new object (also a rational).
` String` `toString()`
Returns a String representation of the rational number, expressed as a vulgar fraction (i.e.

Methods inherited from class java.lang.Number
`byteValue, shortValue`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### ZERO

`public static final Rational ZERO`
Convenient constant representing a value of zero (0/1 as a rational).

### QUARTER

`public static final Rational QUARTER`
Convenient constant representing a value of a quarter (1/4 as a rational).

### THIRD

`public static final Rational THIRD`
Convenient constant representing a value of a third (1/3 as a rational).

### HALF

`public static final Rational HALF`
Convenient constant representing a value of a half (1/2 as a rational).

### TWO_THIRDS

`public static final Rational TWO_THIRDS`
Convenient constant representing a value of two thirds (2/3 as a rational).

### THREE_QUARTERS

`public static final Rational THREE_QUARTERS`
Convenient constant representing a value of three quarters (3/4 as a rational).

### ONE

`public static final Rational ONE`
Convenient constant representing a value of one (1/1 as a rational).

Constructor Detail

### Rational

```public Rational(long numerator,
long denominator)```
Creates a vulgar fraction with the specified numerator and denominator.

Parameters:
`numerator` - The fraction's numerator (may be negative).
`denominator` - The fraction's denominator (must be greater than or equal to 1).

### Rational

`public Rational(long value)`
Creates a rational value equivalent to the specified integer value.

Parameters:
`value` - The value of this rational as an integer.

### Rational

`public Rational(BigDecimal value)`
Creates a rational value equivalent to the specified decimal value.

Parameters:
`value` - The value of this rational as a fractional decimal.
Throws:
`ArithmeticException` - If the BigDecimal value is too large to be represented as a Rational.
Method Detail

### getNumerator

`public long getNumerator()`
Returns the numerator of the fraction.

Returns:
The numerator.

### getDenominator

`public long getDenominator()`
Returns the denominator (divisor) of the fraction.

Returns:
The denominator.

`public Rational add(Rational value)`
Add the specified value to this value and return the result as a new object (also a rational). If the two values have different denominators, they will first be converted so that they have common denominators.

Parameters:
`value` - The value to add to this rational.
Returns:
A new rational value that is the sum of this value and the specified value.

### subtract

`public Rational subtract(Rational value)`
Subtract the specified value from this value and return the result as a new object (also a rational). If the two values have different denominators, they will first be converted so that they have common denominators.

Parameters:
`value` - The value to subtract from this rational.
Returns:
A new rational value that is the result of subtracting the specified value from this value.

### multiply

`public Rational multiply(Rational value)`
Multiply this rational by the specified value and return the result as a new object (also a Rational).

Parameters:
`value` - The amount to multiply by.
Returns:
A new rational value that is the result of multiplying this value by the specified value.

### divide

`public Rational divide(Rational value)`
Divide this rational by the specified value and return the result as a new object (also a Rational).

Parameters:
`value` - The amount to divide by.
Returns:
A new rational value that is the result of dividing this value by the specified value.

### intValue

`public int intValue()`
Returns the integer equivalent of this rational number. If there is no exact integer representation, it returns the closest integer that is lower than the rational value (effectively the truncated version of calling `doubleValue()`).

Specified by:
`intValue` in class `Number`
Returns:
The (truncated) integer value of this rational.

### longValue

`public long longValue()`
Returns the integer equivalent of this rational number as a long. If there is no exact integer representation, it returns the closest long that is lower than the rational value (effectively the truncated version of calling `doubleValue()`).

Specified by:
`longValue` in class `Number`
Returns:
The (truncated) long value of this rational.

### floatValue

`public float floatValue()`
Returns the result of dividing the numerator by the denominator. Will result in a loss of precision for fractions that have no exact float representation.

Specified by:
`floatValue` in class `Number`
Returns:
The closest double-precision floating point equivalent of the fraction represented by this object.

### doubleValue

`public double doubleValue()`
Returns the result of dividing the numerator by the denominator. Will result in a loss of precision for fractions that have no exact double representation.

Specified by:
`doubleValue` in class `Number`
Returns:
The closest double-precision floating point equivalent of the fraction represented by this object.

### equals

`public boolean equals(Object other)`
Determines whether this rational value is equal to some other object. To be considered equal the other object must also be a Rational object with an indentical numerator and denominator.

Overrides:
`equals` in class `Object`
Parameters:
`other` - The object to compare against.
Returns:
True if the objects are equal, false otherwise.

### hashCode

`public int hashCode()`
Over-ridden to be consistent with `equals(Object)`.

Overrides:
`hashCode` in class `Object`
Returns:
The hash code value.

### toString

`public String toString()`
Returns a String representation of the rational number, expressed as a vulgar fraction (i.e. 1 and 1/3 is shown as 4/3). If the rational is equal to an integer, the value is simply displayed as that integer with no fractional part (i.e. 2/1 is shown as 2).

Overrides:
`toString` in class `Object`
Returns:
A string representation of this rational value.

### compareTo

`public int compareTo(Rational other)`
Compares this value with the specified object for order. Returns a negative integer, zero, or a positive integer as this value is less than, equal to, or greater than the specified value.

Specified by:
`compareTo` in interface `Comparable<Rational>`
Parameters:
`other` - Another Rational value.
Returns:
A negative integer, zero, or a positive integer as this value is less than, equal to, or greater than the specified value.

Uncommons Maths API
(Version 1.2.3)