org.apache.commons.math.fraction
Class Fraction

java.lang.Object
  extended by java.lang.Number
      extended by org.apache.commons.math.fraction.Fraction
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<Fraction>, FieldElement<Fraction>

public class Fraction
extends java.lang.Number
implements FieldElement<Fraction>, java.lang.Comparable<Fraction>, java.io.Serializable

Representation of a rational number. implements Serializable since 2.0

Since:
1.1
Version:
$Revision: 990655 $ $Date: 2010-08-29 23:49:40 +0200 (dim. 29 août 2010) $
See Also:
Serialized Form

Field Summary
private  int denominator
          The denominator.
static Fraction FOUR_FIFTHS
          A fraction representing "4/5".
static Fraction MINUS_ONE
          A fraction representing "-1 / 1".
private  int numerator
          The numerator.
static Fraction ONE
          A fraction representing "1".
static Fraction ONE_FIFTH
          A fraction representing "1/5".
static Fraction ONE_HALF
          A fraction representing "1/2".
static Fraction ONE_QUARTER
          A fraction representing "1/4".
static Fraction ONE_THIRD
          A fraction representing "1/3".
private static long serialVersionUID
          Serializable version identifier
static Fraction THREE_FIFTHS
          A fraction representing "3/5".
static Fraction THREE_QUARTERS
          A fraction representing "3/4".
static Fraction TWO
          A fraction representing "2 / 1".
static Fraction TWO_FIFTHS
          A fraction representing "2/5".
static Fraction TWO_QUARTERS
          A fraction representing "2/4".
static Fraction TWO_THIRDS
          A fraction representing "2/3".
static Fraction ZERO
          A fraction representing "0".
 
Constructor Summary
  Fraction(double value)
          Create a fraction given the double value.
  Fraction(double value, double epsilon, int maxIterations)
          Create a fraction given the double value and maximum error allowed.
private Fraction(double value, double epsilon, int maxDenominator, int maxIterations)
          Create a fraction given the double value and either the maximum error allowed or the maximum number of denominator digits.
  Fraction(double value, int maxDenominator)
          Create a fraction given the double value and maximum denominator.
  Fraction(int num)
          Create a fraction from an int.
  Fraction(int num, int den)
          Create a fraction given the numerator and denominator.
 
Method Summary
 Fraction abs()
          Returns the absolute value of this fraction.
 Fraction add(Fraction fraction)
          Adds the value of this fraction to another, returning the result in reduced form.
 Fraction add(int i)
          Add an integer to the fraction.
private  Fraction addSub(Fraction fraction, boolean isAdd)
          Implement add and subtract using algorithm described in Knuth 4.5.1.
 int compareTo(Fraction object)
          Compares this object to another based on size.
 Fraction divide(Fraction fraction)
          Divide the value of this fraction by another.
 Fraction divide(int i)
          Divide the fraction by an integer.
 double doubleValue()
          Gets the fraction as a double.
 boolean equals(java.lang.Object other)
          Test for the equality of two fractions.
 float floatValue()
          Gets the fraction as a float.
 int getDenominator()
          Access the denominator.
 FractionField getField()
          Get the Field to which the instance belongs.
 int getNumerator()
          Access the numerator.
static Fraction getReducedFraction(int numerator, int denominator)
          Creates a 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.
 long longValue()
          Gets the fraction as a long.
 Fraction multiply(Fraction fraction)
          Multiplies the value of this fraction by another, returning the result in reduced form.
 Fraction multiply(int i)
          Multiply the fraction by an integer.
 Fraction negate()
          Return the additive inverse of this fraction.
 Fraction reciprocal()
          Return the multiplicative inverse of this fraction.
 Fraction subtract(Fraction fraction)
          Subtracts the value of another fraction from the value of this one, returning the result in reduced form.
 Fraction subtract(int i)
          Subtract an integer from the fraction.
 java.lang.String toString()
           Returns the String representing this fraction, ie "num / dem" or just "num" if the denominator is one.
 
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

TWO

public static final Fraction TWO
A fraction representing "2 / 1".


ONE

public static final Fraction ONE
A fraction representing "1".


ZERO

public static final Fraction ZERO
A fraction representing "0".


FOUR_FIFTHS

public static final Fraction FOUR_FIFTHS
A fraction representing "4/5".


ONE_FIFTH

public static final Fraction ONE_FIFTH
A fraction representing "1/5".


ONE_HALF

public static final Fraction ONE_HALF
A fraction representing "1/2".


ONE_QUARTER

public static final Fraction ONE_QUARTER
A fraction representing "1/4".


ONE_THIRD

public static final Fraction ONE_THIRD
A fraction representing "1/3".


THREE_FIFTHS

public static final Fraction THREE_FIFTHS
A fraction representing "3/5".


THREE_QUARTERS

public static final Fraction THREE_QUARTERS
A fraction representing "3/4".


TWO_FIFTHS

public static final Fraction TWO_FIFTHS
A fraction representing "2/5".


TWO_QUARTERS

public static final Fraction TWO_QUARTERS
A fraction representing "2/4".


TWO_THIRDS

public static final Fraction TWO_THIRDS
A fraction representing "2/3".


MINUS_ONE

public static final Fraction MINUS_ONE
A fraction representing "-1 / 1".


serialVersionUID

private static final long serialVersionUID
Serializable version identifier

See Also:
Constant Field Values

denominator

private final int denominator
The denominator.


numerator

private final int numerator
The numerator.

Constructor Detail

Fraction

public Fraction(double value)
         throws FractionConversionException
Create a fraction given the double value.

Parameters:
value - the double value to convert to a fraction.
Throws:
FractionConversionException - if the continued fraction failed to converge.

Fraction

public Fraction(double value,
                double epsilon,
                int maxIterations)
         throws FractionConversionException
Create a fraction given the double value and maximum error allowed.

References:

Parameters:
value - the double value to convert to a fraction.
epsilon - maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
maxIterations - maximum number of convergents
Throws:
FractionConversionException - if the continued fraction failed to converge.

Fraction

public Fraction(double value,
                int maxDenominator)
         throws FractionConversionException
Create a fraction given the double value and maximum denominator.

References:

Parameters:
value - the double value to convert to a fraction.
maxDenominator - The maximum allowed value for denominator
Throws:
FractionConversionException - if the continued fraction failed to converge

Fraction

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 - the double value to convert to a fraction.
epsilon - maximum error allowed. The resulting fraction is within epsilon of value, in absolute terms.
maxDenominator - maximum denominator value allowed.
maxIterations - maximum number of convergents
Throws:
FractionConversionException - if the continued fraction failed to converge.

Fraction

public Fraction(int num)
Create a fraction from an int. The fraction is num / 1.

Parameters:
num - the numerator.

Fraction

public Fraction(int num,
                int den)
Create a fraction given the numerator and denominator. The fraction is reduced to lowest terms.

Parameters:
num - the numerator.
den - the denominator.
Throws:
java.lang.ArithmeticException - if the denominator is zero
Method Detail

abs

public Fraction abs()
Returns the absolute value of this fraction.

Returns:
the absolute value.

compareTo

public int compareTo(Fraction object)
Compares this object to another based on size.

Specified by:
compareTo in interface java.lang.Comparable<Fraction>
Parameters:
object - the object to compare to
Returns:
-1 if this is less than object, +1 if this is greater than object, 0 if they are equal.

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 java.lang.Number
Returns:
the fraction as a double

equals

public boolean equals(java.lang.Object other)
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.

Overrides:
equals in class java.lang.Object
Parameters:
other - fraction to test for equality to this fraction
Returns:
true if two fractions are equal, false if object is null, not an instance of Fraction, or not equal to this fraction instance.

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 java.lang.Number
Returns:
the fraction as a float

getDenominator

public int getDenominator()
Access the denominator.

Returns:
the denominator.

getNumerator

public int getNumerator()
Access the numerator.

Returns:
the numerator.

hashCode

public int hashCode()
Gets a hashCode for the fraction.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this object

intValue

public int intValue()
Gets the fraction as an int. This returns the whole number part of the fraction.

Specified by:
intValue in class java.lang.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 java.lang.Number
Returns:
the whole number fraction part

negate

public Fraction negate()
Return the additive inverse of this fraction.

Returns:
the negation of this fraction.

reciprocal

public Fraction reciprocal()
Return the multiplicative inverse of this fraction.

Returns:
the reciprocal fraction

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.

Specified by:
add in interface FieldElement<Fraction>
Parameters:
fraction - the fraction to add, must not be null
Returns:
a Fraction instance with the resulting values
Throws:
java.lang.IllegalArgumentException - if the fraction is null
java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE

add

public Fraction add(int i)
Add an integer to the fraction.

Parameters:
i - the integer to add.
Returns:
this + i

subtract

public Fraction subtract(Fraction fraction)

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

Specified by:
subtract in interface FieldElement<Fraction>
Parameters:
fraction - the fraction to subtract, must not be null
Returns:
a Fraction instance with the resulting values
Throws:
java.lang.IllegalArgumentException - if the fraction is null
java.lang.ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

subtract

public Fraction subtract(int i)
Subtract an integer from the fraction.

Parameters:
i - the integer to subtract.
Returns:
this - i

addSub

private Fraction addSub(Fraction fraction,
                        boolean isAdd)
Implement add and subtract using algorithm described in Knuth 4.5.1.

Parameters:
fraction - the fraction to subtract, must not be null
isAdd - true to add, false to subtract
Returns:
a Fraction instance with the resulting values
Throws:
java.lang.IllegalArgumentException - if the fraction is null
java.lang.ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.

multiply

public Fraction multiply(Fraction fraction)

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

Specified by:
multiply in interface FieldElement<Fraction>
Parameters:
fraction - the fraction to multiply by, must not be null
Returns:
a Fraction instance with the resulting values
Throws:
java.lang.IllegalArgumentException - if the fraction is null
java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE

multiply

public Fraction multiply(int i)
Multiply the fraction by an integer.

Parameters:
i - the integer to multiply by.
Returns:
this * i

divide

public Fraction divide(Fraction fraction)

Divide the value of this fraction by another.

Specified by:
divide in interface FieldElement<Fraction>
Parameters:
fraction - the fraction to divide by, must not be null
Returns:
a Fraction instance with the resulting values
Throws:
java.lang.IllegalArgumentException - if the fraction is null
java.lang.ArithmeticException - if the fraction to divide by is zero
java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE

divide

public Fraction divide(int i)
Divide the fraction by an integer.

Parameters:
i - the integer to divide by.
Returns:
this * i

getReducedFraction

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 - 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 - if the denominator is zero

toString

public java.lang.String toString()

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

Overrides:
toString in class java.lang.Object
Returns:
a string representation of the fraction.
See Also:
Object.toString()

getField

public FractionField getField()
Get the Field to which the instance belongs.

Specified by:
getField in interface FieldElement<Fraction>
Returns:
Field to which the instance belongs


Copyright (c) 2003-2011 Apache Software Foundation