BigRational (ch.obermuhlner.math.big 2.0.0 API)

java.lang.Object
- ch.obermuhlner.math.big.BigRational

All Implemented Interfaces:

java.lang.Comparable<BigRational>
```
public class BigRational
extends java.lang.Object
implements java.lang.Comparable<BigRational>
```
A rational number represented as a quotient of two values.
Basic calculations with rational numbers (+ - * /) have no loss of precision. This allows to use BigRational as a replacement for BigDecimal if absolute accuracy is desired.

Wikipedia: Rational number

The values are internally stored as BigDecimal (for performance optimizations) but represented as BigInteger (for mathematical correctness) when accessed with getNumeratorBigInteger() and getDenominatorBigInteger().

The following basic calculations have no loss of precision:
The following calculations are special cases of the ones listed above and have no loss of precision:
Any BigRational value can be converted into an arbitrary precision (number of significant digits) or scale (number of digits after the decimal point).

Field Summary

Fields
Modifier and Type	Field and Description
`static BigRational`	`ONE` The value 1 as `BigRational`.
`static BigRational`	`TEN` The value 10 as `BigRational`.
`static BigRational`	`TWO` The value 2 as `BigRational`.
`static BigRational`	`ZERO` The value 0 as `BigRational`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`BigRational`	`abs()` Returns the absolute value of this rational number.
`BigRational`	`add(java.math.BigInteger value)` Calculates the addition (+) of this rational number and the specified argument.
`BigRational`	`add(BigRational value)` Calculates the addition (+) of this rational number and the specified argument.
`BigRational`	`add(int value)` Calculates the addition (+) of this rational number and the specified argument.
`static BigRational`	`bernoulli(int n)` Calculates the Bernoulli number for the specified index.
`int`	`compareTo(BigRational other)`
`BigRational`	`decrement()` Calculates the decrement of this rational number (- 1).
`BigRational`	`divide(java.math.BigInteger value)` Calculates the division (/) of this rational number and the specified argument.
`BigRational`	`divide(BigRational value)` Calculates the division (/) of this rational number and the specified argument.
`BigRational`	`divide(int value)` Calculates the division (/) of this rational number and the specified argument.
`boolean`	`equals(java.lang.Object obj)`
`BigRational`	`fractionPart()` Returns the fraction part of this rational number.
`java.math.BigDecimal`	`getDenominator()` Returns the denominator of this rational number as BigDecimal.
`java.math.BigInteger`	`getDenominatorBigInteger()` Returns the denominator of this rational number as BigInteger.
`java.math.BigDecimal`	`getNumerator()` Returns the numerator of this rational number as BigDecimal.
`java.math.BigInteger`	`getNumeratorBigInteger()` Returns the numerator of this rational number as BigInteger.
`int`	`hashCode()`
`BigRational`	`increment()` Calculates the increment of this rational number (+ 1).
`BigRational`	`integerPart()` Returns the integer part of this rational number.
`boolean`	`isInteger()` Returns whether this rational number is an integer number without fraction part.
`boolean`	`isZero()` Returns whether this rational number is zero.
`static BigRational`	`max(BigRational... values)` Returns the largest of the specified rational numbers.
`static BigRational`	`min(BigRational... values)` Returns the smallest of the specified rational numbers.
`BigRational`	`multiply(java.math.BigInteger value)` Calculates the multiplication (*) of this rational number and the specified argument.
`BigRational`	`multiply(BigRational value)` Calculates the multiplication (*) of this rational number and the specified argument.
`BigRational`	`multiply(int value)` Calculates the multiplication (*) of this rational number and the specified argument.
`BigRational`	`negate()` Negates this rational number (inverting the sign).
`BigRational`	`pow(int exponent)` Calculates this rational number to the power (x^y) of the specified argument.
`BigRational`	`reciprocal()` Calculates the reciprocal of this rational number (1/x).
`BigRational`	`reduce()` Reduces this rational number to the smallest numerator/denominator with the same value.
`int`	`signum()` Returns the signum function of this rational number.
`BigRational`	`subtract(java.math.BigInteger value)` Calculates the subtraction (-) of this rational number and the specified argument.
`BigRational`	`subtract(BigRational value)` Calculates the subtraction (-) of this rational number and the specified argument.
`BigRational`	`subtract(int value)` Calculates the subtraction (-) of this rational number and the specified argument.
`java.math.BigDecimal`	`toBigDecimal()` Returns this rational number as a `BigDecimal`.
`java.math.BigDecimal`	`toBigDecimal(java.math.MathContext mc)` Returns this rational number as a `BigDecimal` with the precision specified by the `MathContext`.
`double`	`toDouble()` Returns this rational number as a double value.
`float`	`toFloat()` Returns this rational number as a float value.
`java.lang.String`	`toIntegerRationalString()` Returns the string representation of this rational number as integer and fraction parts in the form "integerPart fractionNominator/fractionDenominator".
`java.lang.String`	`toPlainString()` Returns a plain string representation of this rational number without any exponent.
`java.lang.String`	`toRationalString()` Returns the string representation of this rational number in the form "numerator/denominator".
`java.lang.String`	`toString()`
`static BigRational`	`valueOf(java.math.BigDecimal value)` Creates a rational number of the specified `BigDecimal` value.
`static BigRational`	`valueOf(java.math.BigDecimal numerator, java.math.BigDecimal denominator)` Creates a rational number of the specified numerator/denominator BigDecimal values.
`static BigRational`	`valueOf(java.math.BigInteger value)` Creates a rational number of the specified `BigInteger` value.
`static BigRational`	`valueOf(java.math.BigInteger numerator, java.math.BigInteger denominator)` Creates a rational number of the specified numerator/denominator BigInteger values.
`static BigRational`	`valueOf(boolean positive, java.lang.String integerPart, java.lang.String fractionPart, java.lang.String fractionRepeatPart, java.lang.String exponentPart)`
`static BigRational`	`valueOf(double value)` Creates a rational number of the specified double value.
`static BigRational`	`valueOf(int value)` Creates a rational number of the specified int value.
`static BigRational`	`valueOf(int numerator, int denominator)` Creates a rational number of the specified numerator/denominator int values.
`static BigRational`	`valueOf(int integer, int fractionNumerator, int fractionDenominator)` Creates a rational number of the specified integer and fraction parts.
`static BigRational`	`valueOf(java.lang.String string)` Creates a rational number of the specified string representation.
`BigRational`	`withPrecision(int precision)` Returns a rational number with approximatively `this` value and the specified precision.
`BigRational`	`withScale(int scale)` Returns a rational number with approximatively `this` value and the specified scale.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - ZERO
```
public static final BigRational ZERO
```
    The value 0 as BigRational.
  - ONE
```
public static final BigRational ONE
```
    The value 1 as BigRational.
  - TWO
```
public static final BigRational TWO
```
    The value 2 as BigRational.
  - TEN
```
public static final BigRational TEN
```
    The value 10 as BigRational.
- Method Detail
  - getNumeratorBigInteger
```
public java.math.BigInteger getNumeratorBigInteger()
```
    Returns the numerator of this rational number as BigInteger.
    
    Returns:
    
    the numerator as BigInteger
  - getNumerator
```
public java.math.BigDecimal getNumerator()
```
    Returns the numerator of this rational number as BigDecimal.
    
    Returns:
    
    the numerator as BigDecimal
  - getDenominatorBigInteger
```
public java.math.BigInteger getDenominatorBigInteger()
```
    Returns the denominator of this rational number as BigInteger.
    Guaranteed to not be 0.
    
    Guaranteed to be positive.
    
    Returns:
    
    the denominator as BigInteger
  - getDenominator
```
public java.math.BigDecimal getDenominator()
```
    Returns the denominator of this rational number as BigDecimal.
    Guaranteed to not be 0.
    
    Guaranteed to be positive.
    
    Returns:
    
    the denominator as BigDecimal
  - reduce
```
public BigRational reduce()
```
    Reduces this rational number to the smallest numerator/denominator with the same value.
    
    Returns:
    
    the reduced rational number
  - integerPart
```
public BigRational integerPart()
```
    Returns the integer part of this rational number.
    Examples:
    - BigRational.valueOf(3.5).integerPart() returns BigRational.valueOf(3)
    Returns:
    
    the integer part of this rational number
  - fractionPart
```
public BigRational fractionPart()
```
    Returns the fraction part of this rational number.
    Examples:
    - BigRational.valueOf(3.5).integerPart() returns BigRational.valueOf(0.5)
    Returns:
    
    the fraction part of this rational number
  - negate
```
public BigRational negate()
```
    Negates this rational number (inverting the sign).
    The result has no loss of precision.
    
    Examples:
    - BigRational.valueOf(3.5).negate() returns BigRational.valueOf(-3.5)
    Returns:
    
    the negated rational number
  - reciprocal
```
public BigRational reciprocal()
```
    Calculates the reciprocal of this rational number (1/x).
    The result has no loss of precision.
    
    Examples:
    - BigRational.valueOf(0.5).reciprocal() returns BigRational.valueOf(2)
    - BigRational.valueOf(-2).reciprocal() returns BigRational.valueOf(-0.5)
    Returns:
    
    the reciprocal rational number
    
    Throws:
    
    java.lang.ArithmeticException - if this number is 0 (division by zero)
  - abs
```
public BigRational abs()
```
    Returns the absolute value of this rational number.
    The result has no loss of precision.
    
    Examples:
    - BigRational.valueOf(-2).abs() returns BigRational.valueOf(2)
    - BigRational.valueOf(2).abs() returns BigRational.valueOf(2)
    Returns:
    
    the absolute rational number (positive, or 0 if this rational is 0)
  - signum
```
public int signum()
```
    Returns the signum function of this rational number.
    
    Returns:
    
    -1, 0 or 1 as the value of this rational number is negative, zero or positive.
  - increment
```
public BigRational increment()
```
    Calculates the increment of this rational number (+ 1).
    This is functionally identical to this.add(BigRational.ONE) but slightly faster.
    
    The result has no loss of precision.
    
    Returns:
    
    the incremented rational number
  - decrement
```
public BigRational decrement()
```
    Calculates the decrement of this rational number (- 1).
    This is functionally identical to this.subtract(BigRational.ONE) but slightly faster.
    
    The result has no loss of precision.
    
    Returns:
    
    the decremented rational number
  - add
```
public BigRational add(BigRational value)
```
    Calculates the addition (+) of this rational number and the specified argument.
    The result has no loss of precision.
    
    Parameters:
    
    value - the rational number to add
    
    Returns:
    
    the resulting rational number
  - add
```
public BigRational add(java.math.BigInteger value)
```
    Calculates the addition (+) of this rational number and the specified argument.
    This is functionally identical to this.add(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the BigInteger to add
    
    Returns:
    
    the resulting rational number
  - add
```
public BigRational add(int value)
```
    Calculates the addition (+) of this rational number and the specified argument.
    This is functionally identical to this.add(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the int value to add
    
    Returns:
    
    the resulting rational number
  - subtract
```
public BigRational subtract(BigRational value)
```
    Calculates the subtraction (-) of this rational number and the specified argument.
    The result has no loss of precision.
    
    Parameters:
    
    value - the rational number to subtract
    
    Returns:
    
    the resulting rational number
  - subtract
```
public BigRational subtract(java.math.BigInteger value)
```
    Calculates the subtraction (-) of this rational number and the specified argument.
    This is functionally identical to this.subtract(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the BigInteger to subtract
    
    Returns:
    
    the resulting rational number
  - subtract
```
public BigRational subtract(int value)
```
    Calculates the subtraction (-) of this rational number and the specified argument.
    This is functionally identical to this.subtract(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the int value to subtract
    
    Returns:
    
    the resulting rational number
  - multiply
```
public BigRational multiply(BigRational value)
```
    Calculates the multiplication (*) of this rational number and the specified argument.
    The result has no loss of precision.
    
    Parameters:
    
    value - the rational number to multiply
    
    Returns:
    
    the resulting rational number
  - multiply
```
public BigRational multiply(java.math.BigInteger value)
```
    Calculates the multiplication (*) of this rational number and the specified argument.
    This is functionally identical to this.multiply(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the BigInteger to multiply
    
    Returns:
    
    the resulting rational number
  - multiply
```
public BigRational multiply(int value)
```
    Calculates the multiplication (*) of this rational number and the specified argument.
    This is functionally identical to this.multiply(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the int value to multiply
    
    Returns:
    
    the resulting rational number
  - divide
```
public BigRational divide(BigRational value)
```
    Calculates the division (/) of this rational number and the specified argument.
    The result has no loss of precision.
    
    Parameters:
    
    value - the rational number to divide (0 is not allowed)
    
    Returns:
    
    the resulting rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the argument is 0 (division by zero)
  - divide
```
public BigRational divide(java.math.BigInteger value)
```
    Calculates the division (/) of this rational number and the specified argument.
    This is functionally identical to this.divide(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the BigInteger to divide (0 is not allowed)
    
    Returns:
    
    the resulting rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the argument is 0 (division by zero)
  - divide
```
public BigRational divide(int value)
```
    Calculates the division (/) of this rational number and the specified argument.
    This is functionally identical to this.divide(BigRational.valueOf(value)) but slightly faster.
    
    The result has no loss of precision.
    
    Parameters:
    
    value - the int value to divide (0 is not allowed)
    
    Returns:
    
    the resulting rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the argument is 0 (division by zero)
  - isZero
```
public boolean isZero()
```
    Returns whether this rational number is zero.
    
    Returns:
    
    true if this rational number is zero (0), false if it is not zero
  - isInteger
```
public boolean isInteger()
```
    Returns whether this rational number is an integer number without fraction part.
    
    Returns:
    
    true if this rational number is an integer number, false if it has a fraction part
  - pow
```
public BigRational pow(int exponent)
```
    Calculates this rational number to the power (x^y) of the specified argument.
    The result has no loss of precision.
    
    Parameters:
    
    exponent - exponent to which this rational number is to be raised
    
    Returns:
    
    the resulting rational number
  - withPrecision
```
public BigRational withPrecision(int precision)
```
    Returns a rational number with approximatively this value and the specified precision.
    
    Parameters:
    
    precision - the precision (number of significant digits) of the calculated result, or 0 for unlimited precision
    
    Returns:
    
    the calculated rational number with the specified precision
  - withScale
```
public BigRational withScale(int scale)
```
    Returns a rational number with approximatively this value and the specified scale.
    
    Parameters:
    
    scale - the scale (number of digits after the decimal point) of the calculated result
    
    Returns:
    
    the calculated rational number with the specified scale
  - toDouble
```
public double toDouble()
```
    Returns this rational number as a double value.
    
    Returns:
    
    the double value
  - toFloat
```
public float toFloat()
```
    Returns this rational number as a float value.
    
    Returns:
    
    the float value
  - toBigDecimal
```
public java.math.BigDecimal toBigDecimal()
```
    Returns this rational number as a BigDecimal.
    
    Returns:
    
    the BigDecimal value
  - toBigDecimal
```
public java.math.BigDecimal toBigDecimal(java.math.MathContext mc)
```
    Returns this rational number as a BigDecimal with the precision specified by the MathContext.
    
    Parameters:
    
    mc - the MathContext specifying the precision of the calculated result
    
    Returns:
    
    the BigDecimal
  - compareTo
```
public int compareTo(BigRational other)
```
    Specified by:
    
    compareTo in interface java.lang.Comparable<BigRational>
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - equals
```
public boolean equals(java.lang.Object obj)
```
    Overrides:
    
    equals in class java.lang.Object
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - toPlainString
```
public java.lang.String toPlainString()
```
    Returns a plain string representation of this rational number without any exponent.
    
    Returns:
    
    the plain string representation
    
    See Also:
    
    BigDecimal.toPlainString()
  - toRationalString
```
public java.lang.String toRationalString()
```
    Returns the string representation of this rational number in the form "numerator/denominator".
    The resulting string is a valid input of the valueOf(String) method.
    
    Examples:
    - BigRational.valueOf(0.5).toRationalString() returns "1/2"
    - BigRational.valueOf(2).toRationalString() returns "2"
    - BigRational.valueOf(4, 4).toRationalString() returns "4/4" (not reduced)
    Returns:
    
    the rational number string representation in the form "numerator/denominator", or "0" if the rational number is 0.
    
    See Also:
    
    valueOf(String), valueOf(int, int)
  - toIntegerRationalString
```
public java.lang.String toIntegerRationalString()
```
    Returns the string representation of this rational number as integer and fraction parts in the form "integerPart fractionNominator/fractionDenominator".
    The integer part is omitted if it is 0 (when this absolute rational number is smaller than 1).
    
    The fraction part is omitted it it is 0 (when this rational number is an integer).
    
    If this rational number is 0, then "0" is returned.
    
    Example: BigRational.valueOf(3.5).toIntegerRationalString() returns "3 1/2".
    
    Returns:
    
    the integer and fraction rational string representation
    
    See Also:
    
    valueOf(int, int, int)
  - valueOf
```
public static BigRational valueOf(int value)
```
    Creates a rational number of the specified int value.
    
    Parameters:
    
    value - the int value
    
    Returns:
    
    the rational number
  - valueOf
```
public static BigRational valueOf(int numerator,
                                  int denominator)
```
    Creates a rational number of the specified numerator/denominator int values.
    
    Parameters:
    
    numerator - the numerator int value
    
    denominator - the denominator int value (0 not allowed)
    
    Returns:
    
    the rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the denominator is 0 (division by zero)
  - valueOf
```
public static BigRational valueOf(int integer,
                                  int fractionNumerator,
                                  int fractionDenominator)
```
    Creates a rational number of the specified integer and fraction parts.
    Useful to create numbers like 3 1/2 (= three and a half = 3.5) by calling BigRational.valueOf(3, 1, 2).
    
    To create a negative rational only the integer part argument is allowed to be negative: to create -3 1/2 (= minus three and a half = -3.5) call BigRational.valueOf(-3, 1, 2).
    
    Parameters:
    
    integer - the integer part int value
    
    fractionNumerator - the fraction part numerator int value (negative not allowed)
    
    fractionDenominator - the fraction part denominator int value (0 or negative not allowed)
    
    Returns:
    
    the rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the fraction part denominator is 0 (division by zero), or if the fraction part numerator or denominator is negative
  - valueOf
```
public static BigRational valueOf(java.math.BigInteger numerator,
                                  java.math.BigInteger denominator)
```
    Creates a rational number of the specified numerator/denominator BigInteger values.
    
    Parameters:
    
    numerator - the numerator BigInteger value
    
    denominator - the denominator BigInteger value (0 not allowed)
    
    Returns:
    
    the rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the denominator is 0 (division by zero)
  - valueOf
```
public static BigRational valueOf(java.math.BigInteger value)
```
    Creates a rational number of the specified BigInteger value.
    
    Parameters:
    
    value - the BigInteger value
    
    Returns:
    
    the rational number
  - valueOf
```
public static BigRational valueOf(double value)
```
    Creates a rational number of the specified double value.
    
    Parameters:
    
    value - the double value
    
    Returns:
    
    the rational number
    
    Throws:
    
    java.lang.NumberFormatException - if the double value is Infinite or NaN.
  - valueOf
```
public static BigRational valueOf(java.math.BigDecimal value)
```
    Creates a rational number of the specified BigDecimal value.
    
    Parameters:
    
    value - the double value
    
    Returns:
    
    the rational number
  - valueOf
```
public static BigRational valueOf(java.lang.String string)
```
    Creates a rational number of the specified string representation.
    The accepted string representations are:
    - Output of toString() : "integerPart.fractionPart"
    - Output of toRationalString() : "numerator/denominator"
    - Output of toString() of BigDecimal, BigInteger, Integer, ...
    - Output of toString() of Double, Float - except "Infinity", "-Infinity" and "NaN"
    Parameters:
    
    string - the string representation to convert
    
    Returns:
    
    the rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the denominator is 0 (division by zero)
  - valueOf
```
public static BigRational valueOf(boolean positive,
                                  java.lang.String integerPart,
                                  java.lang.String fractionPart,
                                  java.lang.String fractionRepeatPart,
                                  java.lang.String exponentPart)
```
  - valueOf
```
public static BigRational valueOf(java.math.BigDecimal numerator,
                                  java.math.BigDecimal denominator)
```
    Creates a rational number of the specified numerator/denominator BigDecimal values.
    
    Parameters:
    
    numerator - the numerator BigDecimal value
    
    denominator - the denominator BigDecimal value (0 not allowed)
    
    Returns:
    
    the rational number
    
    Throws:
    
    java.lang.ArithmeticException - if the denominator is 0 (division by zero)
  - min
```
public static BigRational min(BigRational... values)
```
    Returns the smallest of the specified rational numbers.
    
    Parameters:
    
    values - the rational numbers to compare
    
    Returns:
    
    the smallest rational number, 0 if no numbers are specified
  - max
```
public static BigRational max(BigRational... values)
```
    Returns the largest of the specified rational numbers.
    
    Parameters:
    
    values - the rational numbers to compare
    
    Returns:
    
    the largest rational number, 0 if no numbers are specified
    
    See Also:
    
    max(BigRational)
  - bernoulli
```
public static BigRational bernoulli(int n)
```
    Calculates the Bernoulli number for the specified index.
    This function calculates the first Bernoulli numbers and therefore bernoulli(1) returns -0.5
    
    Note that bernoulli(x) for all odd x > 1 returns 0
    
    See: Wikipedia: Bernoulli number
    
    Parameters:
    
    n - the index of the Bernoulli number to be calculated (starting at 0)
    
    Returns:
    
    the Bernoulli number for the specified index
    
    Throws:
    
    java.lang.ArithmeticException - if x is lesser than 0

Class BigRational

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZERO

ONE

TWO

TEN

Method Detail

getNumeratorBigInteger

getNumerator

getDenominatorBigInteger

getDenominator

reduce

integerPart

fractionPart

negate

reciprocal

abs

signum

increment

decrement

add

add

add

subtract

subtract

subtract

multiply

multiply

multiply

divide

divide

divide

isZero

isInteger

pow

withPrecision

withScale

toDouble

toFloat

toBigDecimal

toBigDecimal

compareTo

hashCode

equals

toString

toPlainString

toRationalString

toIntegerRationalString

valueOf

valueOf

valueOf

valueOf

valueOf

valueOf

valueOf

valueOf

valueOf

valueOf

min

max

bernoulli