Package com.zieglersoftware.num

Class Rat

java.lang.Object
java.lang.Number
com.zieglersoftware.num.Rat
All Implemented Interfaces:
Serializable, Comparable<Rat>
public final class Rat
extends Number
implements Comparable<Rat>
Immutable class that represents a rational number; i.e., a number that can be expressed exactly as the ratio of two integers (including whole numbers). The fraction will always be viewed in lowest terms when calling methods such as toString(), numerator(), and denominator().

Instances of Rat are acquired from the static rat() methods. It is recommended to statically import rat() for convenience. There are many overloads of rat() for acquiring Rat from different inputs. The string overload takes an arbitrary arithmetic expression as its argument, evaluates it, and returns the result as a Rat. The static instances ZERO, ONE, PI, and E are also available.

Arithmetic methods include negate, abs, invert, plus, minus, times, dividedBy, sqrt, nthRoot, pow, exp, log, and ln. Whenever possible, these arithmetic methods return an exact result; for example, 

 rat(-8,27).pow(rat(-2,3)) →  9/4
 rat(9,4).log(rat(8,27))   → -2/3
If the result is irrational, a very high-precision approximation is returned (at least 100 significant figures in the decimal representation).

Comparison methods equal, notEqual, greater, less, greaterOrEqual, lessOrEqual, isPositive, isNegative, and isZero are provided, as well as the method isInteger.

All method arguments must not be null unless otherwise stated.

Any reasonably sized rational number can be represented exactly, but if a numerator or denominator approaches the magnitude 2Integer.MAX_VALUE, overflow may occur.

See Also:
Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    static Rat E
    A Rat representation of e approximated to 100 decimal places
    static Rat ONE
    One
    static Rat PI
    A Rat representation of pi approximated to 100 decimal places
    static Rat ZERO
    Zero

  • Method Summary

    Modifier and Type Method Description
    Rat abs()
    Returns the absolute value of this Rat.
    BigDecimal bigDecimalValue()
    Returns a BigDecimal representation of this.
    int compareTo​(Rat other)
    Returns a positive result if this is greater than other, a negative result if this is less than other, and zero if this is numerically equal to other.
    BigInteger denominator()
    Returns the denominator of this, in its reduced-form representation.
    Rat dividedBy​(Rat other)
    Returns this/other.
    double doubleValue()
    Returns a double representation of this.
    boolean equal​(Rat other)
    Returns true if this is numerically equal to other.
    boolean equals​(Object obj)
    Returns true if the given object is a non-null Rat that is numerically equivalent to this.
    Rat exp()
    Returns ethis.
    float floatValue()
    Returns a float representation of this.
    boolean greater​(Rat other)
    Returns true if this is greater than other.
    boolean greaterOrEqual​(Rat other)
    Returns true if this is greater than or numerically equal to other.
    int hashCode()
    Returns a hash code of this.
    int intValue()
    Returns an int representation of this, if possible.
    Rat invert()
    Returns 1/this.
    boolean isInteger()
    Returns true if this Rat can be exactly represented with a denominator of one.
    boolean isNegative()
    Returns true if this Rat is less than zero.
    boolean isPositive()
    Returns true if this Rat is greater than zero.
    boolean isZero()
    Returns true if this Rat is equal to zero.
    boolean less​(Rat other)
    Returns true if this is less than other.
    boolean lessOrEqual​(Rat other)
    Returns true if this is less than or numerically equal to other.
    Rat ln()
    Returns the natural log of this; i.e., the log of this with base e.
    Rat log​(Rat base)
    Returns the log of this with the given base.
    long longValue()
    Returns a long representation of this, if possible.
    Rat minus​(Rat other)
    Returns this-other.
    Rat negate()
    Returns -1*this.
    boolean notEqual​(Rat other)
    Returns true if this is not numerically equal to other.
    Rat nthRoot​(long n)
    Returns the nth root of this; i.e.
    BigInteger numerator()
    Returns the numerator of this, in its reduced-form representation.
    Rat plus​(Rat other)
    Returns this+other.
    Rat pow​(Rat exponent)
    Returns thisexponent.
    static Rat rat​(double value)
    Returns a Rat equal to the given value.
    static Rat rat​(long value)
    Returns a Rat equal to value/1.
    static Rat rat​(long numerator, long denominator)
    Returns a Rat equal to numerator/denominator.
    static Rat rat​(String expression)
    Evaluates the given expression and returns the result as a Rat.
    static Rat rat​(BigDecimal value)
    Returns a Rat equal to the given value.
    static Rat rat​(BigInteger value)
    Returns a Rat equal to value/1.
    static Rat rat​(BigInteger numerator, BigInteger denominator)
    Returns a Rat equal to numerator/denominator.
    Rat reducePrecision​(int maxDigits)
    If both the numerator and denominator of this Rat have more digits than the given maximum, returns a different Rat where both the numerator and denominator have been divided by a power of 10 such that the shorter of the two has the requested number of digits.
    Rat round()
    Returns this Rat rounded to the nearest integer value.
    Rat sqrt()
    Returns the square root of this.
    Rat times​(Rat other)
    Returns this*other.
    String toString()
    Returns a string representation of this.

    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 Rat ZERO
      Zero

    • ONE

      public static final Rat ONE
      One

    • PI

      public static final Rat PI
      A Rat representation of pi approximated to 100 decimal places

    • E

      public static final Rat E
      A Rat representation of e approximated to 100 decimal places

  • Method Details

    • rat

      public static Rat rat​(BigInteger numerator, BigInteger denominator)
      Returns a Rat equal to numerator/denominator.

      denominator cannot be zero.

    • rat

      public static Rat rat​(BigInteger value)
      Returns a Rat equal to value/1.

    • rat

      public static Rat rat​(long value)
      Returns a Rat equal to value/1.

    • rat

      public static Rat rat​(long numerator, long denominator)
      Returns a Rat equal to numerator/denominator.

      denominator cannot be zero.

    • rat

      public static Rat rat​(BigDecimal value)
      Returns a Rat equal to the given value.

    • rat

      public static Rat rat​(double value)
      Returns a Rat equal to the given value.

    • rat

      public static Rat rat​(String expression)
      Evaluates the given expression and returns the result as a Rat. The expression must be a valid arithmetic expression, and may contain whitespace, digits, decimal points, parenthesis, and the operators + - * / ^.

    • isInteger

      public boolean isInteger()
      Returns true if this Rat can be exactly represented with a denominator of one.

      Whether or not it is small enough to be represented as an int is irrelevant.

    • isPositive

      public boolean isPositive()
      Returns true if this Rat is greater than zero.

    • isNegative

      public boolean isNegative()
      Returns true if this Rat is less than zero.

    • isZero

      public boolean isZero()
      Returns true if this Rat is equal to zero.

    • negate

      public Rat negate()
      Returns -1*this.

    • abs

      public Rat abs()
      Returns the absolute value of this Rat.

    • invert

      public Rat invert()
      Returns 1/this.

      If this is zero, an exception is thrown.

    • plus

      public Rat plus​(Rat other)
      Returns this+other.

    • minus

      public Rat minus​(Rat other)
      Returns this-other.

    • times

      public Rat times​(Rat other)
      Returns this*other.

    • dividedBy

      public Rat dividedBy​(Rat other)
      Returns this/other.

      other cannot be zero.

    • pow

      public Rat pow​(Rat exponent)
      Returns thisexponent.

      this and exponent cannot both be zero. If this is negative, the deonominator of exponent must be odd.

    • nthRoot

      public Rat nthRoot​(long n)
      Returns the nth root of this; i.e. this1/n.

      n must be greater than zero. If this is negative, n must be odd.

    • sqrt

      public Rat sqrt()
      Returns the square root of this.

      this cannot be negative.

    • exp

      public Rat exp()
      Returns ethis.

    • log

      public Rat log​(Rat base)
      Returns the log of this with the given base.

      this must be greater than zero. base must be greater than zero and not equal to one.

    • ln

      public Rat ln()
      Returns the natural log of this; i.e., the log of this with base e.

      this must be greater than zero.

    • equal

      public boolean equal​(Rat other)
      Returns true if this is numerically equal to other.

      The comparison is about numeric equivalence, so, for example, rat(1,2).equal(rat(2,4)) => true.

      This method is equivalent to equals(Object) in the case that the given object is a non-null Rat.

    • notEqual

      public boolean notEqual​(Rat other)
      Returns true if this is not numerically equal to other.

      The comparison is about numeric equivalence, so, for example, rat(1,2).notEqual(rat(2,4)) => false.

    • greater

      public boolean greater​(Rat other)
      Returns true if this is greater than other.

    • less

      public boolean less​(Rat other)
      Returns true if this is less than other.

    • greaterOrEqual

      public boolean greaterOrEqual​(Rat other)
      Returns true if this is greater than or numerically equal to other.

    • lessOrEqual

      public boolean lessOrEqual​(Rat other)
      Returns true if this is less than or numerically equal to other.

    • compareTo

      public int compareTo​(Rat other)
      Returns a positive result if this is greater than other, a negative result if this is less than other, and zero if this is numerically equal to other.
      Specified by:
      compareTo in interface Comparable<Rat>

    • numerator

      public BigInteger numerator()
      Returns the numerator of this, in its reduced-form representation.

    • denominator

      public BigInteger denominator()
      Returns the denominator of this, in its reduced-form representation.

    • round

      public Rat round()
      Returns this Rat rounded to the nearest integer value. Uses RoundingMode.HALF_UP.

      Examples: 

        1   →  1
  4/5 →  1
  1/2 →  1
  1/5 →  0
  0   →  0
 -1/5 →  0
 -1/2 → -1
 -4/5 → -1
 -1   → -1

    • reducePrecision

      public Rat reducePrecision​(int maxDigits)
      If both the numerator and denominator of this Rat have more digits than the given maximum, returns a different Rat where both the numerator and denominator have been divided by a power of 10 such that the shorter of the two has the requested number of digits. If rounding is necessary, RoundingMode.HALF_UP is used.

      Note that the resulting fraction will be reduced if possible, so may contain different leading digits than this Rat.

      If either the numerator or denominator of this Rat does not exceed the requested number of digits, a Rat of the same value is returned.

      Examples: 

       1234/2345, 3 →  123/235 
 1234/2345, 4 → 1234/2345 
 1234/2345, 5 → 1234/2345
  123/4567, 2 →   12/457
  123/4561, 2 →    1/38 (12/456 reduced)
  123/4567, 3 →  123/4567
  123/4567, 4 →  123/4567

    • bigDecimalValue

      public BigDecimal bigDecimalValue()
      Returns a BigDecimal representation of this.

    • doubleValue

      public double doubleValue()
      Returns a double representation of this. Precision may be lost because double has limited precision. If the magnitude of this is too large to be represented as a double, an exception is thrown.
      Specified by:
      doubleValue in class Number

    • floatValue

      public float floatValue()
      Returns a float representation of this. Precision may be lost because float has limited precision. If the magnitude of this is too large to be represented as a float, an exception is thrown.
      Specified by:
      floatValue in class Number

    • longValue

      public long longValue()
      Returns a long representation of this, if possible. If this cannot be exactly represented as a long, an exception is thrown.
      Specified by:
      longValue in class Number

    • intValue

      public int intValue()
      Returns an int representation of this, if possible. If this cannot be exactly represented as an int, an exception is thrown.
      Specified by:
      intValue in class Number

    • equals

      public boolean equals​(Object obj)
      Returns true if the given object is a non-null Rat that is numerically equivalent to this.

      This method is equivalent to equal(Rat) in the case that the given object is a non-null Rat.

      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Returns a hash code of this.
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Returns a string representation of this. The representation will be reduced to lowest terms.
      Overrides:
      toString in class Object