Added in API level 1

BigInteger

open class BigInteger : Number, Comparable<BigInteger!>

kotlin.Any
↳	kotlin.Number
	↳	java.math.BigInteger

Immutable arbitrary-precision integers. All operations behave as if BigIntegers were represented in two's-complement notation (like Java's primitive integer types). BigInteger provides analogues to all of Java's primitive integer operators, and all relevant methods from java.lang.Math. Additionally, BigInteger provides operations for modular arithmetic, GCD calculation, primality testing, prime generation, bit manipulation, and a few other miscellaneous operations.

Semantics of arithmetic operations exactly mimic those of Java's integer arithmetic operators, as defined in The Java Language Specification. For example, division by zero throws an ArithmeticException, and division of a negative by a positive yields a negative (or zero) remainder.

Semantics of shift operations extend those of Java's shift operators to allow for negative shift distances. A right-shift with a negative shift distance results in a left shift, and vice-versa. The unsigned right shift operator (>>>) is omitted since this operation only makes sense for a fixed sized word and not for a representation conceptually having an infinite number of leading virtual sign bits.

Semantics of bitwise logical operations exactly mimic those of Java's bitwise integer operators. The binary operators (and, or, xor) implicitly perform sign extension on the shorter of the two operands prior to performing the operation.

Comparison operations perform signed integer comparisons, analogous to those performed by Java's relational and equality operators.

Modular arithmetic operations are provided to compute residues, perform exponentiation, and compute multiplicative inverses. These methods always return a non-negative result, between 0 and (modulus - 1), inclusive.

Bit operations operate on a single bit of the two's-complement representation of their operand. If necessary, the operand is sign-extended so that it contains the designated bit. None of the single-bit operations can produce a BigInteger with a different sign from the BigInteger being operated on, as they affect only a single bit, and the arbitrarily large abstraction provided by this class ensures that conceptually there are infinitely many "virtual sign bits" preceding each BigInteger.

For the sake of brevity and clarity, pseudo-code is used throughout the descriptions of BigInteger methods. The pseudo-code expression (i + j) is shorthand for "a BigInteger whose value is that of the BigInteger i plus that of the BigInteger j." The pseudo-code expression (i == j) is shorthand for "true if and only if the BigInteger i represents the same value as the BigInteger j." Other pseudo-code expressions are interpreted similarly.

All methods and constructors in this class throw NullPointerException when passed a null object reference for any input parameter. BigInteger must support values in the range -2Integer.MAX_VALUE (exclusive) to +2Integer.MAX_VALUE (exclusive) and may support values outside of that range. An ArithmeticException is thrown when a BigInteger constructor or method would generate a value outside of the supported range. The range of probable prime values is limited and may be less than the full supported positive range of BigInteger. The range must be at least 1 to 2500000000.

Summary

Public constructors
`BigInteger(val: ByteArray!)` Translates a byte array containing the two's-complement binary representation of a BigInteger into a BigInteger.
`BigInteger(val: ByteArray!, off: Int, len: Int)` Translates a byte sub-array containing the two's-complement binary representation of a BigInteger into a BigInteger.
`BigInteger(signum: Int, magnitude: ByteArray!)` Translates the sign-magnitude representation of a BigInteger into a BigInteger.
`BigInteger(signum: Int, magnitude: ByteArray!, off: Int, len: Int)` Translates the sign-magnitude representation of a BigInteger into a BigInteger.
`BigInteger(bitLength: Int, certainty: Int, rnd: Random)` Constructs a randomly generated positive BigInteger that is probably prime, with the specified bitLength.
`BigInteger(numBits: Int, rnd: Random)` Constructs a randomly generated BigInteger, uniformly distributed over the range 0 to (2`numBits` - 1), inclusive.
`BigInteger(val: String)` Translates the decimal String representation of a BigInteger into a BigInteger.
`BigInteger(val: String, radix: Int)` Translates the String representation of a BigInteger in the specified radix into a BigInteger.

Public methods
open BigInteger	`abs()` Returns a BigInteger whose value is the absolute value of this BigInteger.
open BigInteger	`add(val: BigInteger)` Returns a BigInteger whose value is `(this + val)`.
open BigInteger	`and(val: BigInteger)` Returns a BigInteger whose value is `(this & val)`.
open BigInteger	`andNot(val: BigInteger)` Returns a BigInteger whose value is `(this & ~val)`.
open Int	`bitCount()` Returns the number of bits in the two's complement representation of this BigInteger that differ from its sign bit.
open Int	`bitLength()` Returns the number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit.
open Byte	`byteValueExact()` Converts this `BigInteger` to a `byte`, checking for lost information.
open BigInteger	`clearBit(n: Int)` Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit cleared.
open Int	`compareTo(other: BigInteger)` Compares this BigInteger with the specified BigInteger.
open BigInteger	`divide(val: BigInteger)` Returns a BigInteger whose value is `(this / val)`.
open Array<BigInteger!>	`divideAndRemainder(val: BigInteger)` Returns an array of two BigIntegers containing `(this / val)` followed by `(this % val)`.
open Boolean	`equals(other: Any?)` Compares this BigInteger with the specified Object for equality.
open BigInteger	`flipBit(n: Int)` Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit flipped.
open BigInteger	`gcd(val: BigInteger)` Returns a BigInteger whose value is the greatest common divisor of `abs(this)` and `abs(val)`.
open Int	`getLowestSetBit()` Returns the index of the rightmost (lowest-order) one bit in this BigInteger (the number of zero bits to the right of the rightmost one bit).
open Int	`hashCode()` Returns the hash code for this BigInteger.
open Int	`intValueExact()` Converts this `BigInteger` to an `int`, checking for lost information.
open Boolean	`isProbablePrime(certainty: Int)` Returns `true` if this BigInteger is probably prime, `false` if it's definitely composite.
open Long	`longValueExact()` Converts this `BigInteger` to a `long`, checking for lost information.
open BigInteger	`max(val: BigInteger)` Returns the maximum of this BigInteger and `val`.
open BigInteger	`min(val: BigInteger)` Returns the minimum of this BigInteger and `val`.
open BigInteger	`mod(m: BigInteger)` Returns a BigInteger whose value is `(this mod m`).
open BigInteger	`modInverse(m: BigInteger)` Returns a BigInteger whose value is `(this`-1 `mod m)`.
open BigInteger	`modPow(exponent: BigInteger, m: BigInteger)` Returns a BigInteger whose value is `(thisexponent mod m)`.
open BigInteger	`multiply(val: BigInteger)` Returns a BigInteger whose value is `(this * val)`.
open BigInteger	`negate()` Returns a BigInteger whose value is `(-this)`.
open BigInteger	`nextProbablePrime()` Returns the first integer greater than this `BigInteger` that is probably prime.
open BigInteger	`not()` Returns a BigInteger whose value is `(~this)`.
open BigInteger	`or(val: BigInteger)` Returns a BigInteger whose value is `(this \| val)`.
open BigInteger	`pow(exponent: Int)` Returns a BigInteger whose value is `(thisexponent)`.
open static BigInteger	`probablePrime(bitLength: Int, rnd: Random)` Returns a positive BigInteger that is probably prime, with the specified bitLength.
open BigInteger	`remainder(val: BigInteger)` Returns a BigInteger whose value is `(this % val)`.
open BigInteger	`setBit(n: Int)` Returns a BigInteger whose value is equivalent to this BigInteger with the designated bit set.
open BigInteger	`shiftLeft(n: Int)` Returns a BigInteger whose value is `(this << n)`.
open BigInteger	`shiftRight(n: Int)` Returns a BigInteger whose value is `(this >> n)`.
open Short	`shortValueExact()` Converts this `BigInteger` to a `short`, checking for lost information.
open Int	`signum()` Returns the signum function of this BigInteger.
open BigInteger	`sqrt()` Returns the integer square root of this BigInteger.
open Array<BigInteger!>	`sqrtAndRemainder()` Returns an array of two BigIntegers containing the integer square root `s` of `this` and its remainder `this - s*s`, respectively.
open BigInteger	`subtract(val: BigInteger)` Returns a BigInteger whose value is `(this - val)`.
open Boolean	`testBit(n: Int)` Returns `true` if and only if the designated bit is set.
open ByteArray!	`toByteArray()` Returns a byte array containing the two's-complement representation of this BigInteger.
open Double	`toDouble()` Converts this BigInteger to a `double`.
open Float	`toFloat()` Converts this BigInteger to a `float`.
open Int	`toInt()` Converts this BigInteger to an `int`.
open Long	`toLong()` Converts this BigInteger to a `long`.
open String	`toString()` Returns the decimal String representation of this BigInteger.
open String	`toString(radix: Int)` Returns the String representation of this BigInteger in the given radix.
open static BigInteger	`valueOf(val: Long)` Returns a BigInteger whose value is equal to that of the specified `long`.
open BigInteger	`xor(val: BigInteger)` Returns a BigInteger whose value is `(this ^ val)`.

Properties
static BigInteger	`ONE` The BigInteger constant one.
static BigInteger	`TEN` The BigInteger constant ten.
static BigInteger	`TWO` The BigInteger constant two.
static BigInteger	`ZERO` The BigInteger constant zero.

Public constructors

BigInteger

Added in API level 1

BigInteger(val: ByteArray!)

Translates a byte array containing the two's-complement binary representation of a BigInteger into a BigInteger. The input array is assumed to be in big-endian byte-order: the most significant byte is in the zeroth element. The val array is assumed to be unchanged for the duration of the constructor call.

Parameters
`val`	ByteArray!: big-endian two's-complement binary representation of a BigInteger.

Exceptions
`java.lang.NumberFormatException`	`val` is zero bytes long.

BigInteger

Added in API level 33

BigInteger(
    val: ByteArray!, 
    off: Int, 
    len: Int)

Translates a byte sub-array containing the two's-complement binary representation of a BigInteger into a BigInteger. The sub-array is specified via an offset into the array and a length. The sub-array is assumed to be in big-endian byte-order: the most significant byte is the element at index off. The val array is assumed to be unchanged for the duration of the constructor call. An IndexOutOfBoundsException is thrown if the length of the array val is non-zero and either off is negative, len is negative, or off+len is greater than the length of val.

Parameters
`val`	ByteArray!: byte array containing a sub-array which is the big-endian two's-complement binary representation of a BigInteger.
`off`	Int: the start offset of the binary representation.
`len`	Int: the number of bytes to use.

Exceptions
`java.lang.IndexOutOfBoundsException`	if the provided array offset and length would cause an index into the byte array to be negative or greater than or equal to the array length.
`java.lang.NumberFormatException`	`val` is zero bytes long.

BigInteger

Added in API level 1

BigInteger(
    signum: Int, 
    magnitude: ByteArray!)

Parameters
`signum`	Int: signum of the number (-1 for negative, 0 for zero, 1 for positive).
`magnitude`	ByteArray!: big-endian binary representation of the magnitude of the number.

Exceptions
`java.lang.NumberFormatException`	`signum` is not one of the three legal values (-1, 0, and 1), or `signum` is 0 and `magnitude` contains one or more non-zero bytes.

BigInteger

Added in API level 33

BigInteger(
    signum: Int, 
    magnitude: ByteArray!, 
    off: Int, 
    len: Int)

Translates the sign-magnitude representation of a BigInteger into a BigInteger. The sign is represented as an integer signum value: -1 for negative, 0 for zero, or 1 for positive. The magnitude is a sub-array of a byte array in big-endian byte-order: the most significant byte is the element at index off. A zero value of the length len is permissible, and will result in a BigInteger value of 0, whether signum is -1, 0 or 1. The magnitude array is assumed to be unchanged for the duration of the constructor call. An IndexOutOfBoundsException is thrown if the length of the array magnitude is non-zero and either off is negative, len is negative, or off+len is greater than the length of magnitude.

Parameters
`signum`	Int: signum of the number (-1 for negative, 0 for zero, 1 for positive).
`magnitude`	ByteArray!: big-endian binary representation of the magnitude of the number.
`off`	Int: the start offset of the binary representation.
`len`	Int: the number of bytes to use.

Exceptions
`java.lang.IndexOutOfBoundsException`	if the provided array offset and length would cause an index into the byte array to be negative or greater than or equal to the array length.
`java.lang.NumberFormatException`	`signum` is not one of the three legal values (-1, 0, and 1), or `signum` is 0 and `magnitude` contains one or more non-zero bytes.

BigInteger

Added in API level 1

BigInteger(
    bitLength: Int, 
    certainty: Int, 
    rnd: Random)

Constructs a randomly generated positive BigInteger that is probably prime, with the specified bitLength.

Parameters
`bitLength`	Int: bitLength of the returned BigInteger.
`certainty`	Int: a measure of the uncertainty that the caller is willing to tolerate. The probability that the new BigInteger represents a prime number will exceed (1 - 1/2`certainty`). The execution time of this constructor is proportional to the value of this parameter.
`rnd`	Random: source of random bits used to select candidates to be tested for primality.

Exceptions
`java.lang.ArithmeticException`	`bitLength < 2` or `bitLength` is too large.

See Also

#bitLength()

BigInteger

Added in API level 1

BigInteger(
    numBits: Int, 
    rnd: Random)

Constructs a randomly generated BigInteger, uniformly distributed over the range 0 to (2numBits - 1), inclusive. The uniformity of the distribution assumes that a fair source of random bits is provided in rnd. Note that this constructor always constructs a non-negative BigInteger.

Parameters
`numBits`	Int: maximum bitLength of the new BigInteger.
`rnd`	Random: source of randomness to be used in computing the new BigInteger.

Exceptions
`java.lang.IllegalArgumentException`	`numBits` is negative.

See Also

#bitLength()

BigInteger

Added in API level 1

BigInteger(val: String)

Translates the decimal String representation of a BigInteger into a BigInteger. The String representation consists of an optional minus or plus sign followed by a sequence of one or more decimal digits. The character-to-digit mapping is provided by Character.digit. The String may not contain any extraneous characters (whitespace, for example).

Parameters
`val`	String: decimal String representation of BigInteger.

Exceptions
`java.lang.NumberFormatException`	`val` is not a valid representation of a BigInteger.

BigInteger

Added in API level 1

BigInteger(
    val: String, 
    radix: Int)

Translates the String representation of a BigInteger in the specified radix into a BigInteger. The String representation consists of an optional minus or plus sign followed by a sequence of one or more digits in the specified radix. The character-to-digit mapping is provided by Character.digit. The String may not contain any extraneous characters (whitespace, for example).

Parameters
`val`	String: String representation of BigInteger.
`radix`	Int: radix to be used in interpreting `val`.

Exceptions
`java.lang.NumberFormatException`	`val` is not a valid representation of a BigInteger in the specified radix, or `radix` is outside the range from `Character.MIN_RADIX` to `Character.MAX_RADIX`, inclusive.

Public methods

abs

Added in API level 1

open fun abs(): BigInteger

Returns a BigInteger whose value is the absolute value of this BigInteger.

Return
`BigInteger`	`abs(this)`

add

Added in API level 1

open fun add(val: BigInteger): BigInteger

Returns a BigInteger whose value is (this + val).

Parameters
`val`	BigInteger: value to be added to this BigInteger.

Return
`BigInteger`	`this + val`

and

Added in API level 1

open fun and(val: BigInteger): BigInteger

Returns a BigInteger whose value is (this & val). (This method returns a negative BigInteger if and only if this and val are both negative.)

Parameters
`val`	BigInteger: value to be AND'ed with this BigInteger.

Return
`BigInteger`	`this & val`

andNot

Added in API level 1

open fun andNot(val: BigInteger): BigInteger

Returns a BigInteger whose value is (this & ~val). This method, which is equivalent to and(val.not()), is provided as a convenience for masking operations. (This method returns a negative BigInteger if and only if this is negative and val is positive.)

Parameters
`val`	BigInteger: value to be complemented and AND'ed with this BigInteger.

Return
`BigInteger`	`this & ~val`

bitCount

Added in API level 1

open fun bitCount(): Int

Returns the number of bits in the two's complement representation of this BigInteger that differ from its sign bit. This method is useful when implementing bit-vector style sets atop BigIntegers.

Return
`Int`	number of bits in the two's complement representation of this BigInteger that differ from its sign bit.

bitLength

Added in API level 1

open fun bitLength(): Int

Returns the number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit. For positive BigIntegers, this is equivalent to the number of bits in the ordinary binary representation. For zero this method returns 0. (Computes (ceil(log2(this < 0 ? -this : this+1))).)

Return
`Int`	number of bits in the minimal two's-complement representation of this BigInteger, excluding a sign bit.

byteValueExact

Added in API level 31

open fun byteValueExact(): Byte