Fraction

public final class org.apache.commons.lang3.math.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

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

Fraction representation of 4/5.

public static final Fraction ONE

Fraction representation of 1.

public static final Fraction ONE_FIFTH

Fraction representation of 1/5.

public static final Fraction ONE_HALF

Fraction representation of 1/2.

public static final Fraction ONE_QUARTER

Fraction representation of 1/4.

public static final Fraction ONE_THIRD

Fraction representation of 1/3.

public static final Fraction THREE_FIFTHS

Fraction representation of 3/5.

public static final Fraction THREE_QUARTERS

Fraction representation of 3/4.

public static final Fraction TWO_FIFTHS

Fraction representation of 2/5.

public static final Fraction TWO_QUARTERS

Fraction representation of 2/4.

public static final Fraction TWO_THIRDS

Fraction representation of 2/3.

public static final Fraction ZERO

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()

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)

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)

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)

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()

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)

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()

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()

Gets the denominator part of the fraction.

Returns:

The denominator fraction part

public static Fraction getFraction(double value)

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)

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)

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)

Gets 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 – 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()

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()

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()

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)

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()

Gets a hashCode for the fraction.

Returns:

A hash code value for this object

@Override public int intValue()

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

Returns:

The whole number fraction part

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

@Override public long longValue()

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)

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()

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)

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()

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)

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()

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()

Gets the fraction as a String.

The format used is ‘numerator/denominator’ always.

Returns:

A String form of the fraction