Top Description Fields Constructors Methods
org.apache.commons.math3.fraction

public Class Fraction

extends Number
implements FieldElement<Fraction>, Comparable<Fraction>, Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable, java.lang.Comparable, org.apache.commons.math3.FieldElement
Imports
java.io.Serializable, java.math.BigInteger, org.apache.commons.math3.FieldElement, org.apache.commons.math3.exception.util.LocalizedFormats, org.apache.commons.math3.exception.MathArithmeticException, .NullArgumentException, org.apache.commons.math3.util.ArithmeticUtils, .FastMath
Representation of a rational number. implements Serializable since 2.0
Since
1.1

Field Summary

Modifier and TypeField and Description
private static final double
DEFAULT_EPSILON

The default epsilon used for convergence.

private final int
denominator

The denominator.

public static final Fraction
FOUR_FIFTHS

A fraction representing "4/5".

public static final Fraction
MINUS_ONE

A fraction representing "-1 / 1".

private final int
numerator

The numerator.

public static final Fraction
ONE

A fraction representing "1".

public static final Fraction
ONE_FIFTH

A fraction representing "1/5".

public static final Fraction
ONE_HALF

A fraction representing "1/2".

public static final Fraction
ONE_QUARTER

A fraction representing "1/4".

public static final Fraction
ONE_THIRD

A fraction representing "1/3".

private static final long
serialVersionUID

Hides java.lang.Number.serialVersionUID.

Serializable version identifier
public static final Fraction
THREE_FIFTHS

A fraction representing "3/5".

public static final Fraction
THREE_QUARTERS

A fraction representing "3/4".

public static final Fraction
TWO

A fraction representing "2 / 1".

public static final Fraction
TWO_FIFTHS

A fraction representing "2/5".

public static final Fraction
TWO_QUARTERS

A fraction representing "2/4".

public static final Fraction
TWO_THIRDS

A fraction representing "2/3".

public static final Fraction
ZERO

A fraction representing "0".

Constructor Summary

AccessConstructor and Description
public
Fraction(double
the double value to convert to a fraction.
value)

Create a fraction given the double value.

public
Fraction(double
the double value to convert to a fraction.
value, double
maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
epsilon, int
maximum number of convergents
maxIterations)

Create a fraction given the double value and maximum error allowed.

public
Fraction(double
the double value to convert to a fraction.
value, int
The maximum allowed value for denominator
maxDenominator)

Create a fraction given the double value and maximum denominator.

private
Fraction(double
the double value to convert to a fraction.
value, double
maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
epsilon, int
maximum denominator value allowed.
maxDenominator, int
maximum number of convergents
maxIterations)

Create a fraction given the double value and either the maximum error allowed or the maximum number of denominator digits.

public
Fraction(int
the numerator.
num)

Create a fraction from an int.

public
Fraction(int
the numerator.
num, int
the denominator.
den)

Create a fraction given the numerator and denominator.

Method Summary

Modifier and TypeMethod and Description
public Fraction

Returns:

the absolute value.
abs()

Returns the absolute value of this fraction.

public Fraction

Returns:

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

Implements org.apache.commons.math3.FieldElement.add.

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

public Fraction

Returns:

this + i
add(final int
the integer to add.
i)

Implements org.apache.commons.math3.FieldElement.add.

Add an integer to the fraction.

private Fraction

Returns:

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

Implement add and subtract using algorithm described in Knuth 4.5.1.

public int

Returns:

-1 if this is less than object, +1 if this is greater than object, 0 if they are equal.
compareTo(Fraction
the object to compare to
object)

Implements java.lang.Comparable.compareTo.

Compares this object to another based on size.

public Fraction

Returns:

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

Implements org.apache.commons.math3.FieldElement.divide.

Divide the value of this fraction by another.

public Fraction

Returns:

this * i
divide(final int
the integer to divide by.
i)

Implements org.apache.commons.math3.FieldElement.divide.

Divide the fraction by an integer.

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 two fractions are equal, false if object is null, not an instance of Fraction, or not equal to this fraction instance.
equals(Object
fraction to test for equality to this fraction
other)

Overrides java.lang.Object.equals.

Test for the equality of two fractions.

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

Access the denominator.

public FractionField
getField()

Implements org.apache.commons.math3.FieldElement.getField.

Get the Field to which the instance belongs.

public int

Returns:

the numerator.
getNumerator()

Access the numerator.

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 Fraction instance with the 2 parts of a fraction Y/Z.

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 long

Returns:

the whole number fraction part
longValue()

Implements abstract java.lang.Number.longValue.

Gets the fraction as a long.

public Fraction

Returns:

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

Implements org.apache.commons.math3.FieldElement.multiply.

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

public Fraction

Returns:

this * i
multiply(final int
the integer to multiply by.
i)

Implements org.apache.commons.math3.FieldElement.multiply, org.apache.commons.math3.FieldElement.multiply.

Multiply the fraction by an integer.

public Fraction

Returns:

the negation of this fraction.
negate()

Implements org.apache.commons.math3.FieldElement.negate.

Return the additive inverse of this fraction.

public double

Returns:

the fraction percentage as a double.
percentageValue()

Gets the fraction percentage as a double.

public Fraction

Returns:

the reciprocal fraction
reciprocal()

Implements org.apache.commons.math3.FieldElement.reciprocal.

Return the multiplicative inverse of this fraction.

public Fraction

Returns:

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

Implements org.apache.commons.math3.FieldElement.subtract.

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

public Fraction

Returns:

this - i
subtract(final int
the integer to subtract.
i)

Implements org.apache.commons.math3.FieldElement.subtract.

Subtract an integer from the fraction.

public String

Returns:

a string representation of the fraction.
toString()

Overrides java.lang.Object.toString.

Returns the String representing this fraction, ie "num / dem" or just "num" if the denominator is one.

Inherited from java.lang.Number:
byteValueshortValue

Field Detail

DEFAULT_EPSILONback to summary
private static final double DEFAULT_EPSILON

The default epsilon used for convergence.

denominatorback to summary
private final int denominator

The denominator.

FOUR_FIFTHSback to summary
public static final Fraction FOUR_FIFTHS

A fraction representing "4/5".

MINUS_ONEback to summary
public static final Fraction MINUS_ONE

A fraction representing "-1 / 1".

numeratorback to summary
private final int numerator

The numerator.

ONEback to summary
public static final Fraction ONE

A fraction representing "1".

ONE_FIFTHback to summary
public static final Fraction ONE_FIFTH

A fraction representing "1/5".

ONE_HALFback to summary
public static final Fraction ONE_HALF

A fraction representing "1/2".

ONE_QUARTERback to summary
public static final Fraction ONE_QUARTER

A fraction representing "1/4".

ONE_THIRDback to summary
public static final Fraction ONE_THIRD

A fraction representing "1/3".

serialVersionUIDback to summary
private static final long serialVersionUID

Hides java.lang.Number.serialVersionUID.

Serializable version identifier

THREE_FIFTHSback to summary
public static final Fraction THREE_FIFTHS

A fraction representing "3/5".

THREE_QUARTERSback to summary
public static final Fraction THREE_QUARTERS

A fraction representing "3/4".

TWOback to summary
public static final Fraction TWO

A fraction representing "2 / 1".

TWO_FIFTHSback to summary
public static final Fraction TWO_FIFTHS

A fraction representing "2/5".

TWO_QUARTERSback to summary
public static final Fraction TWO_QUARTERS

A fraction representing "2/4".

TWO_THIRDSback to summary
public static final Fraction TWO_THIRDS

A fraction representing "2/3".

ZEROback to summary
public static final Fraction ZERO

A fraction representing "0".

Constructor Detail

Fractionback to summary
public Fraction(double value) throws FractionConversionException

Create a fraction given the double value.

Parameters
value:double

the double value to convert to a fraction.

Exceptions
FractionConversionException:
if the continued fraction failed to converge.
Fractionback to summary
public Fraction(double value, double epsilon, int maxIterations) throws FractionConversionException

Create a fraction given the double value and maximum error allowed.

References:

Parameters
value:double

the double value to convert to a fraction.

epsilon:double

maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.

maxIterations:int

maximum number of convergents

Exceptions
FractionConversionException:
if the continued fraction failed to converge.
Fractionback to summary
public Fraction(double value, int maxDenominator) throws FractionConversionException

Create a fraction given the double value and maximum denominator.

References:

Parameters
value:double

the double value to convert to a fraction.

maxDenominator:int

The maximum allowed value for denominator

Exceptions
FractionConversionException:
if the continued fraction failed to converge
Fractionback to summary
private Fraction(double value, double epsilon, int maxDenominator, int maxIterations) throws FractionConversionException

Create a fraction given the double value and either the maximum error allowed or the maximum number of denominator digits.

Note

This constructor is called with EITHER - a valid epsilon value and the maxDenominator set to Integer.MAX_VALUE (that way the maxDenominator has no effect). OR - a valid maxDenominator value and the epsilon value set to zero (that way epsilon only has effect if there is an exact match before the maxDenominator value is reached).

It has been done this way so that the same code can be (re)used for both scenarios. However this could be confusing to users if it were part of the public API and this constructor should therefore remain PRIVATE.

See JIRA issue ticket MATH-181 for more details: https://issues.apache.org/jira/browse/MATH-181
Parameters
value:double

the double value to convert to a fraction.

epsilon:double

maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.

maxDenominator:int

maximum denominator value allowed.

maxIterations:int

maximum number of convergents

Exceptions
FractionConversionException:
if the continued fraction failed to converge.
Fractionback to summary
public Fraction(int num)

Create a fraction from an int. The fraction is num / 1.

Parameters
num:int

the numerator.

Fractionback to summary
public Fraction(int num, int den)

Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.

Parameters
num:int

the numerator.

den:int

the denominator.

Exceptions
MathArithmeticException:
if the denominator is zero

Method Detail

absback to summary
public Fraction abs()

Returns the absolute value of this fraction.

Returns:Fraction

the absolute value.

addback to summary
public Fraction add(Fraction fraction)

Implements org.apache.commons.math3.FieldElement.add.

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
NullArgumentException:
if the fraction is null
MathArithmeticException:
if the resulting numerator or denominator exceeds Integer.MAX_VALUE
addback to summary
public Fraction add(final int i)

Implements org.apache.commons.math3.FieldElement.add.

Add an integer to the fraction.

Parameters
i:int

the integer to add.

Returns:Fraction

this + i

addSubback to summary
private Fraction addSub(Fraction fraction, boolean isAdd)

Implement add and subtract using algorithm described in Knuth 4.5.1.

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
NullArgumentException:
if the fraction is null
MathArithmeticException:
if the resulting numerator or denominator cannot be represented in an int.
compareToback to summary
public int compareTo(Fraction object)

Implements java.lang.Comparable.compareTo.

Compares this object to another based on size.

Parameters
object:Fraction

the object to compare to

Returns:int

-1 if this is less than object, +1 if this is greater than object, 0 if they are equal.

divideback to summary
public Fraction divide(Fraction fraction)

Implements org.apache.commons.math3.FieldElement.divide.

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
IllegalArgumentException:
if the fraction is null
MathArithmeticException:
  • if the fraction to divide by is zero
  • if the resulting numerator or denominator exceeds Integer.MAX_VALUE
divideback to summary
public Fraction divide(final int i)

Implements org.apache.commons.math3.FieldElement.divide.

Divide the fraction by an integer.

Parameters
i:int

the integer to divide by.

Returns:Fraction

this * i

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

Overrides java.lang.Object.equals.

Test for the equality of two fractions. If the lowest term numerator and denominators are the same for both fractions, the two fractions are considered to be equal.

Parameters
other:Object

fraction to test for equality to this fraction

Returns:boolean

true if two fractions are equal, false if object is null, not an instance of Fraction, or not equal to this fraction instance.

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

Access the denominator.

Returns:int

the denominator.

getFieldback to summary
public FractionField getField()

Implements org.apache.commons.math3.FieldElement.getField.

Doc from org.apache.commons.math3.FieldElement.getField.

Get the Field to which the instance belongs.

Returns:FractionField

Field to which the instance belongs

getNumeratorback to summary
public int getNumerator()

Access the numerator.

Returns:int

the numerator.

getReducedFractionback to summary
public static Fraction getReducedFraction(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, with the numerator and denominator reduced

Exceptions
MathArithmeticException:
if the denominator is 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
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
multiplyback to summary
public Fraction multiply(Fraction fraction)

Implements org.apache.commons.math3.FieldElement.multiply.

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
NullArgumentException:
if the fraction is null
MathArithmeticException:
if the resulting numerator or denominator exceeds Integer.MAX_VALUE
multiplyback to summary
public Fraction multiply(final int i)

Implements org.apache.commons.math3.FieldElement.multiply, org.apache.commons.math3.FieldElement.multiply.

Multiply the fraction by an integer.

Parameters
i:int

the integer to multiply by.

Returns:Fraction

this * i

negateback to summary
public Fraction negate()

Implements org.apache.commons.math3.FieldElement.negate.

Return the additive inverse of this fraction.

Returns:Fraction

the negation of this fraction.

percentageValueback to summary
public double percentageValue()

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

Returns:double

the fraction percentage as a double.

reciprocalback to summary
public Fraction reciprocal()

Implements org.apache.commons.math3.FieldElement.reciprocal.

Return the multiplicative inverse of this fraction.

Returns:Fraction

the reciprocal fraction

subtractback to summary
public Fraction subtract(Fraction fraction)

Implements org.apache.commons.math3.FieldElement.subtract.

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
NullArgumentException:
if the fraction is null
MathArithmeticException:
if the resulting numerator or denominator cannot be represented in an int.
subtractback to summary
public Fraction subtract(final int i)

Implements org.apache.commons.math3.FieldElement.subtract.

Subtract an integer from the fraction.

Parameters
i:int

the integer to subtract.

Returns:Fraction

this - i

toStringback to summary
public String toString()

Overrides java.lang.Object.toString.

Returns the String representing this fraction, ie "num / dem" or just "num" if the denominator is one.

Returns:String

a string representation of the fraction.

Annotations
@Override
See Also
java.lang.Object#toString()