Class Fraction

java.lang.Object
java.lang.Number
org.apache.commons.numbers.fraction.Fraction
All Implemented Interfaces:
Serializable, Comparable<Fraction>, Addition<Fraction>, Multiplication<Fraction>, NativeOperators<Fraction>
public final class Fraction extends Number implements Comparable<Fraction>, NativeOperators<Fraction>, Serializable
Representation of a rational number.

The number is expressed as the quotient p/q of two 32-bit integers, a numerator p and a non-zero denominator q.

This class is immutable. Rational number

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final double
    DEFAULT_EPSILON
    The default epsilon used for convergence.
    private static final int
    DEFAULT_MAX_ITERATIONS
    The default iterations used for convergence.
    private final int
    denominator
    The denominator of this fraction reduced to lowest terms.
    private static final String
    NOT_FINITE
    Message for non-finite input double argument to factory constructors.
    private final int
    numerator
    The numerator of this fraction reduced to lowest terms.
    static final Fraction
    ONE
    A fraction representing "1".
    private static final long
    OVERFLOW
    The overflow limit for conversion from a double (2^31).
    private static final long
    serialVersionUID
    Serializable version identifier.
    static final Fraction
    ZERO
    A fraction representing "0".

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Fraction(double value, double epsilon, int maxDenominator, int maxIterations)
    Create a fraction given the double value and either the maximum error allowed or the maximum number of denominator digits.
    private
    Fraction(int num)
    Private constructor: Instances are created using factory methods.
    private
    Fraction(int num, int den)
    Private constructor: Instances are created using factory methods.

  • Method Summary

    Modifier and Type
    Method
    Description
    Fraction
    abs()
    Returns the absolute value of this fraction.
    Fraction
    add(int value)
    Adds the specified value to this fraction, returning the result in reduced form.
    Fraction
    add(Fraction value)
    Adds the specified value to this fraction, returning the result in reduced form.
    private Fraction
    addSub(Fraction value, boolean isAdd)
    Implements add and subtract using algorithm described in Knuth 4.5.1.
    int
    compareTo(Fraction other)
    Compares this object with the specified object for order using the signed magnitude.
    Fraction
    divide(int value)
    Divide this fraction by the passed value, returning the result in reduced form.
    Fraction
    divide(Fraction value)
    Divide this fraction by the passed value, returning the result in reduced form.
    double
    doubleValue()
    Returns the double value closest to this fraction.
    boolean
    equals(Object other)
    Test for equality with another object.
    float
    floatValue()
    Returns the float value closest to this fraction.
    static Fraction
    from(double value)
    Create a fraction given the double value.
    static Fraction
    from(double value, double epsilon, int maxIterations)
    Create a fraction given the double value and maximum error allowed.
    static Fraction
    from(double value, int maxDenominator)
    Create a fraction given the double value and maximum denominator.
    int
    getDenominator()
    Access the denominator as an int.
    int
    getNumerator()
    Access the numerator as an int.
    int
    hashCode()
     
    int
    intValue()
    Returns the whole number part of the fraction.
    boolean
    isOne()
    Check if this is a neutral element of multiplication, i.e.
    boolean
    isZero()
    Check if this is a neutral element of addition, i.e.
    long
    longValue()
    Returns the whole number part of the fraction.
    Fraction
    multiply(int value)
    Multiply this fraction by the passed value, returning the result in reduced form.
    private Fraction
    multiply(int num, int den)
    Multiply this fraction by the passed fraction decomposed into a numerator and denominator, returning the result in reduced form.
    Fraction
    multiply(Fraction value)
    Multiply this fraction by the passed value, returning the result in reduced form.
    Fraction
    negate()
    Additive inverse.
    static Fraction
    of(int num)
    Create a fraction given the numerator.
    static Fraction
    of(int num, int den)
    Create a fraction given the numerator and denominator.
    Fraction
    one()
    Identity element.
    static Fraction
    parse(String s)
    Returns a Fraction instance representing the specified string s.
    Fraction
    pow(int exponent)
    Returns a Fraction whose value is thisexponent, returning the result in reduced form.
    Fraction
    reciprocal()
    Multiplicative inverse.
    int
    signum()
    Retrieves the sign of this fraction.
    Fraction
    subtract(int value)
    Subtracts the specified value from this fraction, returning the result in reduced form.
    Fraction
    subtract(Fraction value)
    Subtracts the specified value from this fraction, returning the result in reduced form.
    String
    toString()
    Returns the String representing this fraction.
    Fraction
    zero()
    Identity element.

    Methods inherited from class Number

    byteValue, shortValue

    Methods inherited from class Object

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

  • Field Details

    • ZERO

      public static final Fraction ZERO
      A fraction representing "0".

    • ONE

      public static final Fraction ONE
      A fraction representing "1".

    • serialVersionUID

      private static final long serialVersionUID
      Serializable version identifier.
      See Also:

    • DEFAULT_EPSILON

      private static final double DEFAULT_EPSILON
      The default epsilon used for convergence.
      See Also:

    • DEFAULT_MAX_ITERATIONS

      private static final int DEFAULT_MAX_ITERATIONS
      The default iterations used for convergence.
      See Also:

    • NOT_FINITE

      private static final String NOT_FINITE
      Message for non-finite input double argument to factory constructors.
      See Also:

    • OVERFLOW

      private static final long OVERFLOW
      The overflow limit for conversion from a double (2^31).
      See Also:

    • numerator

      private final int numerator
      The numerator of this fraction reduced to lowest terms.

    • denominator

      private final int denominator
      The denominator of this fraction reduced to lowest terms.

  • Constructor Details

    • Fraction

      private Fraction(int num, int den)
      Private constructor: Instances are created using factory methods.

      This constructor should only be invoked when the fraction is known to be non-zero; otherwise use ZERO. This avoids creating the zero representation 0 / -1.

      Parameters:
      num - Numerator.
      den - Denominator.
      Throws:
      ArithmeticException - if the denominator is zero.

    • Fraction

      private Fraction(int num)
      Private constructor: Instances are created using factory methods.

      This sets the denominator to 1.

      Parameters:
      num - Numerator.

    • Fraction

      private Fraction(double value, double epsilon, int maxDenominator, int maxIterations)
      Create a fraction given the double value and either the maximum error allowed or the maximum number of denominator digits.

      NOTE: This constructor is called with:

      • EITHER a valid epsilon value and the maxDenominator set to Integer.MAX_VALUE (that way the maxDenominator has no effect)
      • OR a valid maxDenominator value and the epsilon value set to zero (that way epsilon only has effect if there is an exact match before the maxDenominator value is reached).

      It has been done this way so that the same code can be reused for both scenarios. However this could be confusing to users if it were part of the public API and this method should therefore remain PRIVATE.

      See JIRA issue ticket MATH-181 for more details: https://issues.apache.org/jira/browse/MATH-181

      Warning: This conversion assumes the value is not zero.

      Parameters:
      value - Value to convert to a fraction. Must not be zero.
      epsilon - Maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
      maxDenominator - Maximum denominator value allowed.
      maxIterations - Maximum number of convergents.
      Throws:
      IllegalArgumentException - if the given value is NaN or infinite.
      ArithmeticException - if the continued fraction failed to converge.

  • Method Details

    • from

      public static Fraction from(double value)
      Create a fraction given the double value.
      Parameters:
      value - Value to convert to a fraction.
      Returns:
      a new instance.
      Throws:
      IllegalArgumentException - if the given value is NaN or infinite.
      ArithmeticException - if the continued fraction failed to converge.

    • from

      public static Fraction from(double value, double epsilon, int maxIterations)
      Create a fraction given the double value and maximum error allowed.

      References:

      Parameters:
      value - Value to convert to a fraction.
      epsilon - Maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
      maxIterations - Maximum number of convergents.
      Returns:
      a new instance.
      Throws:
      IllegalArgumentException - if the given value is NaN or infinite; epsilon is not positive; or maxIterations < 1.
      ArithmeticException - if the continued fraction failed to converge.

    • from

      public static Fraction from(double value, int maxDenominator)
      Create a fraction given the double value and maximum denominator.

      References:

      Note: The magnitude of the maxDenominator is used allowing use of Integer.MIN_VALUE for a supported maximum denominator of 231.

      Parameters:
      value - Value to convert to a fraction.
      maxDenominator - Maximum allowed value for denominator.
      Returns:
      a new instance.
      Throws:
      IllegalArgumentException - if the given value is NaN or infinite or maxDenominator is zero.
      ArithmeticException - if the continued fraction failed to converge.

    • of

      public static Fraction of(int num)
      Create a fraction given the numerator. The denominator is 1.
      Parameters:
      num - Numerator.
      Returns:
      a new instance.

    • of

      public static Fraction of(int num, int den)
      Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.
      Parameters:
      num - Numerator.
      den - Denominator.
      Returns:
      a new instance.
      Throws:
      ArithmeticException - if the denominator is zero.

    • parse

      public static Fraction parse(String s)
      Returns a Fraction instance representing the specified string s.

      If s is null, then a NullPointerException is thrown.

      The string must be in a format compatible with that produced by Fraction.toString(). The format expects an integer optionally followed by a '/' character and and second integer. Leading and trailing spaces are allowed around each numeric part. Each numeric part is parsed using Integer.parseInt(String). The parts are interpreted as the numerator and optional denominator of the fraction. If absent the denominator is assumed to be "1".

      Examples of valid strings and the equivalent Fraction are shown below: 

      "0"                 = Fraction.of(0)
"42"                = Fraction.of(42)
"0 / 1"             = Fraction.of(0, 1)
"1 / 3"             = Fraction.of(1, 3)
"-4 / 13"           = Fraction.of(-4, 13)

      Note: The fraction is returned in reduced form and the numerator and denominator may not match the values in the input string. For this reason the result of Fraction.parse(s).toString().equals(s) may not be true.

      Parameters:
      s - String representation.
      Returns:
      an instance.
      Throws:
      NullPointerException - if the string is null.
      NumberFormatException - if the string does not contain a parsable fraction.
      See Also:

    • zero

      public Fraction zero()
      Description copied from interface: Addition
      Identity element.
      Specified by:
      zero in interface Addition<Fraction>
      Returns:
      the field element such that for all a, zero().add(a).equals(a) is true.

    • isZero

      public boolean isZero()
      Check if this is a neutral element of addition, i.e. this.add(a) returns a or an element representing the same value as a.

      The default implementation calls equals(zero()). Implementations may want to employ more a efficient method. This may even be required if an implementation has multiple representations of zero and its equals method differentiates between them.

      Specified by:
      isZero in interface Addition<Fraction>
      Returns:
      true if this is a neutral element of addition.
      See Also:

    • one

      public Fraction one()
      Description copied from interface: Multiplication
      Identity element.
      Specified by:
      one in interface Multiplication<Fraction>
      Returns:
      the field element such that for all a, one().multiply(a).equals(a) is true.

    • isOne

      public boolean isOne()
      Check if this is a neutral element of multiplication, i.e. this.multiply(a) returns a or an element representing the same value as a.

      The default implementation calls equals(one()). Implementations may want to employ more a efficient method. This may even be required if an implementation has multiple representations of one and its equals method differentiates between them.

      Specified by:
      isOne in interface Multiplication<Fraction>
      Returns:
      true if this is a neutral element of multiplication.
      See Also:

    • getNumerator

      public int getNumerator()
      Access the numerator as an int.
      Returns:
      the numerator as an int.

    • getDenominator

      public int getDenominator()
      Access the denominator as an int.
      Returns:
      the denominator as an int.

    • signum

      public int signum()
      Retrieves the sign of this fraction.
      Returns:
      -1 if the value is strictly negative, 1 if it is strictly positive, 0 if it is 0.

    • abs

      public Fraction abs()
      Returns the absolute value of this fraction.
      Returns:
      the absolute value.

    • negate

      public Fraction negate()
      Description copied from interface: Addition
      Additive inverse.
      Specified by:
      negate in interface Addition<Fraction>
      Returns:
      -this.

    • reciprocal

      public Fraction reciprocal()
      Multiplicative inverse.

      Raises an exception if the fraction is equal to zero.

      Specified by:
      reciprocal in interface Multiplication<Fraction>
      Returns:
      this-1.
      Throws:
      ArithmeticException - if the current numerator is zero

    • doubleValue

      public double doubleValue()
      Returns the double value closest to this fraction. This calculates the fraction as numerator divided by denominator.
      Specified by:
      doubleValue in class Number
      Returns:
      the fraction as a double.

    • floatValue

      public float floatValue()
      Returns the float value closest to this fraction. This calculates the fraction as numerator divided by denominator.
      Specified by:
      floatValue in class Number
      Returns:
      the fraction as a float.

    • intValue

      public int intValue()
      Returns the whole number part of the fraction.
      Specified by:
      intValue in class Number
      Returns:
      the largest int value that is not larger than this fraction.

    • longValue

      public long longValue()
      Returns the whole number part of the fraction.
      Specified by:
      longValue in class Number
      Returns:
      the largest long value that is not larger than this fraction.

    • add

      public Fraction add(int value)
      Adds the specified value to this fraction, returning the result in reduced form.
      Parameters:
      value - Value to add.
      Returns:
      this + value.
      Throws:
      ArithmeticException - if the resulting numerator cannot be represented in an int.

    • add

      public Fraction add(Fraction value)
      Adds the specified value to this fraction, returning the result in reduced form.
      Specified by:
      add in interface Addition<Fraction>
      Parameters:
      value - Value to add.
      Returns:
      this + value.
      Throws:
      ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

    • subtract

      public Fraction subtract(int value)
      Subtracts the specified value from this fraction, returning the result in reduced form.
      Parameters:
      value - Value to subtract.
      Returns:
      this - value.
      Throws:
      ArithmeticException - if the resulting numerator cannot be represented in an int.

    • subtract

      public Fraction subtract(Fraction value)
      Subtracts the specified value from this fraction, returning the result in reduced form.
      Specified by:
      subtract in interface NativeOperators<Fraction>
      Parameters:
      value - Value to subtract.
      Returns:
      this - value.
      Throws:
      ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

    • addSub

      private Fraction addSub(Fraction value, boolean isAdd)
      Implements add and subtract using algorithm described in Knuth 4.5.1.
      Parameters:
      value - Fraction to add or subtract.
      isAdd - Whether the operation is "add" or "subtract".
      Returns:
      a new instance.
      Throws:
      ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

    • multiply

      public Fraction multiply(int value)
      Multiply this fraction by the passed value, returning the result in reduced form.
      Specified by:
      multiply in interface NativeOperators<Fraction>
      Parameters:
      value - Value to multiply by.
      Returns:
      this * value.
      Throws:
      ArithmeticException - if the resulting numerator cannot be represented in an int.

    • multiply

      public Fraction multiply(Fraction value)
      Multiply this fraction by the passed value, returning the result in reduced form.
      Specified by:
      multiply in interface Multiplication<Fraction>
      Parameters:
      value - Value to multiply by.
      Returns:
      this * value.
      Throws:
      ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

    • multiply

      private Fraction multiply(int num, int den)
      Multiply this fraction by the passed fraction decomposed into a numerator and denominator, returning the result in reduced form.

      This is a utility method to be used by multiply and divide. The decomposed fraction arguments and this fraction are not checked for zero.

      Parameters:
      num - Fraction numerator.
      den - Fraction denominator.
      Returns:
      this * num / den.
      Throws:
      ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

    • divide

      public Fraction divide(int value)
      Divide this fraction by the passed value, returning the result in reduced form.
      Parameters:
      value - Value to divide by
      Returns:
      this / value.
      Throws:
      ArithmeticException - if the value to divide by is zero or if the resulting numerator or denominator cannot be represented by an int.

    • divide

      public Fraction divide(Fraction value)
      Divide this fraction by the passed value, returning the result in reduced form.
      Specified by:
      divide in interface NativeOperators<Fraction>
      Parameters:
      value - Value to divide by
      Returns:
      this / value.
      Throws:
      ArithmeticException - if the value to divide by is zero or if the resulting numerator or denominator cannot be represented by an int.

    • pow

      public Fraction pow(int exponent)
      Returns a Fraction whose value is thisexponent, returning the result in reduced form.
      Specified by:
      pow in interface NativeOperators<Fraction>
      Parameters:
      exponent - exponent to which this Fraction is to be raised.
      Returns:
      thisexponent.
      Throws:
      ArithmeticException - if the intermediate result would overflow.

    • toString

      public String toString()
      Returns the String representing this fraction. Uses:
      • "0" if numerator is zero.
      • "numerator" if denominator is one.
      • "numerator / denominator" for all other cases.
      Overrides:
      toString in class Object
      Returns:
      a string representation of the fraction.

    • compareTo

      public int compareTo(Fraction other)
      Compares this object with the specified object for order using the signed magnitude.
      Specified by:
      compareTo in interface Comparable<Fraction>
      Parameters:
      other -
      Returns:

    • equals

      public boolean equals(Object other)
      Test for equality with another object. If the other object is a Fraction then a comparison is made of the sign and magnitude; otherwise false is returned.
      Overrides:
      equals in class Object
      Parameters:
      other -
      Returns:

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object