Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

    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 1199894 2011-11-09 17:53:59Z ggregory $
See Also:
  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(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 ommitted. If the numerator is zero, only the whole number is returned.

  Returns:
    a `String` form of the fraction

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001-2011 The Apache Software Foundation. All Rights Reserved.