org.apache.commons.lang.math

Class Fraction

Implemented Interfaces:
Comparable, Serializable

public final class Fraction
extends Number
implements Serializable, Comparable

Fraction is a Number implementation that stores fractions accurately.

This class is immutable, and interoperable with most methods that accept a Number.

Version:
$Id: Fraction.java 161243 2005-04-14 04:30:28Z ggregory $
Authors:
Travis Reeder
Stephen Colebourne
Tim O'Brien
Pete Gieser
C. Scott Ananian
Since:
2.0

Field Summary

static Fraction
FOUR_FIFTHS
Fraction representation of 4/5.
static Fraction
ONE
Fraction representation of 1.
static Fraction
ONE_FIFTH
Fraction representation of 1/5.
static Fraction
ONE_HALF
Fraction representation of 1/2.
static Fraction
ONE_QUARTER
Fraction representation of 1/4.
static Fraction
ONE_THIRD
Fraction representation of 1/3.
static Fraction
THREE_FIFTHS
Fraction representation of 3/5.
static Fraction
THREE_QUARTERS
Fraction representation of 3/4.
static Fraction
TWO_FIFTHS
Fraction representation of 2/5.
static Fraction
TWO_QUARTERS
Fraction representation of 2/4.
static Fraction
TWO_THIRDS
Fraction representation of 2/3.
static Fraction
ZERO
Fraction representation of 0.

Method Summary

Fraction
abs()
Gets a fraction that is the positive equivalent of this one.
Fraction
add(Fraction fraction)
Adds the value of this fraction to another, returning the result in reduced form.
int
compareTo(Object object)
Compares this object to another based on size.
Fraction
divideBy(Fraction fraction)
Divide the value of this fraction by another.
double
doubleValue()
Gets the fraction as a double.
boolean
equals(Object obj)
Compares this fraction to another object to test if they are equal.
float
floatValue()
Gets the fraction as a float.
int
getDenominator()
Gets the denominator part of the fraction.
static Fraction
getFraction(String str)
Creates a Fraction from a String.
static Fraction
getFraction(double value)
Creates a Fraction instance from a double value.
static Fraction
getFraction(int numerator, int denominator)
Creates a Fraction instance with the 2 parts of a fraction Y/Z.
static Fraction
getFraction(int whole, int numerator, int denominator)
Creates a Fraction instance with the 3 parts of a fraction X Y/Z.
int
getNumerator()
Gets the numerator part of the fraction.
int
getProperNumerator()
Gets the proper numerator, always positive.
int
getProperWhole()
Gets the proper whole part of the fraction.
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.
Fraction
invert()
Gets a fraction that is the inverse (1/fraction) of this one.
long
longValue()
Gets the fraction as a long.
Fraction
multiplyBy(Fraction fraction)
Multiplies the value of this fraction by another, returning the result in reduced form.
Fraction
negate()
Gets a fraction that is the negative (-fraction) of this one.
Fraction
pow(int power)
Gets a fraction that is raised to the passed in power.
Fraction
reduce()
Reduce the fraction to the smallest values for the numerator and denominator, returning the result..
Fraction
subtract(Fraction fraction)
Subtracts the value of another fraction from the value of this one, returning the result in reduced form.
String
toProperString()
Gets the fraction as a proper String in the format X Y/Z.
String
toString()
Gets the fraction as a String.

Field Details

FOUR_FIFTHS

public static final Fraction FOUR_FIFTHS
Fraction representation of 4/5.

ONE

public static final Fraction ONE
Fraction representation of 1.

ONE_FIFTH

public static final Fraction ONE_FIFTH
Fraction representation of 1/5.

ONE_HALF

public static final Fraction ONE_HALF
Fraction representation of 1/2.

ONE_QUARTER

public static final Fraction ONE_QUARTER
Fraction representation of 1/4.

ONE_THIRD

public static final Fraction ONE_THIRD
Fraction representation of 1/3.

THREE_FIFTHS

public static final Fraction THREE_FIFTHS
Fraction representation of 3/5.

THREE_QUARTERS

public static final Fraction THREE_QUARTERS
Fraction representation of 3/4.

TWO_FIFTHS

public static final Fraction TWO_FIFTHS
Fraction representation of 2/5.

TWO_QUARTERS

public static final Fraction TWO_QUARTERS
Fraction representation of 2/4.

TWO_THIRDS

public static final Fraction TWO_THIRDS
Fraction representation of 2/3.

ZERO

public static final Fraction ZERO
Fraction representation of 0.

Method Details

abs

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

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.
Parameters:
fraction - the fraction to add, must not be null
Returns:
a Fraction instance with the resulting values

compareTo

public int compareTo(Object object)
Compares this object to another based on size.
Parameters:
object - the object to compare to
Returns:
-1 if this is less, 0 if equal, +1 if greater

divideBy

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

doubleValue

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

equals

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

floatValue

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

getDenominator

public int getDenominator()
Gets the denominator part of the fraction.
Returns:
the denominator fraction part

getFraction

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 - the string to parse, must not be null
Returns:
the new Fraction instance

getFraction

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 - the double value to convert
Returns:
a new fraction instance that is close to the value

getFraction

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 - the numerator, for example the three in 'three sevenths'
denominator - the denominator, for example the seven in 'three sevenths'
Returns:
a new fraction instance

getFraction

public static Fraction getFraction(int whole,
                                   int numerator,
                                   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 - 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

getNumerator

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

getProperNumerator

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

getProperWhole

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

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

hashCode

public int hashCode()
Gets a hashCode for the fraction.
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.
Returns:
the whole number fraction part

invert

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.

longValue

public long longValue()
Gets the fraction as a long. This returns the whole number part of the fraction.
Returns:
the whole number fraction part

multiplyBy

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

negate

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

pow

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

reduce

public Fraction reduce()
Reduce the fraction to the smallest values for the numerator and denominator, returning the result..
Returns:
a new reduce fraction instance, or this if no simplification possible

subtract

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

toProperString

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 ommitted. If the numerator is zero, only the whole number is returned.

Returns:
a String form of the fraction

toString

public String toString()
Gets the fraction as a String.

The format used is 'numerator/denominator' always.

Returns:
a String form of the fraction

Copyright © 2001-2005 - Apache Software Foundation