Package ch.obermuhlner.math.big

Class BigRational

java.lang.Object
java.lang.Number
ch.obermuhlner.math.big.BigRational
All Implemented Interfaces:
Serializable, Comparable<BigRational>
public class BigRational extends Number implements Comparable<BigRational>, Serializable
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).

See Also:

  • Field Details

  • Constructor Details

    • BigRational

      private BigRational(int value)

    • BigRational

      private BigRational(BigDecimal num, BigDecimal denom)

  • Method Details

    • getNumeratorBigInteger

      public BigInteger getNumeratorBigInteger()
      Returns the numerator of this rational number as BigInteger.
      Returns:
      the numerator as BigInteger

    • getNumerator

      public BigDecimal getNumerator()
      Returns the numerator of this rational number as BigDecimal.
      Returns:
      the numerator as BigDecimal

    • getDenominatorBigInteger

      public 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 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:
      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

      private BigRational add(BigDecimal value)

    • add

      public BigRational add(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

      private BigRational subtract(BigDecimal value)

    • subtract

      public BigRational subtract(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

      private BigRational multiply(BigDecimal value)

    • multiply

      public BigRational multiply(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:
      ArithmeticException - if the argument is 0 (division by zero)

    • divide

      private BigRational divide(BigDecimal value)

    • divide

      public BigRational divide(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:
      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:
      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

    • isPositive

      private boolean isPositive()

    • 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

    • isIntegerInternal

      private boolean isIntegerInternal()
      Returns whether this rational number is an integer number without fraction part.

      Will return false if this number is not reduced to the integer representation yet (e.g. 4/4 or 4/2)

      Returns:
      true if this rational number is an integer number, false if it has a fraction part
      See Also:

    • pow

      public BigRational pow(int exponent)
      Calculates this rational number to the power (xy) 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

    • min

      private BigRational min(BigRational value)
      Finds the minimum (smaller) of two rational numbers.
      Parameters:
      value - the rational number to compare with
      Returns:
      the minimum rational number, either this or the argument value

    • max

      private BigRational max(BigRational value)
      Finds the maximum (larger) of two rational numbers.
      Parameters:
      value - the rational number to compare with
      Returns:
      the minimum rational number, either this or the argument value

    • 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

    • countDigits

      private static int countDigits(BigInteger number)

    • precision

      private int precision()

    • toDouble

      public double toDouble()
      Returns this rational number as a double value.

      If the rational number cannot be represented as double then one of the following results will be returned:

      Returns:
      the double value

    • toFloat

      public float toFloat()
      Returns this rational number as a float value.

      If the rational number cannot be represented as float then one of the following results will be returned:

      Returns:
      the float value

    • toBigDecimal

      public BigDecimal toBigDecimal()
      Returns this rational number as a BigDecimal.
      Returns:
      the BigDecimal value

    • toBigDecimal

      public BigDecimal toBigDecimal(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 Comparable<BigRational>

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toPlainString

      public String toPlainString()
      Returns a plain string representation of this rational number without any exponent.
      Returns:
      the plain string representation
      See Also:

    • toRationalString

      public 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:

    • toIntegerRationalString

      public 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

      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:
      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:
      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(BigInteger numerator, 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:
      ArithmeticException - if the denominator is 0 (division by zero)

    • valueOf

      public static BigRational valueOf(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:
      NumberFormatException - if the double value is Infinite or NaN.

    • valueOf

      public static BigRational valueOf(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(String string)
      Creates a rational number of the specified string representation.

      The accepted string representations are:

      Parameters:
      string - the string representation to convert
      Returns:
      the rational number
      Throws:
      ArithmeticException - if the denominator is 0 (division by zero)

    • valueOfSimple

      private static BigRational valueOfSimple(String string)

    • valueOf

      public static BigRational valueOf(boolean positive, String integerPart, String fractionPart, String fractionRepeatPart, String exponentPart)

    • valueOf

      public static BigRational valueOf(BigDecimal numerator, 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:
      ArithmeticException - if the denominator is 0 (division by zero)

    • of

      private static BigRational of(BigDecimal numerator, BigDecimal denominator)

    • 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:

    • 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:
      ArithmeticException - if x is lesser than 0

    • calculateBernoulli

      private static BigRational calculateBernoulli(int n)

    • intValue

      public int intValue()
      Specified by:
      intValue in class Number

    • longValue

      public long longValue()
      Specified by:
      longValue in class Number

    • floatValue

      public float floatValue()
      Specified by:
      floatValue in class Number

    • doubleValue

      public double doubleValue()
      Specified by:
      doubleValue in class Number