# Class AprationalMath

java.lang.Object
org.apfloat.AprationalMath

public class AprationalMath extends Object
Various mathematical functions for arbitrary precision rational numbers.

Version:
  1.15.0
Author:
  Mikko Tommila

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Aprational`
  `abs(Aprational x)`
  Absolute value.
  `static Aprational`
  `bernoulli(long n)`
  Returns the specified Bernoulli number.
  `static Aprational`
  `bernoulli(long n, int radix)`
  Returns the specified Bernoulli number in the given radix.
  `static Aprational`
  `binomial(Aprational n, Aprational k)`
  Binomial coefficient.
  `static Apint[]`
  `continuedFraction(Aprational x, int n)`
  Generates the first `n` terms in the continued fraction representation of `x`.
  `static Aprational[]`
  `convergents(Aprational x, int n)`
  Generates the first `n` convergents corresponding to the continued fraction of `x`.
  `static Aprational`
  `copySign(Aprational x, Aprational y)`
  Copy sign from one argument to another.
  `static Aprational`
  `doubleFactorial(long n)`
  Double factorial function.
  `static Aprational`
  `doubleFactorial(long n, int radix)`
  Double factorial function.
  `static Aprational`
  `harmonicNumber(Apint n)`
  Harmonic number.
  `static Aprational`
  `harmonicNumber(Apint n, Apint r)`
  Generalized harmonic number.
  `static Aprational`
  `max(Aprational x, Aprational y)`
  Returns the greater of the two values.
  `static Aprational`
  `min(Aprational x, Aprational y)`
  Returns the smaller of the two values.
  `static Aprational`
  `negate(Aprational x)`
  Deprecated.
  Use `Aprational.negate()`.
  `static Aprational`
  `pochhammer(Aprational x, Apint n)`
  Pochhammer symbol.
  `static Aprational`
  `pow(Aprational x, long n)`
  Integer power.
  `static Aprational`
  `product(Aprational... x)`
  Product of numbers.
  `static Apfloat`
  `round(Aprational x, long precision, RoundingMode roundingMode)`
  Deprecated.
  Use `roundToPrecision(Aprational,long,RoundingMode)`.
  `static Apint`
  `roundToInteger(Aprational x, RoundingMode roundingMode)`
  Rounds `x` to integer using the specified rounding mode.
  `static Aprational`
  `roundToMultiple(Aprational x, Aprational y, RoundingMode roundingMode)`
  Rounds `x` to the nearest multiple of `y` using the specified rounding mode.
  `static Apfloat`
  `roundToPlaces(Aprational x, long places, RoundingMode roundingMode)`
  Rounds `x` to the specified number of places using the specified rounding mode.
  `static Apfloat`
  `roundToPrecision(Aprational x, long precision, RoundingMode roundingMode)`
  Rounds the given number to the specified precision with the specified rounding mode.
  `static Aprational`
  `scale(Aprational x, long scale)`
  Multiply by a power of the radix.
  `static Aprational`
  `sum(Aprational... x)`
  Sum of numbers.

  ### Methods inherited from class Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### pow

    public static Aprational pow(Aprational x, long n) throws ArithmeticException, ApfloatRuntimeException
    Integer power.
    Parameters:
      `x` - Base of the power operator.
      `n` - Exponent of the power operator.
    Returns:
      `x` to the `n`:th power, that is `xn`.
    Throws:
      `ArithmeticException` - If both `x` and `n` are zero.
      `ApfloatRuntimeException`

  - ### negate

    @Deprecated public static Aprational negate(Aprational x) throws ApfloatRuntimeException
    Deprecated.
    Use `Aprational.negate()`.
    Returns an aprational whose value is `-x`.
    Parameters:
      `x` - The argument.
    Returns:
      `-x`.
    Throws:
      `ApfloatRuntimeException`

  - ### abs

    public static Aprational abs(Aprational x) throws ApfloatRuntimeException
    Absolute value.
    Parameters:
      `x` - The argument.
    Returns:
      Absolute value of `x`.
    Throws:
      `ApfloatRuntimeException`

  - ### copySign

    public static Aprational copySign(Aprational x, Aprational y) throws ApfloatRuntimeException
    Copy sign from one argument to another.
    Parameters:
      `x` - The value whose sign is to be adjusted.
      `y` - The value whose sign is to be used.
    Returns:
      `x` with its sign changed to match the sign of `y`.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.1

  - ### scale

    public static Aprational scale(Aprational x, long scale) throws ApfloatRuntimeException
    Multiply by a power of the radix. Note that this method is prone to intermediate overflow errors. Also, scaling by a very large negative number won't result in an underflow and a zero result, but an overflow of the denominator and an exception thrown.
    Parameters:
      `x` - The argument.
      `scale` - The scaling factor.
    Returns:
      `x * x.radix()scale`.
    Throws:
      `ApfloatRuntimeException`

  - ### round

    @Deprecated public static Apfloat round(Aprational x, long precision, RoundingMode roundingMode) throws IllegalArgumentException, ArithmeticException, ApfloatRuntimeException
    Deprecated.
    Use `roundToPrecision(Aprational,long,RoundingMode)`.
    Rounds the given number to the specified precision with the specified rounding mode.
    Parameters:
      `x` - The number to round.
      `precision` - The precision to round to.
      `roundingMode` - The rounding mode to use.
    Returns:
      The rounded number.
    Throws:
      `IllegalArgumentException` - If `precision` is less than zero or zero.
      `ArithmeticException` - If rounding is necessary (result is not exact) and rounding mode is `RoundingMode.UNNECESSARY`.
      `ApfloatRuntimeException`
    Since:
      1.7.0

  - ### roundToPrecision

    public static Apfloat roundToPrecision(Aprational x, long precision, RoundingMode roundingMode) throws IllegalArgumentException, ArithmeticException, ApfloatRuntimeException
    Rounds the given number to the specified precision with the specified rounding mode.
    Parameters:
      `x` - The number to round.
      `precision` - The precision to round to.
      `roundingMode` - The rounding mode to use.
    Returns:
      The rounded number.
    Throws:
      `IllegalArgumentException` - If `precision` is less than zero or zero.
      `ArithmeticException` - If rounding is necessary (result is not exact) and rounding mode is `RoundingMode.UNNECESSARY`.
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### roundToInteger

    public static Apint roundToInteger(Aprational x, RoundingMode roundingMode) throws IllegalArgumentException, ArithmeticException, ApfloatRuntimeException
    Rounds `x` to integer using the specified rounding mode.
    Parameters:
      `x` - The number to round.
      `roundingMode` - The rounding mode to use.
    Returns:
      The rounded number.
    Throws:
      `ArithmeticException` - If rounding is necessary (result is not exact) and rounding mode is `RoundingMode.UNNECESSARY`.
      `IllegalArgumentException`
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### roundToPlaces

    public static Apfloat roundToPlaces(Aprational x, long places, RoundingMode roundingMode) throws IllegalArgumentException, ArithmeticException, ApfloatRuntimeException
    Rounds `x` to the specified number of places using the specified rounding mode.
    Parameters:
      `x` - The number to round.
      `places` - The number of places to round to (in base 10, the number of decimal places).
      `roundingMode` - The rounding mode to use.
    Returns:
      The rounded number.
    Throws:
      `ArithmeticException` - If rounding is necessary (result is not exact) and rounding mode is `RoundingMode.UNNECESSARY`.
      `IllegalArgumentException`
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### roundToMultiple

    public static Aprational roundToMultiple(Aprational x, Aprational y, RoundingMode roundingMode) throws IllegalArgumentException, ArithmeticException, ApfloatRuntimeException
    Rounds `x` to the nearest multiple of `y` using the specified rounding mode.
    Parameters:
      `x` - The number to round.
      `y` - The integer multiple to round to.
      `roundingMode` - The rounding mode to use.
    Returns:
      The rounded number.
    Throws:
      `ArithmeticException` - If rounding is necessary (result is not exact) and rounding mode is `RoundingMode.UNNECESSARY`.
      `IllegalArgumentException`
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### product

    public static Aprational product(Aprational... x) throws ApfloatRuntimeException
    Product of numbers. This method may perform significantly better than simply multiplying the numbers sequentially.

    If there are no arguments, the return value is `1`.

    Parameters:
      `x` - The argument(s).
    Returns:
      The product of the given numbers.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.3

  - ### sum

    public static Aprational sum(Aprational... x) throws ApfloatRuntimeException
    Sum of numbers. This method may perform significantly better than simply adding the numbers sequentially.

    If there are no arguments, the return value is `0`.

    Parameters:
      `x` - The argument(s).
    Returns:
      The sum of the given numbers.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.3

  - ### continuedFraction

    public static Apint[] continuedFraction(Aprational x, int n)
    Generates the first `n` terms in the continued fraction representation of `x`.

    Note that the result length might be less than `n`, depending on the input value.

    Parameters:
      `x` - The number whose continued fraction terms should be generated.
      `n` - The maximum number of terms to generate.
    Returns:
      The continued fraction.
    Throws:
      `IllegalArgumentException` - If `n` is less than one.
    Since:
      1.12.0

  - ### convergents

    public static Aprational[] convergents(Aprational x, int n)
    Generates the first `n` convergents corresponding to the continued fraction of `x`.

    Note that the result length might be less than `n`, depending on the input value.

    Parameters:
      `x` - The number whose continued fraction convergents should be generated.
      `n` - The maximum number of convergents to generate.
    Returns:
      The convergents.
    Throws:
      `IllegalArgumentException` - If `n` is less than one.
    Since:
      1.12.0

  - ### max

    public static Aprational max(Aprational x, Aprational y) throws ApfloatRuntimeException
    Returns the greater of the two values.
    Parameters:
      `x` - An argument.
      `y` - Another argument.
    Returns:
      The greater of the two values.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.9.0

  - ### min

    public static Aprational min(Aprational x, Aprational y) throws ApfloatRuntimeException
    Returns the smaller of the two values.
    Parameters:
      `x` - An argument.
      `y` - Another argument.
    Returns:
      The smaller of the two values.
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.9.0

  - ### doubleFactorial

    public static Aprational doubleFactorial(long n) throws ArithmeticException, NumberFormatException, ApfloatRuntimeException
    Double factorial function. Uses the default radix.
    Parameters:
      `n` - The number whose double factorial is to be calculated. Negative values should be odd.
    Returns:
      `n!!`
    Throws:
      `ArithmeticException` - If `n` is negative and even.
      `NumberFormatException` - If the default radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.15.0

  - ### doubleFactorial

    public static Aprational doubleFactorial(long n, int radix) throws ArithmeticException, NumberFormatException, ApfloatRuntimeException
    Double factorial function. Returns a number in the specified radix.
    Parameters:
      `n` - The number whose double factorial is to be calculated. Negative values should be odd.
      `radix` - The radix to use.
    Returns:
      `n!!`
    Throws:
      `ArithmeticException` - If `n` is negative and even.
      `NumberFormatException` - If the radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.15.0

  - ### binomial

    public static Aprational binomial(Aprational n, Aprational k) throws ArithmeticException, ApfloatRuntimeException
    Binomial coefficient.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
    Returns:
      ( n k )
    Throws:
      `ArithmeticException` - If the result is not finite or not a rational number.
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### pochhammer

    public static Aprational pochhammer(Aprational x, Apint n)
    Pochhammer symbol.

    Parameters:
      `x` - The first argument.
      `n` - The second argument.
    Returns:
      `(x)n`
    Since:
      1.13.0
    Implementation notes:
      This implementation is slow, meaning that it isn't a fast algorithm. The asymptotic complexity is at least O(n2log n) and it is impractically slow beyond a precision of a few thousand digits. At the time of implementation no generic fast algorithm is known for the pochhammer symbol.

  - ### bernoulli

    public static Aprational bernoulli(long n) throws IllegalArgumentException, ApfloatRuntimeException
    Returns the specified Bernoulli number. The default radix is used.
    Parameters:
      `n` - The argument.
    Returns:
      The Bernoulli number `Bn`.
    Throws:
      `IllegalArgumentException` - If `n < 0`.
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### bernoulli

    public static Aprational bernoulli(long n, int radix) throws IllegalArgumentException, NumberFormatException, ApfloatRuntimeException
    Returns the specified Bernoulli number in the given radix.
    Parameters:
      `n` - The argument.
      `radix` - The radix.
    Returns:
      The Bernoulli number `Bn`.
    Throws:
      `IllegalArgumentException` - If `n < 0`.
      `NumberFormatException` - If the radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### harmonicNumber

    public static Aprational harmonicNumber(Apint n) throws ArithmeticException, ApfloatRuntimeException
    Harmonic number.

    Parameters:
      `n` - The argument.
    Returns:
      Hn
    Throws:
      `ArithmeticException` - If `n` is negative.
      `ApfloatRuntimeException`
    Since:
      1.14.0

  - ### harmonicNumber

    public static Aprational harmonicNumber(Apint n, Apint r) throws ArithmeticException, ApfloatRuntimeException
    Generalized harmonic number.

    Parameters:
      `n` - The first argument.
      `r` - The second argument.
    Returns:
      Hn(r)
    Throws:
      `ArithmeticException` - If `n` is negative and `r` is positive.
      `ApfloatRuntimeException`
    Since:
      1.14.0