org.apache.commons.math.fraction
Class BigFraction

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

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

Representation of a rational number without any overflow. This class is immutable.

Since:
2.0
Version:
$Revision: 795900 $ $Date: 2009-07-20 12:27:45 -0400 (Mon, 20 Jul 2009) $
See Also:
Serialized Form

Field Summary
private  java.math.BigInteger denominator
          The denominator.
static BigFraction FOUR_FIFTHS
          A fraction representing "4/5".
static BigFraction MINUS_ONE
          A fraction representing "-1 / 1".
private  java.math.BigInteger numerator
          The numerator.
static BigFraction ONE
          A fraction representing "1".
static BigFraction ONE_FIFTH
          A fraction representing "1/5".
static BigFraction ONE_HALF
          A fraction representing "1/2".
private static java.math.BigInteger ONE_HUNDRED_DOUBLE
          BigInteger representation of 100.
static BigFraction ONE_QUARTER
          A fraction representing "1/4".
static BigFraction ONE_THIRD
          A fraction representing "1/3".
private static long serialVersionUID
          Serializable version identifier.
static BigFraction THREE_FIFTHS
          A fraction representing "3/5".
static BigFraction THREE_QUARTERS
          A fraction representing "3/4".
static BigFraction TWO
          A fraction representing "2 / 1".
static BigFraction TWO_FIFTHS
          A fraction representing "2/5".
static BigFraction TWO_QUARTERS
          A fraction representing "2/4".
static BigFraction TWO_THIRDS
          A fraction representing "2/3".
static BigFraction ZERO
          A fraction representing "0".
 
Constructor Summary
  BigFraction(java.math.BigInteger num)
           Create a BigFraction equivalent to the passed BigInteger, ie "num / 1".
  BigFraction(java.math.BigInteger num, java.math.BigInteger den)
           Create a BigFraction given the numerator and denominator as BigInteger.
  BigFraction(double value)
          Create a fraction given the double value.
  BigFraction(double value, double epsilon, int maxIterations)
          Create a fraction given the double value and maximum error allowed.
private BigFraction(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.
  BigFraction(double value, int maxDenominator)
          Create a fraction given the double value and maximum denominator.
  BigFraction(int num)
           Create a BigFraction equivalent to the passed int, ie "num / 1".
  BigFraction(int num, int den)
           Create a BigFraction given the numerator and denominator as simple int.
  BigFraction(long num)
           Create a BigFraction equivalent to the passed long, ie "num / 1".
  BigFraction(long num, long den)
           Create a BigFraction given the numerator and denominator as simple long.
 
Method Summary
 BigFraction abs()
           Returns the absolute value of this BigFraction.
 BigFraction add(BigFraction fraction)
           Adds the value of this fraction to another, returning the result in reduced form.
 BigFraction add(java.math.BigInteger bg)
           Adds the value of this fraction to the passed BigInteger, returning the result in reduced form.
 BigFraction add(int i)
           Adds the value of this fraction to the passed integer, returning the result in reduced form.
 BigFraction add(long l)
           Adds the value of this fraction to the passed long, returning the result in reduced form.
 java.math.BigDecimal bigDecimalValue()
           Gets the fraction as a BigDecimal.
 java.math.BigDecimal bigDecimalValue(int roundingMode)
           Gets the fraction as a BigDecimal following the passed rounding mode.
 java.math.BigDecimal bigDecimalValue(int scale, int roundingMode)
           Gets the fraction as a BigDecimal following the passed scale and rounding mode.
 int compareTo(BigFraction object)
           Compares this object to another based on size.
 BigFraction divide(BigFraction fraction)
           Divide the value of this fraction by another, returning the result in reduced form.
 BigFraction divide(java.math.BigInteger bg)
           Divide the value of this fraction by the passed BigInteger, ie "this * 1 / bg", returning the result in reduced form.
 BigFraction divide(int i)
           Divide the value of this fraction by the passed int, ie "this * 1 / i", returning the result in reduced form.
 BigFraction divide(long l)
           Divide the value of this fraction by the passed long, ie "this * 1 / l", returning the result in reduced form.
 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.
 java.math.BigInteger getDenominator()
           Access the denominator as a BigInteger.
 int getDenominatorAsInt()
           Access the denominator as a int.
 long getDenominatorAsLong()
           Access the denominator as a long.
 BigFractionField getField()
          Get the Field to which the instance belongs.
 java.math.BigInteger getNumerator()
           Access the numerator as a BigInteger.
 int getNumeratorAsInt()
           Access the numerator as a int.
 long getNumeratorAsLong()
           Access the numerator as a long.
static BigFraction getReducedFraction(int numerator, int denominator)
           Creates a BigFraction 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.
 BigFraction multiply(BigFraction fraction)
           Multiplies the value of this fraction by another, returning the result in reduced form.
 BigFraction multiply(java.math.BigInteger bg)
           Multiplies the value of this fraction by the passed BigInteger, returning the result in reduced form.
 BigFraction multiply(int i)
           Multiply the value of this fraction by the passed int, returning the result in reduced form.
 BigFraction multiply(long l)
           Multiply the value of this fraction by the passed long, returning the result in reduced form.
 BigFraction negate()
           Return the additive inverse of this fraction, returning the result in reduced form.
 double percentageValue()
           Gets the fraction percentage as a double.
 BigFraction pow(java.math.BigInteger exponent)
           Returns a BigFraction whose value is (thisexponent), returning the result in reduced form.
 double pow(double exponent)
           Returns a double whose value is (thisexponent), returning the result in reduced form.
 BigFraction pow(int exponent)
           Returns a integer whose value is (thisexponent), returning the result in reduced form.
 BigFraction pow(long exponent)
           Returns a BigFraction whose value is (thisexponent), returning the result in reduced form.
 BigFraction reciprocal()
           Return the multiplicative inverse of this fraction.
 BigFraction reduce()
           Reduce this BigFraction to its lowest terms.
 BigFraction subtract(BigFraction fraction)
           Subtracts the value of another fraction from the value of this one, returning the result in reduced form.
 BigFraction subtract(java.math.BigInteger bg)
           Subtracts the value of an BigInteger from the value of this one, returning the result in reduced form.
 BigFraction subtract(int i)
           Subtracts the value of an integer from the value of this one, returning the result in reduced form.
 BigFraction subtract(long l)
           Subtracts the value of an integer from the value of this one, returning the result in reduced form.
 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 BigFraction TWO
A fraction representing "2 / 1".


ONE

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


ZERO

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


MINUS_ONE

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


FOUR_FIFTHS

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


ONE_FIFTH

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


ONE_HALF

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


ONE_QUARTER

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


ONE_THIRD

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


THREE_FIFTHS

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


THREE_QUARTERS

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


TWO_FIFTHS

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


TWO_QUARTERS

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


TWO_THIRDS

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


serialVersionUID

private static final long serialVersionUID
Serializable version identifier.

See Also:
Constant Field Values

ONE_HUNDRED_DOUBLE

private static final java.math.BigInteger ONE_HUNDRED_DOUBLE
BigInteger representation of 100.


numerator

private final java.math.BigInteger numerator
The numerator.


denominator

private final java.math.BigInteger denominator
The denominator.

Constructor Detail

BigFraction

public BigFraction(java.math.BigInteger num)

Create a BigFraction equivalent to the passed BigInteger, ie "num / 1".

Parameters:
num - the numerator.

BigFraction

public BigFraction(java.math.BigInteger num,
                   java.math.BigInteger den)

Create a BigFraction given the numerator and denominator as BigInteger. The BigFraction is reduced to lowest terms.

Parameters:
num - the numerator, must not be null.
den - the denominator, must not be null.
Throws:
java.lang.ArithmeticException - if the denominator is zero.
java.lang.NullPointerException - if the numerator or the denominator is zero.

BigFraction

public BigFraction(double value)
            throws java.lang.IllegalArgumentException
Create a fraction given the double value.

This constructor behaves differently from BigFraction(double, double, int). It converts the double value exactly, considering its internal bits representation. This does work for all values except NaN and infinities and does not requires any loop or convergence threshold.

Since this conversion is exact and since double numbers are sometimes approximated, the fraction created may seem strange in some cases. For example calling new BigFraction(1.0 / 3.0) does not create the fraction 1/3 but the fraction 6004799503160661 / 18014398509481984 because the double number passed to the constructor is not exactly 1/3 (this number cannot be stored exactly in IEEE754).

Parameters:
value - the double value to convert to a fraction.
Throws:
java.lang.IllegalArgumentException - if value is NaN or infinite
See Also:
BigFraction(double, double, int)

BigFraction

public BigFraction(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.
See Also:
BigFraction(double)

BigFraction

private BigFraction(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.

BigFraction

public BigFraction(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.

BigFraction

public BigFraction(int num)

Create a BigFraction equivalent to the passed int, ie "num / 1".

Parameters:
num - the numerator.

BigFraction

public BigFraction(int num,
                   int den)

Create a BigFraction given the numerator and denominator as simple int. The BigFraction is reduced to lowest terms.

Parameters:
num - the numerator.
den - the denominator.

BigFraction

public BigFraction(long num)

Create a BigFraction equivalent to the passed long, ie "num / 1".

Parameters:
num - the numerator.

BigFraction

public BigFraction(long num,
                   long den)

Create a BigFraction given the numerator and denominator as simple long. The BigFraction is reduced to lowest terms.

Parameters:
num - the numerator.
den - the denominator.
Method Detail

getReducedFraction

public static BigFraction getReducedFraction(int numerator,
                                             int denominator)

Creates a BigFraction 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.

abs

public BigFraction abs()

Returns the absolute value of this BigFraction.

Returns:
the absolute value as a BigFraction.

add

public BigFraction add(java.math.BigInteger bg)

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

Parameters:
bg - the BigInteger to add, must'nt be null.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.NullPointerException - if the BigInteger is null.

add

public BigFraction add(int i)

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

Parameters:
i - the integer to add.
Returns:
a BigFraction instance with the resulting values.

add

public BigFraction add(long l)

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

Parameters:
l - the long to add.
Returns:
a BigFraction instance with the resulting values.

add

public BigFraction add(BigFraction fraction)

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

Specified by:
add in interface FieldElement<BigFraction>
Parameters:
fraction - the BigFraction to add, must not be null.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.NullPointerException - if the BigFraction is null.

bigDecimalValue

public java.math.BigDecimal bigDecimalValue()

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

Returns:
the fraction as a BigDecimal.
Throws:
java.lang.ArithmeticException - if the exact quotient does not have a terminating decimal expansion.
See Also:
BigDecimal

bigDecimalValue

public java.math.BigDecimal bigDecimalValue(int roundingMode)

Gets the fraction as a BigDecimal following the passed rounding mode. This calculates the fraction as the numerator divided by denominator.

Parameters:
roundingMode - rounding mode to apply. see BigDecimal constants.
Returns:
the fraction as a BigDecimal.
Throws:
java.lang.IllegalArgumentException - if roundingMode does not represent a valid rounding mode.
See Also:
BigDecimal

bigDecimalValue

public java.math.BigDecimal bigDecimalValue(int scale,
                                            int roundingMode)

Gets the fraction as a BigDecimal following the passed scale and rounding mode. This calculates the fraction as the numerator divided by denominator.

Parameters:
scale - scale of the BigDecimal quotient to be returned. see BigDecimal for more information.
roundingMode - rounding mode to apply. see BigDecimal constants.
Returns:
the fraction as a BigDecimal.
See Also:
BigDecimal

compareTo

public int compareTo(BigFraction object)

Compares this object to another based on size.

Specified by:
compareTo in interface java.lang.Comparable<BigFraction>
Parameters:
object - the object to compare to, must not be null.
Returns:
-1 if this is less than object, +1 if this is greater than object, 0 if they are equal.
See Also:
Comparable.compareTo(java.lang.Object)

divide

public BigFraction divide(java.math.BigInteger bg)

Divide the value of this fraction by the passed BigInteger, ie "this * 1 / bg", returning the result in reduced form.

Parameters:
bg - the BigInteger to divide by, must not be null.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.NullPointerException - if the BigInteger is null.
java.lang.ArithmeticException - if the fraction to divide by is zero.

divide

public BigFraction divide(int i)

Divide the value of this fraction by the passed int, ie "this * 1 / i", returning the result in reduced form.

Parameters:
i - the int to divide by.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.ArithmeticException - if the fraction to divide by is zero.

divide

public BigFraction divide(long l)

Divide the value of this fraction by the passed long, ie "this * 1 / l", returning the result in reduced form.

Parameters:
l - the long to divide by.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.ArithmeticException - if the fraction to divide by is zero.

divide

public BigFraction divide(BigFraction fraction)

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

Specified by:
divide in interface FieldElement<BigFraction>
Parameters:
fraction - the fraction to divide by, must not be null.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.NullPointerException - if the fraction is null.
java.lang.ArithmeticException - if the fraction to divide by is zero.

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
See Also:
Number.doubleValue()

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, can be null.
Returns:
true if two fractions are equal, false if object is null, not an instance of BigFraction, or not equal to this fraction instance.
See Also:
Object.equals(java.lang.Object)

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.
See Also:
Number.floatValue()

getDenominator

public java.math.BigInteger getDenominator()

Access the denominator as a BigInteger.

Returns:
the denominator as a BigInteger.

getDenominatorAsInt

public int getDenominatorAsInt()

Access the denominator as a int.

Returns:
the denominator as a int.

getDenominatorAsLong

public long getDenominatorAsLong()

Access the denominator as a long.

Returns:
the denominator as a long.

getNumerator

public java.math.BigInteger getNumerator()

Access the numerator as a BigInteger.

Returns:
the numerator as a BigInteger.

getNumeratorAsInt

public int getNumeratorAsInt()

Access the numerator as a int.

Returns:
the numerator as a int.

getNumeratorAsLong

public long getNumeratorAsLong()

Access the numerator as a long.

Returns:
the numerator as a long.

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.
See Also:
Object.hashCode()

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.
See Also:
Number.intValue()

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.
See Also:
Number.longValue()

multiply

public BigFraction multiply(java.math.BigInteger bg)

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

Parameters:
bg - the BigInteger to multiply by.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.NullPointerException - if the bg is null.

multiply

public BigFraction multiply(int i)

Multiply the value of this fraction by the passed int, returning the result in reduced form.

Parameters:
i - the int to multiply by.
Returns:
a BigFraction instance with the resulting values.

multiply

public BigFraction multiply(long l)

Multiply the value of this fraction by the passed long, returning the result in reduced form.

Parameters:
l - the long to multiply by.
Returns:
a BigFraction instance with the resulting values.

multiply

public BigFraction multiply(BigFraction fraction)

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

Specified by:
multiply in interface FieldElement<BigFraction>
Parameters:
fraction - the fraction to multiply by, must not be null.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.NullPointerException - if the fraction is null.

negate

public BigFraction negate()

Return the additive inverse of this fraction, returning the result in reduced form.

Returns:
the negation of this fraction.

percentageValue

public double percentageValue()

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

Returns:
the fraction percentage as a double.

pow

public BigFraction pow(int exponent)

Returns a integer whose value is (thisexponent), returning the result in reduced form.

Parameters:
exponent - exponent to which this BigInteger is to be raised.
Returns:
thisexponent.

pow

public BigFraction pow(long exponent)

Returns a BigFraction whose value is (thisexponent), returning the result in reduced form.

Parameters:
exponent - exponent to which this BigFraction is to be raised.
Returns:
thisexponent as a BigFraction.

pow

public BigFraction pow(java.math.BigInteger exponent)

Returns a BigFraction whose value is (thisexponent), returning the result in reduced form.

Parameters:
exponent - exponent to which this BigFraction is to be raised.
Returns:
thisexponent as a BigFraction.

pow

public double pow(double exponent)

Returns a double whose value is (thisexponent), returning the result in reduced form.

Parameters:
exponent - exponent to which this BigFraction is to be raised.
Returns:
thisexponent.

reciprocal

public BigFraction reciprocal()

Return the multiplicative inverse of this fraction.

Returns:
the reciprocal fraction.

reduce

public BigFraction reduce()

Reduce this BigFraction to its lowest terms.

Returns:
the reduced BigFraction. It doesn't change anything if the fraction can be reduced.

subtract

public BigFraction subtract(java.math.BigInteger bg)

Subtracts the value of an BigInteger from the value of this one, returning the result in reduced form.

Parameters:
bg - the BigInteger to subtract, must'nt be null.
Returns:
a BigFraction instance with the resulting values.
Throws:
java.lang.NullPointerException - if the BigInteger is null.

subtract

public BigFraction subtract(int i)

Subtracts the value of an integer from the value of this one, returning the result in reduced form.

Parameters:
i - the integer to subtract.
Returns:
a BigFraction instance with the resulting values.

subtract

public BigFraction subtract(long l)

Subtracts the value of an integer from the value of this one, returning the result in reduced form.

Parameters:
l - the long to subtract.
Returns:
a BigFraction instance with the resulting values, or this object if the long is zero.

subtract

public BigFraction subtract(BigFraction 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<BigFraction>
Parameters:
fraction - the BigFraction to subtract, must not be null.
Returns:
a BigFraction instance with the resulting values
Throws:
java.lang.NullPointerException - if the fraction is null.

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 BigFractionField getField()
Get the Field to which the instance belongs.

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


Copyright (c) 2003-2010 Apache Software Foundation