Class Rational

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

public final class Rational extends Number implements 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
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final long
     
    static final Rational
    Convenient constant representing a value of a half (1/2 as a rational).
    private final long
     
    static final Rational
    Convenient constant representing a value of one (1/1 as a rational).
    static final Rational
    Convenient constant representing a value of a quarter (1/4 as a rational).
    static final Rational
    Convenient constant representing a value of a third (1/3 as a rational).
    static final Rational
    Convenient constant representing a value of three quarters (3/4 as a rational).
    static final Rational
    Convenient constant representing a value of two thirds (2/3 as a rational).
    static final Rational
    Convenient constant representing a value of zero (0/1 as a rational).
  • Constructor Summary

    Constructors
    Constructor
    Description
    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.
    Creates a rational value equivalent to the specified decimal value.
  • Method Summary

    Modifier and Type
    Method
    Description
    add(Rational value)
    Add the specified value to this value and return the result as a new object (also a rational).
    int
    Compares this value with the specified object for order.
    Divide this rational by the specified value and return the result as a new object (also a Rational).
    double
    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
    Returns the result of dividing the numerator by the denominator.
    long
    Returns the denominator (divisor) of the fraction.
    long
    Returns the numerator of the fraction.
    int
    Over-ridden to be consistent with equals(Object).
    int
    Returns the integer equivalent of this rational number.
    long
    Returns the integer equivalent of this rational number as a long.
    Multiply this rational by the specified value and return the result as a new object (also a Rational).
    Subtract the specified value from this value and return the result as a new object (also a rational).
    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 Details

    • 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).
    • numerator

      private final long numerator
    • denominator

      private final long denominator
  • Constructor Details

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

    • 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.
    • add

      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.