Fraction (abacus API Documentation)

java.lang.Object
- java.lang.Number
- - com.landawn.abacus.util.Fraction

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<Fraction>
```
public final class Fraction
extends java.lang.Number
implements java.lang.Comparable<Fraction>
```
Note: it's copied from Apache Commons Lang developed at The Apache Software Foundation (http://www.apache.org/), or under the Apache License 2.0. The methods copied from other products/frameworks may be modified in this class.

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 1583482 2014-03-31 22:54:57Z niallp $

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

All Methods Static Methods Instance Methods Concrete Methods Deprecated 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.
`int`	`denominator()`
`Fraction`	`dividedBy(Fraction fraction)` Divide the value of this fraction by another.
`double`	`doubleValue()` Gets the fraction as a `double`.
`boolean`	`equals(java.lang.Object obj)` Compares this fraction to another object to test if they are equal.
`float`	`floatValue()` Gets the fraction as a `float`.
`int`	`getDenominator()` Deprecated. replaced by `denominator`
`int`	`getNumerator()` Deprecated. replaced by `numerator`
`int`	`getProperNumerator()` Deprecated. replaced by `properNumerator`
`int`	`getProperWhole()` Deprecated. replaced by `properWhole`
`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`	`multipliedBy(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.
`int`	`numerator()`
`static Fraction`	`of(double value)` Creates a `Fraction` instance from a `double` value.
`static Fraction`	`of(int numerator, int denominator)`
`static Fraction`	`of(int numerator, int denominator, boolean reduce)` Creates a `Fraction` instance with the 2 parts of a fraction Y/Z.
`static Fraction`	`of(int whole, int numerator, int denominator)`
`static Fraction`	`of(int whole, int numerator, int denominator, boolean reduce)` Creates a `Fraction` instance with the 3 parts of a fraction X Y/Z.
`static Fraction`	`of(java.lang.String str)` Creates a Fraction from a `String`.
`Fraction`	`pow(int power)` Gets a fraction that is raised to the passed in power.
`int`	`properNumerator()`
`int`	`properWhole()`
`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.
`java.lang.String`	`toProperString()` Gets the fraction as a proper `String` in the format X Y/Z.
`java.lang.String`	`toString()` Gets the fraction as a `String`.

Methods inherited from class java.lang.Number
byteValue, shortValue

Methods inherited from class java.lang.Object
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
  - of
```
public static Fraction of(int numerator,
                          int denominator)
```
    Parameters:
    
    numerator -
    
    denominator -
    
    Returns:
    
    See Also:
    
    of(int, int, boolean)
  - of
```
public static Fraction of(int numerator,
                          int denominator,
                          boolean reduce)
```
    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'
    
    reduce - if it's true, reduce 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.
    
    Returns:
    
    a new fraction instance
    
    Throws:
    
    java.lang.ArithmeticException - if the denominator is zero or the denominator is negative and the numerator is Integer#MIN_VALUE
  - of
```
public static Fraction of(int whole,
                          int numerator,
                          int denominator)
```
    Parameters:
    
    whole -
    
    numerator -
    
    denominator -
    
    Returns:
    
    See Also:
    
    #of(int, int, int, boolean)}
  - of
```
public static Fraction of(int whole,
                          int numerator,
                          int denominator,
                          boolean reduce)
```
    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:
    
    java.lang.ArithmeticException - if the denominator is zero
    
    java.lang.ArithmeticException - if the denominator is negative
    
    java.lang.ArithmeticException - if the numerator is negative
    
    java.lang.ArithmeticException - if the resulting numerator exceeds Integer.MAX_VALUE
  - of
```
public static Fraction of(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:
    
    java.lang.ArithmeticException - if |value| > Integer.MAX_VALUE or value = NaN
    
    java.lang.ArithmeticException - if the calculated denominator is zero
    
    java.lang.ArithmeticException - if the the algorithm does not converge
  - of
```
public static Fraction of(java.lang.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:
    
    java.lang.IllegalArgumentException - if the string is null
    
    java.lang.NumberFormatException - if the number format is invalid
  - getNumerator
```
@Deprecated
public int getNumerator()
```
    Deprecated. replaced by numerator
    
    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
  - numerator
```
public int numerator()
```
  - getDenominator
```
@Deprecated
public int getDenominator()
```
    Deprecated. replaced by denominator
    
    Gets the denominator part of the fraction.
    
    Returns:
    
    the denominator fraction part
  - denominator
```
public int denominator()
```
  - getProperNumerator
```
@Deprecated
public int getProperNumerator()
```
    Deprecated. replaced by properNumerator
    
    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
  - properNumerator
```
public int properNumerator()
```
  - getProperWhole
```
@Deprecated
public int getProperWhole()
```
    Deprecated. replaced by properWhole
    
    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
  - properWhole
```
public int properWhole()
```
  - 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
  - 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
  - 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
  - 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
  - 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:
    
    java.lang.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:
    
    java.lang.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:
    
    java.lang.IllegalArgumentException - if the fraction is null
    
    java.lang.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:
    
    java.lang.IllegalArgumentException - if the fraction is null
    
    java.lang.ArithmeticException - if the resulting numerator or denominator cannot be represented in an int.
  - multipliedBy
```
public Fraction multipliedBy(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:
    
    java.lang.IllegalArgumentException - if the fraction is null
    
    java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE
  - dividedBy
```
public Fraction dividedBy(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:
    
    java.lang.IllegalArgumentException - if the fraction is null
    
    java.lang.ArithmeticException - if the fraction to divide by is zero
    
    java.lang.ArithmeticException - if the resulting numerator or denominator exceeds Integer.MAX_VALUE
  - 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 java.lang.Comparable<Fraction>
    
    Parameters:
    
    other - the object to compare to
    
    Returns:
    
    -1 if this is less, 0 if equal, +1 if greater
    
    Throws:
    
    java.lang.ClassCastException - if the object is not a Fraction
    
    java.lang.NullPointerException - if the object is null
  - toProperString
```
public java.lang.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
  - equals
```
public boolean equals(java.lang.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 java.lang.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 java.lang.Object
    
    Returns:
    
    a hash code value for this object
  - toString
```
public java.lang.String toString()
```
    Gets the fraction as a String.
    
    The format used is 'numerator/denominator' always.
    
    Overrides:
    
    toString in class java.lang.Object
    
    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

of

of

of

of

of

of

getNumerator

numerator

getDenominator

denominator

getProperNumerator

properNumerator

getProperWhole

properWhole

intValue

longValue

floatValue

doubleValue

reduce

invert

negate

abs

pow

add

subtract

multipliedBy

dividedBy

compareTo

toProperString

equals

hashCode

toString