Top Description Fields Constructors Methods
org.apache.commons.lang3.math

public final Class Fraction

extends Number
implements Comparable<Fraction>
Class Inheritance
All Implemented Interfaces
java.lang.Comparable
Imports
java.io.Serializable, java.math.BigInteger, java.util.Objects
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

Field Summary

Modifier and TypeField and Description
private final int
denominator

The denominator number part of the fraction (the seven in three sevenths).

public static final Fraction
FOUR_FIFTHS

Fraction representation of 4/5.

private transient int
hashCode

Cached output hashCode (class is immutable).

private final int
numerator

The numerator number part of the fraction (the three in three sevenths).

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.

private static final long
serialVersionUID

Hides java.lang.Number.serialVersionUID.

Required for serialization support.
public static final Fraction
THREE_FIFTHS

Fraction representation of 3/5.

public static final Fraction
THREE_QUARTERS

Fraction representation of 3/4.

private transient String
toProperString

Cached output toProperString (class is immutable).

private transient String
toString

Cached output toString (class is immutable).

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.

Constructor Summary

AccessConstructor and Description
private
Fraction(final int
the numerator, for example the three in 'three sevenths'
numerator, final int
the denominator, for example the seven in 'three sevenths'
denominator)

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

Method Summary

Modifier and TypeMethod and Description
public Fraction

Returns:

this if it is positive, or a new positive fraction instance with the opposite signed numerator
abs()

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

public Fraction

Returns:

a Fraction instance with the resulting values
add(final Fraction
the fraction to add, must not be null
fraction)

Adds the value of this fraction to another, returning the result in reduced form.

private static int

Returns:

the sum x+y
addAndCheck(final int
an addend
x, final int
an addend
y)

Adds two integers, checking for overflow.

private Fraction

Returns:

a Fraction instance with the resulting values
addSub(final Fraction
the fraction to subtract, must not be null
fraction, final boolean
true to add, false to subtract
isAdd)

Implements add and subtract using the algorithm described in The Art of Computer Programming (TAOCP) 4.5.1 by Donald Knuth.

public int

Returns:

-1 if this is less, 0 if equal, +1 if greater
compareTo(final Fraction
the object to compare to
other)

Implements java.lang.Comparable.compareTo.

Compares this object to another based on size.

public Fraction

Returns:

a Fraction instance with the resulting values
divideBy(final Fraction
the fraction to divide by, must not be null
fraction)

Divide the value of this fraction by another.

public double

Returns:

the fraction as a double
doubleValue()

Implements abstract java.lang.Number.doubleValue.

Gets the fraction as a double.

public boolean

Returns:

true if this object is equal
equals(final Object
the reference object with which to compare
obj)

Overrides java.lang.Object.equals.

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

public float

Returns:

the fraction as a float
floatValue()

Implements abstract java.lang.Number.floatValue.

Gets the fraction as a float.

public int

Returns:

the denominator fraction part
getDenominator()

Gets the denominator part of the fraction.

public static Fraction

Returns:

a new fraction instance that is close to the value
getFraction(double
the double value to convert
value)

Creates a Fraction instance from a double value.

public static Fraction

Returns:

a new fraction instance
getFraction(int
the numerator, for example the three in 'three sevenths'
numerator, int
the denominator, for example the seven in 'three sevenths'
denominator)

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

public static Fraction

Returns:

a new fraction instance
getFraction(final int
the whole number, for example the one in 'one and three sevenths'
whole, final int
the numerator, for example the three in 'one and three sevenths'
numerator, final int
the denominator, for example the seven in 'one and three sevenths'
denominator)

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

public static Fraction

Returns:

the new Fraction instance
getFraction(String
the string to parse, must not be null
str)

Creates a Fraction from a String.

public int

Returns:

the numerator fraction part
getNumerator()

Gets the numerator part of the fraction.

public int

Returns:

the numerator fraction part of a proper fraction, always positive
getProperNumerator()

Gets the proper numerator, always positive.

public int

Returns:

the whole fraction part of a proper fraction, that includes the sign
getProperWhole()

Gets the proper whole part of the fraction.

public static Fraction

Returns:

a new fraction instance, with the numerator and denominator reduced
getReducedFraction(int
the numerator, for example the three in 'three sevenths'
numerator, int
the denominator, for example the seven in 'three sevenths'
denominator)

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

private static int

Returns:

the greatest common divisor, never zero
greatestCommonDivisor(int
a non-zero number
u, int
a non-zero number
v)

Gets the greatest common divisor of the absolute value of two numbers, using the "binary gcd" method which avoids division and modulo operations.

public int

Returns:

a hash code value for this object
hashCode()

Overrides java.lang.Object.hashCode.

Gets a hashCode for the fraction.

public int

Returns:

the whole number fraction part
intValue()

Implements abstract java.lang.Number.intValue.

Gets the fraction as an int.

public Fraction

Returns:

a new fraction instance with the numerator and denominator inverted.
invert()

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

public long

Returns:

the whole number fraction part
longValue()

Implements abstract java.lang.Number.longValue.

Gets the fraction as a long.

private static int

Returns:

the product x*y
mulAndCheck(final int
a factor
x, final int
a factor
y)

Multiplies two integers, checking for overflow.

private static int

Returns:

the product x*y
mulPosAndCheck(final int
a non-negative factor
x, final int
a non-negative factor
y)

Multiplies two non-negative integers, checking for overflow.

public Fraction

Returns:

a Fraction instance with the resulting values
multiplyBy(final Fraction
the fraction to multiply by, must not be null
fraction)

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

public Fraction

Returns:

a new fraction instance with the opposite signed numerator
negate()

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

public Fraction

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
pow(final int
the power to raise the fraction to
power)

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

public Fraction

Returns:

a new reduced fraction instance, or this if no simplification possible
reduce()

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

private static int

Returns:

the difference x-y
subAndCheck(final int
the minuend
x, final int
the subtrahend
y)

Subtracts two integers, checking for overflow.

public Fraction

Returns:

a Fraction instance with the resulting values
subtract(final Fraction
the fraction to subtract, must not be null
fraction)

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

public String

Returns:

a String form of the fraction
toProperString()

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

public String

Returns:

a String form of the fraction
toString()

Overrides java.lang.Object.toString.

Gets the fraction as a String.

Inherited from java.lang.Number:
byteValueshortValue

Field Detail

denominatorback to summary
private final int denominator

The denominator number part of the fraction (the seven in three sevenths).

FOUR_FIFTHSback to summary
public static final Fraction FOUR_FIFTHS

Fraction representation of 4/5.

hashCodeback to summary
private transient int hashCode

Cached output hashCode (class is immutable).

numeratorback to summary
private final int numerator

The numerator number part of the fraction (the three in three sevenths).

ONEback to summary
public static final Fraction ONE

Fraction representation of 1.

ONE_FIFTHback to summary
public static final Fraction ONE_FIFTH

Fraction representation of 1/5.

ONE_HALFback to summary
public static final Fraction ONE_HALF

Fraction representation of 1/2.

ONE_QUARTERback to summary
public static final Fraction ONE_QUARTER

Fraction representation of 1/4.

ONE_THIRDback to summary
public static final Fraction ONE_THIRD

Fraction representation of 1/3.

serialVersionUIDback to summary
private static final long serialVersionUID

Hides java.lang.Number.serialVersionUID.

Required for serialization support. Lang version 2.0.

See Also
Serializable
THREE_FIFTHSback to summary
public static final Fraction THREE_FIFTHS

Fraction representation of 3/5.

THREE_QUARTERSback to summary
public static final Fraction THREE_QUARTERS

Fraction representation of 3/4.

toProperStringback to summary
private transient String toProperString

Cached output toProperString (class is immutable).

toStringback to summary
private transient String toString

Cached output toString (class is immutable).

TWO_FIFTHSback to summary
public static final Fraction TWO_FIFTHS

Fraction representation of 2/5.

TWO_QUARTERSback to summary
public static final Fraction TWO_QUARTERS

Fraction representation of 2/4.

TWO_THIRDSback to summary
public static final Fraction TWO_THIRDS

Fraction representation of 2/3.

ZEROback to summary
public static final Fraction ZERO

Fraction representation of 0.

Constructor Detail

Fractionback to summary
private Fraction(final int numerator, final int denominator)

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

Parameters
numerator:int

the numerator, for example the three in 'three sevenths'

denominator:int

the denominator, for example the seven in 'three sevenths'

Method Detail

absback to summary
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:Fraction

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

addback to summary
public Fraction add(final 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:Fraction

the fraction to add, must not be null

Returns:Fraction

a Fraction instance with the resulting values

Exceptions
NullPointerException:
if the fraction is null
ArithmeticException:
if the resulting numerator or denominator exceeds Integer.MAX_VALUE
addAndCheckback to summary
private static int addAndCheck(final int x, final int y)

Adds two integers, checking for overflow.

Parameters
x:int

an addend

y:int

an addend

Returns:int

the sum x+y

Exceptions
ArithmeticException:
if the result cannot be represented as an int
addSubback to summary
private Fraction addSub(final Fraction fraction, final boolean isAdd)

Implements add and subtract using the algorithm described in The Art of Computer Programming (TAOCP) 4.5.1 by Donald Knuth.

Parameters
fraction:Fraction

the fraction to subtract, must not be null

isAdd:boolean

true to add, false to subtract

Returns:Fraction

a Fraction instance with the resulting values

Exceptions
IllegalArgumentException:
if the fraction is null
ArithmeticException:
if the resulting numerator or denominator cannot be represented in an int.
compareToback to summary
public int compareTo(final Fraction other)

Implements java.lang.Comparable.compareTo.

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:Fraction

the object to compare to

Returns:int

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

Annotations
@Override
Exceptions
ClassCastException:
if the object is not a Fraction
NullPointerException:
if the object is null
divideByback to summary
public Fraction divideBy(final Fraction fraction)

Divide the value of this fraction by another.

Parameters
fraction:Fraction

the fraction to divide by, must not be null

Returns:Fraction

a Fraction instance with the resulting values

Exceptions
NullPointerException:
if the fraction is null
ArithmeticException:
  • if the fraction to divide by is zero
  • if the resulting numerator or denominator exceeds Integer.MAX_VALUE
doubleValueback to summary
public double doubleValue()

Implements abstract java.lang.Number.doubleValue.

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

Returns:double

the fraction as a double

Annotations
@Override
equalsback to summary
public boolean equals(final Object obj)

Overrides java.lang.Object.equals.

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:Object

the reference object with which to compare

Returns:boolean

true if this object is equal

Annotations
@Override
floatValueback to summary
public float floatValue()

Implements abstract java.lang.Number.floatValue.

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

Returns:float

the fraction as a float

Annotations
@Override
getDenominatorback to summary
public int getDenominator()

Gets the denominator part of the fraction.

Returns:int

the denominator fraction part

getFractionback to summary
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:double

the double value to convert

Returns:Fraction

a new fraction instance that is close to the value

Exceptions
ArithmeticException:
  • if |value| > Integer.MAX_VALUE or value = NaN
  • if the calculated denominator is zero
  • if the algorithm does not converge
getFractionback to summary
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:int

the numerator, for example the three in 'three sevenths'

denominator:int

the denominator, for example the seven in 'three sevenths'

Returns:Fraction

a new fraction instance

Exceptions
ArithmeticException:
if the denominator is zero or the denominator is negative and the numerator is Integer#MIN_VALUE
getFractionback to summary
public static Fraction getFraction(final int whole, final int numerator, final 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:int

the whole number, for example the one in 'one and three sevenths'

numerator:int

the numerator, for example the three in 'one and three sevenths'

denominator:int

the denominator, for example the seven in 'one and three sevenths'

Returns:Fraction

a new fraction instance

Exceptions
ArithmeticException:
  • if the denominator is zero
  • if the denominator is negative
  • if the numerator is negative
  • if the resulting numerator exceeds Integer.MAX_VALUE
getFractionback to summary
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:String

the string to parse, must not be null

Returns:Fraction

the new Fraction instance

Exceptions
NullPointerException:
if the string is null
NumberFormatException:
if the number format is invalid
getNumeratorback to summary
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:int

the numerator fraction part

getProperNumeratorback to summary
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:int

the numerator fraction part of a proper fraction, always positive

getProperWholeback to summary
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:int

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

getReducedFractionback to summary
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:int

the numerator, for example the three in 'three sevenths'

denominator:int

the denominator, for example the seven in 'three sevenths'

Returns:Fraction

a new fraction instance, with the numerator and denominator reduced

Exceptions
ArithmeticException:
if the denominator is zero
greatestCommonDivisorback to summary
private static int greatestCommonDivisor(int u, int v)

Gets the greatest common divisor of the absolute value of two numbers, using the "binary gcd" method which avoids division and modulo operations. See Knuth 4.5.2 algorithm B. This algorithm is due to Josef Stein (1961).

Parameters
u:int

a non-zero number

v:int

a non-zero number

Returns:int

the greatest common divisor, never zero

hashCodeback to summary
public int hashCode()

Overrides java.lang.Object.hashCode.

Gets a hashCode for the fraction.

Returns:int

a hash code value for this object

Annotations
@Override
intValueback to summary
public int intValue()

Implements abstract java.lang.Number.intValue.

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

Returns:int

the whole number fraction part

Annotations
@Override
invertback to summary
public Fraction invert()

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

The returned fraction is not reduced.

Returns:Fraction

a new fraction instance with the numerator and denominator inverted.

Exceptions
ArithmeticException:
if the fraction represents zero.
longValueback to summary
public long longValue()

Implements abstract java.lang.Number.longValue.

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

Returns:long

the whole number fraction part

Annotations
@Override
mulAndCheckback to summary
private static int mulAndCheck(final int x, final int y)

Multiplies two integers, checking for overflow.

Parameters
x:int

a factor

y:int

a factor

Returns:int

the product x*y

Exceptions
ArithmeticException:
if the result cannot be represented as an int
mulPosAndCheckback to summary
private static int mulPosAndCheck(final int x, final int y)

Multiplies two non-negative integers, checking for overflow.

Parameters
x:int

a non-negative factor

y:int

a non-negative factor

Returns:int

the product x*y

Exceptions
ArithmeticException:
if the result cannot be represented as an int
multiplyByback to summary
public Fraction multiplyBy(final Fraction fraction)

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

Parameters
fraction:Fraction

the fraction to multiply by, must not be null

Returns:Fraction

a Fraction instance with the resulting values

Exceptions
NullPointerException:
if the fraction is null
ArithmeticException:
if the resulting numerator or denominator exceeds Integer.MAX_VALUE
negateback to summary
public Fraction negate()

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

The returned fraction is not reduced.

Returns:Fraction

a new fraction instance with the opposite signed numerator

powback to summary
public Fraction pow(final int power)

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

The returned fraction is in reduced form.

Parameters
power:int

the power to raise the fraction to

Returns:Fraction

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

Exceptions
ArithmeticException:
if the resulting numerator or denominator exceeds Integer.MAX_VALUE
reduceback to summary
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:Fraction

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

subAndCheckback to summary
private static int subAndCheck(final int x, final int y)

Subtracts two integers, checking for overflow.

Parameters
x:int

the minuend

y:int

the subtrahend

Returns:int

the difference x-y

Exceptions
ArithmeticException:
if the result cannot be represented as an int
subtractback to summary
public Fraction subtract(final Fraction fraction)

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

Parameters
fraction:Fraction

the fraction to subtract, must not be null

Returns:Fraction

a Fraction instance with the resulting values

Exceptions
NullPointerException:
if the fraction is null
ArithmeticException:
if the resulting numerator or denominator cannot be represented in an int.
toProperStringback to summary
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:String

a String form of the fraction

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Gets the fraction as a String.

The format used is 'numerator/denominator' always.

Returns:String

a String form of the fraction

Annotations
@Override