org.apache.commons.math3.fraction

## Class Fraction

- java.lang.Object
- - java.lang.Number
  - - org.apache.commons.math3.fraction.Fraction

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Comparable<Fraction>, FieldElement<Fraction>

      public class Fraction
      extends java.lang.Number
      implements FieldElement<Fraction>, java.lang.Comparable<Fraction>, java.io.Serializable

  Representation of a rational number. implements Serializable since 2.0
  Since:
    1.1
  Version:
    $Id: Fraction.java 1416643 2012-12-03 19:37:14Z tn $
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `private int` | `denominator` The denominator.
    `static Fraction` | `FOUR_FIFTHS` A fraction representing "4/5".
    `static Fraction` | `MINUS_ONE` A fraction representing "-1 / 1".
    `private int` | `numerator` The numerator.
    `static Fraction` | `ONE` A fraction representing "1".
    `static Fraction` | `ONE_FIFTH` A fraction representing "1/5".
    `static Fraction` | `ONE_HALF` A fraction representing "1/2".
    `static Fraction` | `ONE_QUARTER` A fraction representing "1/4".
    `static Fraction` | `ONE_THIRD` A fraction representing "1/3".
    `private static long` | `serialVersionUID` Serializable version identifier
    `static Fraction` | `THREE_FIFTHS` A fraction representing "3/5".
    `static Fraction` | `THREE_QUARTERS` A fraction representing "3/4".
    `static Fraction` | `TWO` A fraction representing "2 / 1".
    `static Fraction` | `TWO_FIFTHS` A fraction representing "2/5".
    `static Fraction` | `TWO_QUARTERS` A fraction representing "2/4".
    `static Fraction` | `TWO_THIRDS` A fraction representing "2/3".
    `static Fraction` | `ZERO` A fraction representing "0".

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `Fraction(double value)` Create a fraction given the double value.
    `` | `Fraction(double value, double epsilon, int maxIterations)` Create a fraction given the double value and maximum error allowed.
    `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.
    `` | `Fraction(double value, int maxDenominator)` Create a fraction given the double value and maximum denominator.
    `` | `Fraction(int num)` Create a fraction from an int.
    `` | `Fraction(int num, int den)` Create a fraction given the numerator and denominator.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Fraction` | `abs()` Returns the absolute value of this fraction.
    `Fraction` | `add(Fraction fraction)` Adds the value of this fraction to another, returning the result in reduced form.
    `Fraction` | `add(int i)` Add an integer to the fraction.
    `private Fraction` | `addSub(Fraction fraction, boolean isAdd)` Implement add and subtract using algorithm described in Knuth 4.5.1.
    `int` | `compareTo(Fraction object)` Compares this object to another based on size.
    `Fraction` | `divide(Fraction fraction)` Divide the value of this fraction by another.
    `Fraction` | `divide(int i)` Divide the fraction by an integer.
    `double` | `doubleValue()` Gets the fraction as a `double`.
    `boolean` | `equals(java.lang.Object other)` Test for the equality of two fractions.
    `float` | `floatValue()` Gets the fraction as a `float`.
    `int` | `getDenominator()` Access the denominator.
    `FractionField` | `getField()` Get the `Field` to which the instance belongs.
    `int` | `getNumerator()` Access the numerator.
    `static Fraction` | `getReducedFraction(int numerator, int denominator)` Creates a `Fraction` instance with the 2 parts of a fraction Y/Z.
    `int` | `hashCode()` Gets a hashCode for the fraction.
    `int` | `intValue()` Gets the fraction as an `int`.
    `long` | `longValue()` Gets the fraction as a `long`.
    `Fraction` | `multiply(Fraction fraction)` Multiplies the value of this fraction by another, returning the result in reduced form.
    `Fraction` | `multiply(int i)` Multiply the fraction by an integer.
    `Fraction` | `negate()` Return the additive inverse of this fraction.
    `double` | `percentageValue()` Gets the fraction percentage as a `double`.
    `Fraction` | `reciprocal()` Return the multiplicative inverse of this fraction.
    `Fraction` | `subtract(Fraction fraction)` Subtracts the value of another fraction from the value of this one, returning the result in reduced form.
    `Fraction` | `subtract(int i)` Subtract an integer from the fraction.
    `java.lang.String` | `toString()` Returns the `String` representing this fraction, ie "num / dem" or just "num" if the denominator is one.

    - ### 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

    - #### TWO

          public static final Fraction TWO

      A fraction representing "2 / 1".

    - #### ONE

          public static final Fraction ONE

      A fraction representing "1".

    - #### ZERO

          public static final Fraction ZERO

      A fraction representing "0".

    - #### FOUR_FIFTHS

          public static final Fraction FOUR_FIFTHS

      A fraction representing "4/5".

    - #### ONE_FIFTH

          public static final Fraction ONE_FIFTH

      A fraction representing "1/5".

    - #### ONE_HALF

          public static final Fraction ONE_HALF

      A fraction representing "1/2".

    - #### ONE_QUARTER

          public static final Fraction ONE_QUARTER

      A fraction representing "1/4".

    - #### ONE_THIRD

          public static final Fraction ONE_THIRD

      A fraction representing "1/3".

    - #### THREE_FIFTHS

          public static final Fraction THREE_FIFTHS

      A fraction representing "3/5".

    - #### THREE_QUARTERS

          public static final Fraction THREE_QUARTERS

      A fraction representing "3/4".

    - #### TWO_FIFTHS

          public static final Fraction TWO_FIFTHS

      A fraction representing "2/5".

    - #### TWO_QUARTERS

          public static final Fraction TWO_QUARTERS

      A fraction representing "2/4".

    - #### TWO_THIRDS

          public static final Fraction TWO_THIRDS

      A fraction representing "2/3".

    - #### MINUS_ONE

          public static final Fraction MINUS_ONE

      A fraction representing "-1 / 1".

    - #### serialVersionUID

          private static final long serialVersionUID

      Serializable version identifier
      See Also:
        Constant Field Values

    - #### denominator

          private final int denominator

      The denominator.

    - #### numerator

          private final int numerator

      The numerator.

  - ### Constructor Detail

    - #### Fraction

          public Fraction(double value)
                   throws FractionConversionException

      Create a fraction given the double value.
      Parameters:
        `value` - the double value to convert to a fraction.
      Throws:
        `FractionConversionException` - if the continued fraction failed to converge.

    - #### Fraction

          public Fraction(double value,
                  double epsilon,
                  int maxIterations)
                   throws FractionConversionException

      Create a fraction given the double value and maximum error allowed.

      References:

      - Continued Fraction equations (11) and (22)-(26)
      Parameters:
        `value` - the double 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
      Throws:
        `FractionConversionException` - if the continued fraction failed to converge.

    - #### Fraction

          public Fraction(double value,
                  int maxDenominator)
                   throws FractionConversionException

      Create a fraction given the double value and maximum denominator.

      References:

      - Continued Fraction equations (11) and (22)-(26)
      Parameters:
        `value` - the double value to convert to a fraction.
        `maxDenominator` - The maximum allowed value for denominator
      Throws:
        `FractionConversionException` - if the continued fraction failed to converge

    - #### Fraction

          private Fraction(double value,
                  double epsilon,
                  int maxDenominator,
                  int maxIterations)
                    throws FractionConversionException

      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 (re)used for both scenarios. However this could be confusing to users if it were part of the public API and this constructor should therefore remain PRIVATE.

      See JIRA issue ticket MATH-181 for more details: https://issues.apache.org/jira/browse/MATH-181
      Parameters:
        `value` - the double value to convert to a fraction.
        `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:
        `FractionConversionException` - if the continued fraction failed to converge.

    - #### Fraction

          public Fraction(int num)

      Create a fraction from an int. The fraction is num / 1.
      Parameters:
        `num` - the numerator.

    - #### Fraction

          public Fraction(int num,
                  int den)

      Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.
      Parameters:
        `num` - the numerator.
        `den` - the denominator.
      Throws:
        `MathArithmeticException` - if the denominator is `zero`

  - ### Method Detail

    - #### abs

          public Fraction abs()

      Returns the absolute value of this fraction.
      Returns:
        the absolute value.

    - #### compareTo

          public int compareTo(Fraction object)

      Compares this object to another based on size.
      Specified by:
        `compareTo` in interface `java.lang.Comparable<Fraction>`
      Parameters:
        `object` - the object to compare to
      Returns:
        -1 if this is less than `object`, +1 if this is greater than `object`, 0 if they are equal.

    - #### doubleValue

          public double doubleValue()

      Gets the fraction as a `double`. This calculates the fraction as the numerator divided by denominator.
      Specified by:
        `doubleValue` in class `java.lang.Number`
      Returns:
        the fraction as a `double`

    - #### equals

          public boolean equals(java.lang.Object other)

      Test for the equality of two fractions. If the lowest term numerator and denominators are the same for both fractions, the two fractions are considered to be equal.
      Overrides:
        `equals` in class `java.lang.Object`
      Parameters:
        `other` - fraction to test for equality to this fraction
      Returns:
        true if two fractions are equal, false if object is `null`, not an instance of `Fraction`, or not equal to this fraction instance.

    - #### floatValue

          public float floatValue()

      Gets the fraction as a `float`. This calculates the fraction as the numerator divided by denominator.
      Specified by:
        `floatValue` in class `java.lang.Number`
      Returns:
        the fraction as a `float`

    - #### getDenominator

          public int getDenominator()

      Access the denominator.
      Returns:
        the denominator.

    - #### getNumerator

          public int getNumerator()

      Access the numerator.
      Returns:
        the numerator.

    - #### hashCode

          public int hashCode()

      Gets a hashCode for the fraction.
      Overrides:
        `hashCode` in class `java.lang.Object`
      Returns:
        a hash code value for this object

    - #### intValue

          public int intValue()

      Gets the fraction as an `int`. This returns the whole number part of the fraction.
      Specified by:
        `intValue` in class `java.lang.Number`
      Returns:
        the whole number fraction part

    - #### longValue

          public long longValue()

      Gets the fraction as a `long`. This returns the whole number part of the fraction.
      Specified by:
        `longValue` in class `java.lang.Number`
      Returns:
        the whole number fraction part

    - #### negate

          public Fraction negate()

      Return the additive inverse of this fraction.
      Specified by:
        `negate` in interface `FieldElement<Fraction>`
      Returns:
        the negation of this fraction.

    - #### reciprocal

          public Fraction reciprocal()

      Return the multiplicative inverse of this fraction.
      Specified by:
        `reciprocal` in interface `FieldElement<Fraction>`
      Returns:
        the reciprocal fraction

    - #### add

          public Fraction add(Fraction fraction)

      Adds the value of this fraction to another, returning the result in reduced form. The algorithm follows Knuth, 4.5.1.

      Specified by:
        `add` in interface `FieldElement<Fraction>`
      Parameters:
        `fraction` - the fraction to add, must not be `null`
      Returns:
        a `Fraction` instance with the resulting values
      Throws:
        `NullArgumentException` - if the fraction is `null`
        `MathArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

    - #### add

          public Fraction add(int i)

      Add an integer to the fraction.
      Parameters:
        `i` - the `integer` to add.
      Returns:
        this + i

    - #### subtract

          public Fraction subtract(Fraction fraction)

      Subtracts the value of another fraction from the value of this one, returning the result in reduced form.

      Specified by:
        `subtract` in interface `FieldElement<Fraction>`
      Parameters:
        `fraction` - the fraction to subtract, must not be `null`
      Returns:
        a `Fraction` instance with the resulting values
      Throws:
        `NullArgumentException` - if the fraction is `null`
        `MathArithmeticException` - if the resulting numerator or denominator cannot be represented in an `int`.

    - #### subtract

          public Fraction subtract(int i)

      Subtract an integer from the fraction.
      Parameters:
        `i` - the `integer` to subtract.
      Returns:
        this - i

    - #### addSub

          private Fraction addSub(Fraction fraction,
                        boolean isAdd)

      Implement add and subtract using algorithm described in Knuth 4.5.1.
      Parameters:
        `fraction` - the fraction to subtract, must not be `null`
        `isAdd` - true to add, false to subtract
      Returns:
        a `Fraction` instance with the resulting values
      Throws:
        `NullArgumentException` - if the fraction is `null`
        `MathArithmeticException` - if the resulting numerator or denominator cannot be represented in an `int`.

    - #### multiply

          public Fraction multiply(Fraction fraction)

      Multiplies the value of this fraction by another, returning the result in reduced form.

      Specified by:
        `multiply` in interface `FieldElement<Fraction>`
      Parameters:
        `fraction` - the fraction to multiply by, must not be `null`
      Returns:
        a `Fraction` instance with the resulting values
      Throws:
        `NullArgumentException` - if the fraction is `null`
        `MathArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

    - #### multiply

          public Fraction multiply(int i)

      Multiply the fraction by an integer.
      Specified by:
        `multiply` in interface `FieldElement<Fraction>`
      Parameters:
        `i` - the `integer` to multiply by.
      Returns:
        this * i

    - #### divide

          public Fraction divide(Fraction fraction)

      Divide the value of this fraction by another.

      Specified by:
        `divide` in interface `FieldElement<Fraction>`
      Parameters:
        `fraction` - the fraction to divide by, must not be `null`
      Returns:
        a `Fraction` instance with the resulting values
      Throws:
        `java.lang.IllegalArgumentException` - if the fraction is `null`
        `MathArithmeticException` - if the fraction to divide by is zero
        `MathArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

    - #### divide

          public Fraction divide(int i)

      Divide the fraction by an integer.
      Parameters:
        `i` - the `integer` to divide by.
      Returns:
        this * i

    - #### percentageValue

          public double percentageValue()

      Gets the fraction percentage as a `double`. This calculates the fraction as the numerator divided by denominator multiplied by 100.

      Returns:
        the fraction percentage as a `double`.

    - #### getReducedFraction

          public static Fraction getReducedFraction(int numerator,
                                    int denominator)

      Creates a `Fraction` instance with the 2 parts of a fraction Y/Z.

      Any negative signs are resolved to be on the numerator.

      Parameters:
        `numerator` - the numerator, for example the three in 'three sevenths'
        `denominator` - the denominator, for example the seven in 'three sevenths'
      Returns:
        a new fraction instance, with the numerator and denominator reduced
      Throws:
        `MathArithmeticException` - if the denominator is `zero`

    - #### toString

          public java.lang.String toString()

      Returns the `String` representing this fraction, ie "num / dem" or just "num" if the denominator is one.

      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the fraction.
      See Also:
        `Object.toString()`

    - #### getField

          public FractionField getField()

      Get the `Field` to which the instance belongs.
      Specified by:
        `getField` in interface `FieldElement<Fraction>`
      Returns:
        `Field` to which the instance belongs

Copyright (c) 2003-2013 Apache Software Foundation