Fraction (Apache Commons Lang 3.2 API)

java.lang.Object
- java.lang.Number
- - org.apache.commons.lang3.math.Fraction

All Implemented Interfaces:

Serializable, Comparable<Fraction>
```
public final class Fraction
extends Number
implements Comparable<Fraction>
```
Fraction is a Number implementation that stores fractions accurately.

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

Note that this class is intended for common use cases, it is int based and thus suffers from various overflow issues. For a BigInteger based equivalent, please see the Commons Math BigFraction class.

Since:

2.0

Version:

$Id: Fraction.java 1436770 2013-01-22 07:09:45Z ggregory $

See Also:
Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`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

Methods
Modifier and Type	Method and Description
`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(Fraction other)` 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 reduced `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 denominator is zero or the denominator is negative and the numerator is Integer#MIN_VALUE
  - 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 denominator 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 reduced Fraction instance with the 2 parts of a fraction Y/Z.
    
    For example, if the input parameters represent 2/4, then the created fraction will be 1/2.
    
    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.
    
    Specified by:
    
    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.
    
    Specified by:
    
    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.
    
    Specified by:
    
    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.
    
    Specified by:
    
    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.
    
    For example, if this fraction represents 2/4, then the result will be 1/2.
    
    Returns:
    a new reduced 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
  - 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
    
    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(Fraction other)
```
    Compares this object to another based on size.
    
    Note: this class has a natural ordering that is inconsistent with equals, because, for example, equals treats 1/2 and 2/4 as different, whereas compareTo treats them as equal.
    
    Specified by:
    
    compareTo in interface Comparable<Fraction>
    
    Parameters:
    other - 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 omitted. If the numerator is zero, only the whole number is returned.
    
    Returns:
    a String form of the fraction

Class Fraction

Field Summary

Method Summary

Methods inherited from class java.lang.Number

Methods inherited from class java.lang.Object

Field Detail

ZERO

ONE

ONE_HALF

ONE_THIRD

TWO_THIRDS

ONE_QUARTER

TWO_QUARTERS

THREE_QUARTERS

ONE_FIFTH

TWO_FIFTHS

THREE_FIFTHS

FOUR_FIFTHS

Method Detail

getFraction

getFraction

getReducedFraction

getFraction

getFraction

getNumerator

getDenominator

getProperNumerator

getProperWhole

intValue

longValue

floatValue

doubleValue

reduce

invert

negate

abs

pow

add

subtract

multiplyBy

divideBy

equals

hashCode

compareTo

toString

toProperString