## org.apache.commons.lang.math Class Fraction

```java.lang.Object
|
+--java.lang.Number
|
+--org.apache.commons.lang.math.Fraction
```

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`.

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

 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(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. `static Fraction` `getFraction(String str)`           Creates a Fraction from a `String`. ` 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`.

 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

### ZERO

`public static final Fraction ZERO`
`Fraction` representation of 0.

### ONE

`public static final Fraction ONE`
`Fraction` representation of 1.

### ONE_HALF

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

### ONE_THIRD

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

### TWO_THIRDS

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

### ONE_QUARTER

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

### TWO_QUARTERS

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

### THREE_QUARTERS

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

### ONE_FIFTH

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

### TWO_FIFTHS

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

### THREE_FIFTHS

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

### FOUR_FIFTHS

`public static final Fraction FOUR_FIFTHS`
`Fraction` representation of 4/5.
 Method Detail

### 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
Throws:
ArithmeticException - if the denomiator is `zero`

### 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
Throws:
ArithmeticException - if the denomiator is `zero`
ArithmeticException - if the denominator is negative
ArithmeticException - if the numerator is negative
ArithmeticException - if the resulting numerator exceeds `Integer.MAX_VALUE`

### 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:
ArithmeticException - if the denominator is `zero`

### 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
Throws:
ArithmeticException - if `|value| > Integer.MAX_VALUE` or `value = NaN`
ArithmeticException - if the calculated denominator is `zero`
ArithmeticException - if the the algorithm does not converge

### 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
Throws:
IllegalArgumentException - if the string is `null`
NumberFormatException - if the number format is invalid

### 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

### getDenominator

`public int getDenominator()`

Gets the denominator part of the fraction.

Returns:
the denominator 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

### intValue

`public int intValue()`

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

Overrides:
intValue in class 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.

Overrides:
longValue in class Number
Returns:
the whole number fraction part

### floatValue

`public float floatValue()`

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

Overrides:
floatValue in class Number
Returns:
the fraction as a `float`

### doubleValue

`public double doubleValue()`

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

Overrides:
doubleValue in class Number
Returns:
the fraction as a `double`

### 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

### 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.
Throws:
ArithmeticException - if the fraction represents zero.

### 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

### 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

### 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
Throws:
ArithmeticException - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

`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
Throws:
IllegalArgumentException - if the fraction is `null`
ArithmeticException - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

### 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
Throws:
IllegalArgumentException - if the fraction is `null`
ArithmeticException - if the resulting numerator or denominator cannot be represented in an `int`.

### 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
Throws:
IllegalArgumentException - if the fraction is `null`
ArithmeticException - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

### 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
Throws:
IllegalArgumentException - if the fraction is `null`
ArithmeticException - if the fraction to divide by is zero
ArithmeticException - if the resulting numerator or denominator exceeds `Integer.MAX_VALUE`

### 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.

Overrides:
equals in class Object
Parameters:
`obj` - the reference object with which to compare
Returns:
`true` if this object is equal

### hashCode

`public int hashCode()`

Gets a hashCode for the fraction.

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

### compareTo

`public int compareTo(Object object)`

Compares this object to another based on size.

Specified by:
compareTo in interface Comparable
Parameters:
`object` - the object to compare to
Returns:
-1 if this is less, 0 if equal, +1 if greater
Throws:
ClassCastException - if the object is not a `Fraction`
NullPointerException - if the object is `null`

### toString

`public String toString()`

Gets the fraction as a `String`.

The format used is 'numerator/denominator' always.

Overrides:
toString in class Object
Returns:
a `String` form of the fraction

### 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

Copyright © 2001-2005 - Apache Software Foundation