# Class ApintMath

java.lang.Object
org.apfloat.ApintMath

public class ApintMath extends Object
Various mathematical functions for arbitrary precision integers.

Version:
  1.16.0
Author:
  Mikko Tommila

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Apint`
  `abs(Apint x)`
  Absolute value.
  `static Apint`
  `binomial(long n, long k)`
  Binomial coefficient.
  `static Apint`
  `binomial(long n, long k, int radix)`
  Binomial coefficient.
  `static Apint`
  `binomial(Apint n, Apint k)`
  Binomial coefficient.
  `static Apint[]`
  `cbrt(Apint x)`
  Cube root and remainder.
  `static Apint`
  `copySign(Apint x, Apint y)`
  Copy sign from one argument to another.
  `static Apint[]`
  `div(Apint x, Apint y)`
  Quotient and remainder.
  `static Apint`
  `doubleFactorial(long n)`
  Double factorial function.
  `static Apint`
  `doubleFactorial(long n, int radix)`
  Double factorial function.
  `static Apint`
  `factorial(long n)`
  Factorial function.
  `static Apint`
  `factorial(long n, int radix)`
  Factorial function.
  `static Apint`
  `gcd(Apint a, Apint b)`
  Greatest common divisor.
  `static Apint`
  `lcm(Apint a, Apint b)`
  Least common multiple.
  `static Apint`
  `max(Apint x, Apint y)`
  Returns the greater of the two values.
  `static Apint`
  `min(Apint x, Apint y)`
  Returns the smaller of the two values.
  `static Apint`
  `modMultiply(Apint a, Apint b, Apint m)`
  Modular multiplication.
  `static Apint`
  `modPow(Apint a, Apint b, Apint m)`
  Modular power.
  `static Apint`
  `negate(Apint x)`
  Deprecated.
  Use `Apint.negate()`.
  `static Apint`
  `pow(Apint x, long n)`
  Integer power.
  `static Apint`
  `product(Apint... x)`
  Product of numbers.
  `static Apint`
  `random(long digits)`
  Generates a random number.
  `static Apint`
  `random(long digits, int radix)`
  Generates a random number.
  `static Apint[]`
  `root(Apint x, long n)`
  Positive integer root and remainder.
  `static Apint`
  `scale(Apint x, long scale)`
  Multiply by a power of the radix.
  `static Apint[]`
  `sqrt(Apint x)`
  Square root and remainder.
  `static Apint`
  `stirlingS1(long n, long k)`
  Stirling number of the first kind.
  `static Apint`
  `stirlingS1(long n, long k, int radix)`
  Stirling number of the first kind.
  `static Apint`
  `stirlingS1(Apint n, Apint k)`
  Stirling number of the first kind.
  `static Apint`
  `stirlingS2(long n, long k)`
  Stirling number of the second kind.
  `static Apint`
  `stirlingS2(long n, long k, int radix)`
  Stirling number of the second kind.
  `static Apint`
  `stirlingS2(Apint n, Apint k)`
  Stirling number of the second kind.
  `static Apint`
  `sum(Apint... 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 Apint pow(Apint 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`

  - ### sqrt

    public static Apint[] sqrt(Apint x) throws ArithmeticException, ApfloatRuntimeException
    Square root and remainder.
    Parameters:
      `x` - The argument.
    Returns:
      An array of two apints: `[q, r]`, where `q2 + r = x`.
    Throws:
      `ArithmeticException` - If `x` is negative.
      `ApfloatRuntimeException`

  - ### cbrt

    public static Apint[] cbrt(Apint x) throws ApfloatRuntimeException
    Cube root and remainder.
    Parameters:
      `x` - The argument.
    Returns:
      An array of two apints: `[q, r]`, where `q3 + r = x`.
    Throws:
      `ApfloatRuntimeException`

  - ### root

    public static Apint[] root(Apint x, long n) throws ArithmeticException, ApfloatRuntimeException
    Positive integer root and remainder.

    Returns the `n`:th root of `x`, that is `x1/n`, rounded towards zero.

    Parameters:
      `x` - The argument.
      `n` - Which root to take.
    Returns:
      An array of two apints: `[q, r]`, where `qn + r = x`.
    Throws:
      `ArithmeticException` - If `n` and `x` are zero, or `x` is negative and `n` is even.
      `ApfloatRuntimeException`

  - ### negate

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

  - ### abs

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

  - ### copySign

    public static Apint copySign(Apint x, Apint 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 Apint scale(Apint x, long scale) throws ApfloatRuntimeException
    Multiply by a power of the radix. Any rounding will occur towards zero.
    Parameters:
      `x` - The argument.
      `scale` - The scaling factor.
    Returns:
      `x * x.radix()scale`.
    Throws:
      `ApfloatRuntimeException`

  - ### div

    public static Apint[] div(Apint x, Apint y) throws ArithmeticException, ApfloatRuntimeException
    Quotient and remainder.
    Parameters:
      `x` - The dividend.
      `y` - The divisor.
    Returns:
      An array of two apints: `[quotient, remainder]`, that is `[x / y, x % y]`.
    Throws:
      `ArithmeticException` - In case the divisor is zero.
      `ApfloatRuntimeException`

  - ### gcd

    public static Apint gcd(Apint a, Apint b) throws ApfloatRuntimeException
    Greatest common divisor. This method returns a positive number even if one of `a` and `b` is negative.
    Parameters:
      `a` - First argument.
      `b` - Second argument.
    Returns:
      Greatest common divisor of `a` and `b`.
    Throws:
      `ApfloatRuntimeException`

  - ### lcm

    public static Apint lcm(Apint a, Apint b) throws ApfloatRuntimeException
    Least common multiple. This method returns a positive number even if one of `a` and `b` is negative.
    Parameters:
      `a` - First argument.
      `b` - Second argument.
    Returns:
      Least common multiple of `a` and `b`.
    Throws:
      `ApfloatRuntimeException`

  - ### modMultiply

    public static Apint modMultiply(Apint a, Apint b, Apint m) throws ApfloatRuntimeException
    Modular multiplication. Returns `a * b % m`
    Parameters:
      `a` - First argument.
      `b` - Second argument.
      `m` - Modulus.
    Returns:
      `a * b mod m`
    Throws:
      `ApfloatRuntimeException`

  - ### modPow

    public static Apint modPow(Apint a, Apint b, Apint m) throws ArithmeticException, ApfloatRuntimeException
    Modular power.
    Parameters:
      `a` - Base.
      `b` - Exponent.
      `m` - Modulus.
    Returns:
      `ab mod m`
    Throws:
      `ArithmeticException` - If the exponent is negative but the GCD of `a` and `m` is not 1 and the modular inverse does not exist.
      `ApfloatRuntimeException`

  - ### factorial

    public static Apint factorial(long n) throws ArithmeticException, NumberFormatException, ApfloatRuntimeException
    Factorial function. Uses the default radix.
    Parameters:
      `n` - The number whose factorial is to be calculated. Should be non-negative.
    Returns:
      `n!`
    Throws:
      `ArithmeticException` - If `n` is negative.
      `NumberFormatException` - If the default radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.1

  - ### factorial

    public static Apint factorial(long n, int radix) throws ArithmeticException, NumberFormatException, ApfloatRuntimeException
    Factorial function. Returns a number in the specified radix.
    Parameters:
      `n` - The number whose factorial is to be calculated. Should be non-negative.
      `radix` - The radix to use.
    Returns:
      `n!`
    Throws:
      `ArithmeticException` - If `n` is negative.
      `NumberFormatException` - If the radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.1

  - ### doubleFactorial

    public static Apint 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. Should be non-negative.
    Returns:
      `n!!`
    Throws:
      `ArithmeticException` - If `n` is negative.
      `NumberFormatException` - If the default radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.14.0

  - ### doubleFactorial

    public static Apint 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. Should be non-negative.
      `radix` - The radix to use.
    Returns:
      `n!!`
    Throws:
      `ArithmeticException` - If `n` is negative.
      `NumberFormatException` - If the radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.14.0

  - ### binomial

    public static Apint binomial(long n, long k) throws ApfloatRuntimeException
    Binomial coefficient. Uses the default radix.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
    Returns:
      ( n k )
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### binomial

    public static Apint binomial(long n, long k, int radix) throws NumberFormatException, ApfloatRuntimeException
    Binomial coefficient. Uses the specified radix.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
      `radix` - The radix.
    Returns:
      ( n k )
    Throws:
      `NumberFormatException` - If the radix is not valid.
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### binomial

    public static Apint binomial(Apint n, Apint k) throws ApfloatRuntimeException
    Binomial coefficient.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
    Returns:
      ( n k )
    Throws:
      `ApfloatRuntimeException`
    Since:
      1.11.0

  - ### stirlingS1

    public static Apint stirlingS1(long n, long k) throws IllegalArgumentException, ApfloatRuntimeException
    Stirling number of the first kind. Uses the default radix.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
    Returns:
      s(n, k)
    Throws:
      `IllegalArgumentException` - In case n or k is negative.
      `ApfloatRuntimeException`
    Since:
      1.16.0

  - ### stirlingS1

    public static Apint stirlingS1(long n, long k, int radix) throws NumberFormatException, IllegalArgumentException, ApfloatRuntimeException
    Stirling number of the first kind. Uses the specified radix.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
      `radix` - The radix.
    Returns:
      s(n, k)
    Throws:
      `NumberFormatException` - If the radix is not valid.
      `IllegalArgumentException` - In case n or k is negative.
      `ApfloatRuntimeException`
    Since:
      1.16.0

  - ### stirlingS1

    public static Apint stirlingS1(Apint n, Apint k) throws IllegalArgumentException, ApfloatRuntimeException
    Stirling number of the first kind.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
    Returns:
      s(n, k)
    Throws:
      `IllegalArgumentException` - In case n or k is negative.
      `ApfloatRuntimeException`
    Since:
      1.16.0

  - ### stirlingS2

    public static Apint stirlingS2(long n, long k) throws IllegalArgumentException, ApfloatRuntimeException
    Stirling number of the second kind. Uses the default radix.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
    Returns:
      S(n, k)
    Throws:
      `IllegalArgumentException` - In case n or k is negative.
      `ApfloatRuntimeException`
    Since:
      1.16.0

  - ### stirlingS2

    public static Apint stirlingS2(long n, long k, int radix) throws NumberFormatException, IllegalArgumentException, ApfloatRuntimeException
    Stirling number of the second kind. Uses the specified radix.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
      `radix` - The radix.
    Returns:
      S(n, k)
    Throws:
      `NumberFormatException` - If the radix is not valid.
      `IllegalArgumentException` - In case n or k is negative.
      `ApfloatRuntimeException`
    Since:
      1.16.0

  - ### stirlingS2

    public static Apint stirlingS2(Apint n, Apint k) throws IllegalArgumentException, ApfloatRuntimeException
    Stirling number of the second kind.
    Parameters:
      `n` - The first argument.
      `k` - The second argument.
    Returns:
      S(n, k)
    Throws:
      `IllegalArgumentException` - In case n or k is negative.
      `ApfloatRuntimeException`
    Since:
      1.16.0

  - ### product

    public static Apint product(Apint... 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 Apint sum(Apint... x) throws ApfloatRuntimeException
    Sum of numbers.

    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

  - ### random

    public static Apint random(long digits)
    Generates a random number. Uses the default radix. Returned values are chosen pseudorandomly with (approximately) uniform distribution from the range `0 ≤ x < radixdigits`. The generated random numbers may have leading zeros and may thus not always have exactly the requested number of digis.
    Parameters:
      `digits` - Maximum number of digits in the number.
    Returns:
      A random number, uniformly distributed between `0 ≤ x < radixdigits`.
    Throws:
      `NumberFormatException` - If the default radix is not valid.
      `IllegalArgumentException` - In case the number of specified digits is invalid.
    Since:
      1.9.0

  - ### random

    public static Apint random(long digits, int radix)
    Generates a random number. Returned values are chosen pseudorandomly with (approximately) uniform distribution from the range `0 ≤ x < radixdigits`. The generated random numbers may have leading zeros and may thus not always have exactly the requested number of digis.
    Parameters:
      `digits` - Maximum number of digits in the number.
      `radix` - The radix in which the number should be generated.
    Returns:
      A random number, uniformly distributed between `0 ≤ x < radixdigits`, in base `radix`.
    Throws:
      `NumberFormatException` - If the radix is not valid.
      `IllegalArgumentException` - In case the number of specified digits is invalid.
    Since:
      1.9.0

  - ### max

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

  - ### min

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