org.apache.commons.lang3.math

## Class Fraction

• All Implemented Interfaces:
Serializable, Comparable<Fraction>

```public final class Fraction
extends Number
implements 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
Modifier and Type Field and Description
`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
Modifier and Type Method and Description
`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(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(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.
`String` `toProperString()`
Gets the fraction as a proper `String` in the format X Y/Z.
`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:
`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:
`ArithmeticException` - if the denominator is `zero`
`ArithmeticException` - if the denominator is negative
`ArithmeticException` - if the numerator is negative
`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:
`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:
`ArithmeticException` - if `|value| &gt; Integer.MAX_VALUE` or `value = NaN`
`ArithmeticException` - if the calculated denominator is `zero`
`ArithmeticException` - if the algorithm does not converge
• #### getFraction

`public static Fraction getFraction(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:
`NullPointerException` - if the string is `null`
`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 `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 `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 `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 `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:
`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:
`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:
`IllegalArgumentException` - if the fraction is `null`
`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:
`IllegalArgumentException` - if the fraction is `null`
`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:
`NullPointerException` - if the fraction is `null`
`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:
`NullPointerException` - if the fraction is `null`
`ArithmeticException` - if the fraction to divide by is zero
`ArithmeticException` - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`
• #### equals

`public boolean equals(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 `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 `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 `Comparable<Fraction>`
Parameters:
`other` - the object to compare to
Returns:
-1 if this is less, 0 if equal, +1 if greater
Throws:
`ClassCastException` - if the object is not a `Fraction`
`NullPointerException` - if the object is `null`
• #### toString

`public String toString()`

Gets the fraction as a `String`.

The format used is 'numerator/denominator' always.

Overrides:
`toString` in class `Object`
Returns:
a `String` form of the fraction
• #### toProperString

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

Copyright © 2001–2021 The Apache Software Foundation. All rights reserved.