Fraction¶

public final class org.apache.commons.lang3.math.Fraction extends Number implements Comparable<Fraction>[source]¶

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

Fields and constants¶

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

public static final Fraction FOUR_FIFTHS[source]¶: Fraction representation of 4/5.

public static final Fraction ONE[source]¶: Fraction representation of 1.

public static final Fraction ONE_FIFTH[source]¶: Fraction representation of 1/5.

public static final Fraction ONE_HALF[source]¶: Fraction representation of 1/2.

public static final Fraction ONE_QUARTER[source]¶: Fraction representation of 1/4.

public static final Fraction ONE_THIRD[source]¶: Fraction representation of 1/3.

public static final Fraction THREE_FIFTHS[source]¶: Fraction representation of 3/5.

public static final Fraction THREE_QUARTERS[source]¶: Fraction representation of 3/4.

public static final Fraction TWO_FIFTHS[source]¶: Fraction representation of 2/5.

public static final Fraction TWO_QUARTERS[source]¶: Fraction representation of 2/4.

public static final Fraction TWO_THIRDS[source]¶: Fraction representation of 2/3.

public static final Fraction ZERO[source]¶: Fraction representation of 0.

Methods¶

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

public Fraction abs()[source]¶

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

More precisely: (fraction >= 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

public Fraction add(Fraction fraction)[source]¶

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.NullPointerException – Thrown if the fraction is null.
java.lang.ArithmeticException – Thrown if the resulting numerator or denominator exceeds Integer.MAX_VALUE.

@Override public int compareTo(Fraction other)[source]¶

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.

Parameters:

other – The object to compare to

Returns:

-1 if this is less, 0 if equal, +1 if greater

Throws:

java.lang.ClassCastException – Thrown if the object is not a Fraction.
java.lang.NullPointerException – Thrown if the object is null.

public Fraction divideBy(Fraction fraction)[source]¶

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 – Thrown if the fraction is null.
java.lang.ArithmeticException – Thrown if the fraction to divide by is zero.

Thrown if the resulting numerator or denominator exceeds Integer.MAX_VALUE.

@Override public double doubleValue()[source]¶

Gets the fraction as a double. This calculates the fraction as the numerator divided by denominator.

Returns:: The fraction as a double

@Override public boolean equals(Object obj)[source]¶

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.

Parameters:: obj – The reference object with which to compare
Returns:: true if this object is equal

@Override public float floatValue()[source]¶

Gets the fraction as a float. This calculates the fraction as the numerator divided by denominator.

Returns:: The fraction as a float

public int getDenominator()[source]¶

Gets the denominator part of the fraction.

Returns:: The denominator fraction part

public static Fraction getFraction(double value)[source]¶

Gets 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 – Thrown if |value| > Integer.MAX_VALUE or value = NaN.

Thrown if the calculated denominator is zero.

Thrown if the algorithm does not converge.

public static Fraction getFraction(int numerator, int denominator)[source]¶

Gets 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 – Thrown if the denominator is zero or the denominator is negative and the numerator is Integer#MIN_VALUE.

public static Fraction getFraction(int whole, int numerator, int denominator)[source]¶

Gets 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 – Thrown if the denominator is zero.

Thrown if the denominator is negative.

Thrown if the numerator is negative.

Thrown if the resulting numerator exceeds Integer.MAX_VALUE.

public static Fraction getFraction(String str)[source]¶

Gets a Fraction from a String.

The formats accepted are:

double String containing a dot
"X Y/Z"
"Y/Z"
"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 – Thrown if the string is null
java.lang.NumberFormatException – Thrown if the number format is invalid, or if the string is well-formed but its value cannot be represented as a Fraction: a zero denominator such as "1/0", a value outside the range of an int such as "9999999999.5", or a mixed number whose combined numerator overflows. For those unrepresentable values, the causal ArithmeticException is preserved as the cause.

public int getNumerator()[source]¶

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

public int getProperNumerator()[source]¶

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

public int getProperWhole()[source]¶

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

public static Fraction getReducedFraction(int numerator, int denominator)[source]¶

Gets 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 – Thrown if the denominator is zero, or the reduced numerator or positive denominator cannot be represented as an int.

@Override public int hashCode()[source]¶

Gets a hashCode for the fraction.

Returns:: A hash code value for this object

@Override public int intValue()[source]¶

Gets the fraction as an int. This returns the whole number part of the fraction.

Returns:: The whole number fraction part

public Fraction invert()[source]¶

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 – Thrown if the fraction represents zero.

@Override public long longValue()[source]¶

Gets the fraction as a long. This returns the whole number part of the fraction.

Returns:: The whole number fraction part

public Fraction multiplyBy(Fraction fraction)[source]¶

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 – Thrown if the fraction is null.
java.lang.ArithmeticException – Thrown if the resulting numerator or denominator exceeds Integer.MAX_VALUE.

public Fraction negate()[source]¶

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

public Fraction pow(int power)[source]¶

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 – Thrown if the resulting numerator or denominator exceeds Integer.MAX_VALUE.

public Fraction reduce()[source]¶

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

public Fraction subtract(Fraction fraction)[source]¶

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.NullPointerException – Thrown if the fraction is null.
java.lang.ArithmeticException – Thrown if the resulting numerator or denominator cannot be represented in an int.

public String toProperString()[source]¶

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

@Override public String toString()[source]¶

Gets the fraction as a String.

The format used is ‘numerator/denominator’ always.

Returns:: A String form of the fraction