Package org.apache.commons.lang3.math

## Class Fraction

- java.lang.Object
- - java.lang.Number
  - - org.apache.commons.lang3.math.Fraction

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

    public final class Fraction
    extends java.lang.Number
    implements java.lang.Comparable<Fraction>

`Fraction` is a `Number` implementation that stores fractions accurately.

This class is immutable, and interoperable with most methods that accept a `Number`.

Note that this class is intended for common use cases, it is int based and thus suffers from various overflow issues. For a BigInteger based equivalent, please see the Commons Math BigFraction class.

Since:
  2.0
See Also:
  Serialized Form

### Field Summary

Fields
`static Fraction` `FOUR_FIFTHS` `Fraction` representation of 4/5.
`static Fraction` `ONE` `Fraction` representation of 1.
`static Fraction` `ONE_FIFTH` `Fraction` representation of 1/5.
`static Fraction` `ONE_HALF` `Fraction` representation of 1/2.
`static Fraction` `ONE_QUARTER` `Fraction` representation of 1/4.
`static Fraction` `ONE_THIRD` `Fraction` representation of 1/3.
`static Fraction` `THREE_FIFTHS` `Fraction` representation of 3/5.
`static Fraction` `THREE_QUARTERS` `Fraction` representation of 3/4.
`static Fraction` `TWO_FIFTHS` `Fraction` representation of 2/5.
`static Fraction` `TWO_QUARTERS` `Fraction` representation of 2/4.
`static Fraction` `TWO_THIRDS` `Fraction` representation of 2/3.
`static Fraction` `ZERO` `Fraction` representation of 0.

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`Fraction` `abs()` Gets a fraction that is the positive equivalent of this one.
`Fraction` `add​(Fraction fraction)` Adds the value of this fraction to another, returning the result in reduced form.
`int` `compareTo​(Fraction other)` Compares this object to another based on size.
`Fraction` `divideBy​(Fraction fraction)` Divide the value of this fraction by another.
`double` `doubleValue()` Gets the fraction as a `double`.
`boolean` `equals​(java.lang.Object obj)` Compares this fraction to another object to test if they are equal.
`float` `floatValue()` Gets the fraction as a `float`.
`int` `getDenominator()` Gets the denominator part of the fraction.
`static Fraction` `getFraction​(double value)` Creates a `Fraction` instance from a `double` value.
`static Fraction` `getFraction​(int numerator, int denominator)` Creates a `Fraction` instance with the 2 parts of a fraction Y/Z.
`static Fraction` `getFraction​(int whole, int numerator, int denominator)` Creates a `Fraction` instance with the 3 parts of a fraction X Y/Z.
`static Fraction` `getFraction​(java.lang.String str)` Creates a Fraction from a `String`.
`int` `getNumerator()` Gets the numerator part of the fraction.
`int` `getProperNumerator()` Gets the proper numerator, always positive.
`int` `getProperWhole()` Gets the proper whole part of the fraction.
`static Fraction` `getReducedFraction​(int numerator, int denominator)` Creates a reduced `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`.
`Fraction` `invert()` Gets a fraction that is the inverse (1/fraction) of this one.
`long` `longValue()` Gets the fraction as a `long`.
`Fraction` `multiplyBy​(Fraction fraction)` Multiplies the value of this fraction by another, returning the result in reduced form.
`Fraction` `negate()` Gets a fraction that is the negative (-fraction) of this one.
`Fraction` `pow​(int power)` Gets a fraction that is raised to the passed in power.
`Fraction` `reduce()` Reduce the fraction to the smallest values for the numerator and denominator, returning the result.
`Fraction` `subtract​(Fraction fraction)` Subtracts the value of another fraction from the value of this one, returning the result in reduced form.
`java.lang.String` `toProperString()` Gets the fraction as a proper `String` in the format X Y/Z.
`java.lang.String` `toString()` Gets the fraction as a `String`.

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

`Fraction` representation of 0.

#### ONE

    public static final Fraction ONE

`Fraction` representation of 1.

#### ONE_HALF

    public static final Fraction ONE_HALF

`Fraction` representation of 1/2.

#### ONE_THIRD

    public static final Fraction ONE_THIRD

`Fraction` representation of 1/3.

#### TWO_THIRDS

    public static final Fraction TWO_THIRDS

`Fraction` representation of 2/3.

#### ONE_QUARTER

    public static final Fraction ONE_QUARTER

`Fraction` representation of 1/4.

#### TWO_QUARTERS

    public static final Fraction TWO_QUARTERS

`Fraction` representation of 2/4.

#### THREE_QUARTERS

    public static final Fraction THREE_QUARTERS

`Fraction` representation of 3/4.

#### ONE_FIFTH

    public static final Fraction ONE_FIFTH

`Fraction` representation of 1/5.

#### TWO_FIFTHS

    public static final Fraction TWO_FIFTHS

`Fraction` representation of 2/5.

#### THREE_FIFTHS

    public static final Fraction THREE_FIFTHS

`Fraction` representation of 3/5.

#### FOUR_FIFTHS

    public static final Fraction FOUR_FIFTHS

`Fraction` representation of 4/5.

### Method Detail

#### getFraction

    public static Fraction getFraction​(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
Throws:
  `java.lang.ArithmeticException` - if the denominator is `zero` or the denominator is `negative` and the numerator is `Integer#MIN_VALUE`

#### getFraction

    public static Fraction getFraction​(int whole,
                                       int numerator,
                                       int denominator)

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

The negative sign must be passed in on the whole number part.

Parameters:
  `whole` - the whole number, for example the one in 'one and three sevenths'
  `numerator` - the numerator, for example the three in 'one and three sevenths'
  `denominator` - the denominator, for example the seven in 'one and three sevenths'
Returns:
  a new fraction instance
Throws:
  `java.lang.ArithmeticException` - if the denominator is `zero`
  `java.lang.ArithmeticException` - if the denominator is negative
  `java.lang.ArithmeticException` - if the numerator is negative
  `java.lang.ArithmeticException` - if the resulting numerator exceeds `Integer.MAX_VALUE`

#### getReducedFraction

    public static Fraction getReducedFraction​(int numerator,
                                              int denominator)

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

For example, if the input parameters represent 2/4, then the created fraction will be 1/2.

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:
  `java.lang.ArithmeticException` - if the denominator is `zero`

#### getFraction

    public static Fraction getFraction​(double value)

Creates a `Fraction` instance from a `double` value.

This method uses the continued fraction algorithm, computing a maximum of 25 convergents and bounding the denominator by 10,000.

Parameters:
  `value` - the double value to convert
Returns:
  a new fraction instance that is close to the value
Throws:
  `java.lang.ArithmeticException` - if `|value| &gt; Integer.MAX_VALUE` or `value = NaN`
  `java.lang.ArithmeticException` - if the calculated denominator is `zero`
  `java.lang.ArithmeticException` - if the algorithm does not converge

#### getFraction

    public static Fraction getFraction​(java.lang.String str)

Creates a Fraction from a `String`.

The formats accepted are:

1. `double` String containing a dot
2. 'X Y/Z'
3. 'Y/Z'
4. 'X' (a simple whole number)

and a .

Parameters:
  `str` - the string to parse, must not be `null`
Returns:
  the new `Fraction` instance
Throws:
  `java.lang.NullPointerException` - if the string is `null`
  `java.lang.NumberFormatException` - if the number format is invalid

#### getNumerator

    public int getNumerator()

Gets the numerator part of the fraction.

This method may return a value greater than the denominator, an improper fraction, such as the seven in 7/4.

Returns:
  the numerator fraction part

#### getDenominator

    public int getDenominator()

Gets the denominator part of the fraction.

Returns:
  the denominator fraction part

#### getProperNumerator

    public int getProperNumerator()

Gets the proper numerator, always positive.

An improper fraction 7/4 can be resolved into a proper one, 1 3/4. This method returns the 3 from the proper fraction.

If the fraction is negative such as -7/4, it can be resolved into -1 3/4, so this method returns the positive proper numerator, 3.

Returns:
  the numerator fraction part of a proper fraction, always positive

#### getProperWhole

    public int getProperWhole()

Gets the proper whole part of the fraction.

An improper fraction 7/4 can be resolved into a proper one, 1 3/4. This method returns the 1 from the proper fraction.

If the fraction is negative such as -7/4, it can be resolved into -1 3/4, so this method returns the positive whole part -1.

Returns:
  the whole fraction part of a proper fraction, that includes the sign

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

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

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

#### reduce

    public Fraction reduce()

Reduce the fraction to the smallest values for the numerator and denominator, returning the result.

For example, if this fraction represents 2/4, then the result will be 1/2.

Returns:
  a new reduced fraction instance, or this if no simplification possible

#### invert

    public Fraction invert()

Gets a fraction that is the inverse (1/fraction) of this one.

The returned fraction is not reduced.

Returns:
  a new fraction instance with the numerator and denominator inverted.
Throws:
  `java.lang.ArithmeticException` - if the fraction represents zero.

#### negate

    public Fraction negate()

Gets a fraction that is the negative (-fraction) of this one.

The returned fraction is not reduced.

Returns:
  a new fraction instance with the opposite signed numerator

#### abs

    public Fraction abs()

Gets a fraction that is the positive equivalent of this one.

More precisely: `(fraction &gt;= 0 ? this : -fraction)`

The returned fraction is not reduced.

Returns:
  `this` if it is positive, or a new positive fraction instance with the opposite signed numerator

#### pow

    public Fraction pow​(int power)

Gets a fraction that is raised to the passed in power.

The returned fraction is in reduced form.

Parameters:
  `power` - the power to raise the fraction to
Returns:
  `this` if the power is one, `ONE` if the power is zero (even if the fraction equals ZERO) or a new fraction instance raised to the appropriate power
Throws:
  `java.lang.ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

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

Parameters:
  `fraction` - the fraction to add, must not be `null`
Returns:
  a `Fraction` instance with the resulting values
Throws:
  `java.lang.IllegalArgumentException` - if the fraction is `null`
  `java.lang.ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

#### subtract

    public Fraction subtract​(Fraction fraction)

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

Parameters:
  `fraction` - the fraction to subtract, must not be `null`
Returns:
  a `Fraction` instance with the resulting values
Throws:
  `java.lang.IllegalArgumentException` - if the fraction is `null`
  `java.lang.ArithmeticException` - if the resulting numerator or denominator cannot be represented in an `int`.

#### multiplyBy

    public Fraction multiplyBy​(Fraction fraction)

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

Parameters:
  `fraction` - the fraction to multiply by, must not be `null`
Returns:
  a `Fraction` instance with the resulting values
Throws:
  `java.lang.NullPointerException` - if the fraction is `null`
  `java.lang.ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

#### divideBy

    public Fraction divideBy​(Fraction fraction)

Divide the value of this fraction by another.

Parameters:
  `fraction` - the fraction to divide by, must not be `null`
Returns:
  a `Fraction` instance with the resulting values
Throws:
  `java.lang.NullPointerException` - if the fraction is `null`
  `java.lang.ArithmeticException` - if the fraction to divide by is zero
  `java.lang.ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

#### equals

    public boolean equals​(java.lang.Object obj)

Compares this fraction to another object to test if they are equal.

.

To be equal, both values must be equal. Thus 2/4 is not equal to 1/2.

Overrides:
  `equals` in class `java.lang.Object`
Parameters:
  `obj` - the reference object with which to compare
Returns:
  `true` if this object is equal

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

#### compareTo

    public int compareTo​(Fraction other)

Compares this object to another based on size.

Note: this class has a natural ordering that is inconsistent with equals, because, for example, equals treats 1/2 and 2/4 as different, whereas compareTo treats them as equal.

Specified by:
  `compareTo` in interface `java.lang.Comparable<Fraction>`
Parameters:
  `other` - the object to compare to
Returns:
  -1 if this is less, 0 if equal, +1 if greater
Throws:
  `java.lang.ClassCastException` - if the object is not a `Fraction`
  `java.lang.NullPointerException` - if the object is `null`

#### toString

    public java.lang.String toString()

Gets the fraction as a `String`.

The format used is 'numerator/denominator' always.

Overrides:
  `toString` in class `java.lang.Object`
Returns:
  a `String` form of the fraction

#### toProperString

    public java.lang.String toProperString()

Gets the fraction as a proper `String` in the format X Y/Z.

The format used in 'wholeNumber numerator/denominator'. If the whole number is zero it will be omitted. If the numerator is zero, only the whole number is returned.

Returns:
  a `String` form of the fraction