Added in API level 1

BigInteger

open class BigInteger : Number, Comparable<BigInteger!>, Serializable

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

An immutable arbitrary-precision signed integer.

Fast Cryptography

This implementation is efficient for operations traditionally used in cryptography, such as the generation of large prime numbers and computation of the modular inverse.

Slow Two's Complement Bitwise Operations

This API includes operations for bitwise operations in two's complement representation. Two's complement is not the internal representation used by this implementation, so such methods may be inefficient. Use for high-performance bitwise operations on arbitrarily-large sequences of bits.

Summary

Public constructors
`<init>(numBits: Int, random: Random)` Constructs a random non-negative `BigInteger` instance in the range `[0, pow(2, numBits)-1]`.
`<init>(bitLength: Int, certainty: Int, random: Random)` Constructs a random `BigInteger` instance in the range `[0, pow(2, bitLength)-1]` which is probably prime.
`<init>(value: String)` Constructs a new `BigInteger` by parsing `value`.
`<init>(value: String, radix: Int)` Constructs a new `BigInteger` instance by parsing `value`.
`<init>(signum: Int, magnitude: ByteArray!)` Constructs a new `BigInteger` instance with the given sign and magnitude.
`<init>(value: ByteArray!)` Constructs a new `BigInteger` from the given two's complement representation.

Public methods
open BigInteger	`abs()` Returns a `BigInteger` whose value is the absolute value of `this`.
open BigInteger	`add(value: BigInteger)` Returns a `BigInteger` whose value is `this + value`.
open BigInteger	`and(value: BigInteger)` Returns a `BigInteger` whose value is `this & value`.
open BigInteger	`andNot(value: BigInteger)` Returns a `BigInteger` whose value is `this & ~value`.
open Int	`bitCount()` Returns the number of bits in the two's complement representation of `this` which differ from the sign bit.
open Int	`bitLength()` Returns the length of the value's two's complement representation without leading zeros for positive numbers / without leading ones for negative values.
open BigInteger	`clearBit(n: Int)` Returns a `BigInteger` which has the same binary representation as `this` but with the bit at position n cleared.
open Int	`compareTo(other: BigInteger)` Compares this `BigInteger` with `value`.
open BigInteger	`divide(divisor: BigInteger)` Returns a `BigInteger` whose value is `this / divisor`.
open Array<BigInteger!>	`divideAndRemainder(divisor: BigInteger)` Returns a two element `BigInteger` array containing `this / divisor` at index 0 and `this % divisor` at index 1.
open Boolean	`equals(other: Any?)`
open BigInteger	`flipBit(n: Int)` Returns a `BigInteger` which has the same binary representation as `this` but with the bit at position n flipped.
open BigInteger	`gcd(value: BigInteger)` Returns a `BigInteger` whose value is greatest common divisor of `this` and `value`.
open Int	`getLowestSetBit()` Returns the position of the lowest set bit in the two's complement representation of this `BigInteger`.
open Int	`hashCode()`
open Boolean	`isProbablePrime(certainty: Int)` Tests whether this `BigInteger` is probably prime.
open BigInteger	`max(value: BigInteger)` Returns the maximum of this `BigInteger` and `value`.
open BigInteger	`min(value: BigInteger)` Returns the minimum of this `BigInteger` and `value`.
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 `1/this mod m`.
open BigInteger	`modPow(exponent: BigInteger, modulus: BigInteger)` Returns a `BigInteger` whose value is `pow(this, exponent) mod modulus`.
open BigInteger	`multiply(value: BigInteger)` Returns a `BigInteger` whose value is `this * value`.
open BigInteger	`negate()` Returns a `BigInteger` whose value is the `-this`.
open BigInteger	`nextProbablePrime()` Returns the smallest integer x > `this` which is probably prime as a `BigInteger` instance.
open BigInteger	`not()` Returns a `BigInteger` whose value is `~this`.
open BigInteger	`or(value: BigInteger)` Returns a `BigInteger` whose value is `this \| value`.
open BigInteger	`pow(exp: Int)` Returns a `BigInteger` whose value is `pow(this, exp)`.
open static BigInteger	`probablePrime(bitLength: Int, random: Random)` Returns a random positive `BigInteger` instance in the range `[0, pow(2, bitLength)-1]` which is probably prime.
open BigInteger	`remainder(divisor: BigInteger)` Returns a `BigInteger` whose value is `this % divisor`.
open BigInteger	`setBit(n: Int)` Returns a `BigInteger` which has the same binary representation as `this` but with the bit at position n 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 Int	`signum()` Returns the sign of this `BigInteger`.
open BigInteger	`subtract(value: BigInteger)` Returns a `BigInteger` whose value is `this - value`.
open Boolean	`testBit(n: Int)` Tests whether the bit at position n in `this` is set.
open ByteArray!	`toByteArray()` Returns the two's complement representation of this `BigInteger` in a byte array.
open Double	`toDouble()` Returns this `BigInteger` as a double.
open Float	`toFloat()` Returns this `BigInteger` as a float.
open Int	`toInt()` Returns this `BigInteger` as an int value.
open Long	`toLong()` Returns this `BigInteger` as a long value.
open String	`toString()` Returns a string representation of this `BigInteger` in decimal form.
open String	`toString(radix: Int)` Returns a string containing a string representation of this `BigInteger` with base radix.
open static BigInteger	`valueOf(value: Long)` Returns a `BigInteger` whose value is equal to `value`.
open BigInteger	`xor(value: BigInteger)` Returns a `BigInteger` whose value is `this ^ value`.

Properties
static BigInteger	`ONE` The `BigInteger` constant 1.
static BigInteger	`TEN` The `BigInteger` constant 10.
static BigInteger	`ZERO` The `BigInteger` constant 0.

Public constructors

<init>

Added in API level 1

BigInteger(
    numBits: Int, 
    random: Random)

Constructs a random non-negative BigInteger instance in the range [0, pow(2, numBits)-1].

Parameters
`numBits`	Int: maximum length of the new `BigInteger` in bits.
`random`	Random: is the random number generator to be used.

Exceptions
`java.lang.IllegalArgumentException`	if `numBits` < 0.

<init>

Added in API level 1

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

Constructs a random BigInteger instance in the range [0, pow(2, bitLength)-1] which is probably prime. The probability that the returned BigInteger is prime is greater than 1 - 1/2certainty).

Note: the Random argument is ignored if bitLength >= 16, where this implementation will use OpenSSL's BN_generate_prime_ex as a source of cryptographically strong pseudo-random numbers.

Parameters
`bitLength`	Int: length of the new `BigInteger` in bits.
`certainty`	Int: tolerated primality uncertainty.

Exceptions
`java.lang.ArithmeticException`	if `bitLength < 2`.

See Also

<init>

Added in API level 1

BigInteger(value: String)

Constructs a new BigInteger by parsing value. The string representation consists of an optional plus or minus sign followed by a non-empty sequence of decimal digits. Digits are interpreted as if by Character.digit(char,10).

Parameters
`value`	String: string representation of the new `BigInteger`.

Exceptions
`java.lang.NullPointerException`	if `value == null`.
`java.lang.NumberFormatException`	if `value` is not a valid representation of a `BigInteger`.

<init>

Added in API level 1

BigInteger(
    value: String, 
    radix: Int)

Constructs a new BigInteger instance by parsing value. The string representation consists of an optional plus or minus sign followed by a non-empty sequence of digits in the specified radix. Digits are interpreted as if by Character.digit(char, radix).

Parameters
`value`	String: string representation of the new `BigInteger`.
`radix`	Int: the base to be used for the conversion.

Exceptions
`java.lang.NullPointerException`	if `value == null`.
`java.lang.NumberFormatException`	if `value` is not a valid representation of a `BigInteger` or if `radix < Character.MIN_RADIX` or `radix > Character.MAX_RADIX`.

<init>

Added in API level 1

BigInteger(
    signum: Int, 
    magnitude: ByteArray!)

Constructs a new BigInteger instance with the given sign and magnitude.

Parameters
`signum`	Int: sign of the new `BigInteger` (-1 for negative, 0 for zero, 1 for positive).
`magnitude`	ByteArray!: magnitude of the new `BigInteger` with the most significant byte first.

Exceptions
`java.lang.NullPointerException`	if `magnitude == null`.
`java.lang.NumberFormatException`	if the sign is not one of -1, 0, 1 or if the sign is zero and the magnitude contains non-zero entries.

<init>

Added in API level 1

BigInteger(value: ByteArray!)

Constructs a new BigInteger from the given two's complement representation. The most significant byte is the entry at index 0. The most significant bit of this entry determines the sign of the new BigInteger instance. The array must be nonempty.

Parameters
`value`	ByteArray!: two's complement representation of the new `BigInteger`.

Exceptions
`java.lang.NullPointerException`	if `value == null`.
`java.lang.NumberFormatException`	if the length of `value` is zero.

Public methods

abs

Added in API level 1

open fun abs(): BigInteger

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

add

Added in API level 1

open fun add(value: BigInteger): BigInteger

Returns a BigInteger whose value is this + value.

and

Added in API level 1

open fun and(value: BigInteger): BigInteger

Returns a BigInteger whose value is this & value.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

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

Exceptions
`java.lang.NullPointerException`	if `value == null`.

andNot

Added in API level 1

open fun andNot(value: BigInteger): BigInteger

Returns a BigInteger whose value is this & ~value. Evaluating x.andNot(value) returns the same result as x.and(value.not()).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters
`value`	BigInteger: value to be not'ed and then and'ed with `this`.

Exceptions
`java.lang.NullPointerException`	if `value == null`.

bitCount

Added in API level 1

open fun bitCount(): Int

Returns the number of bits in the two's complement representation of this which differ from the sign bit. If this is negative, the result is equivalent to the number of bits set in the two's complement representation of -this - 1.

Use bitLength(0) to find the length of the binary value in bits.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

bitLength

Added in API level 1

open fun bitLength(): Int

Returns the length of the value's two's complement representation without leading zeros for positive numbers / without leading ones for negative values.

The two's complement representation of this will be at least bitLength() + 1 bits long.

The value will fit into an int if bitLength() < 32 or into a long if bitLength() < 64.

Return
`Int`	the length of the minimal two's complement representation for `this` without the sign bit.

clearBit

Added in API level 1

open fun clearBit(n: Int): BigInteger

Returns a BigInteger which has the same binary representation as this but with the bit at position n cleared. The result is equivalent to this & ~pow(2, n).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters
`n`	Int: position where the bit in `this` has to be cleared.

Exceptions
`java.lang.ArithmeticException`	if `n < 0`.

compareTo

Added in API level 1

open fun compareTo(other: BigInteger): Int

Compares this BigInteger with value. Returns -1 if this < value, 0 if this == value and 1 if this > value, .

Parameters
`o`	the object to be compared.
`value`	value to be compared with `this`.

Return
`Int`	a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object.

Exceptions
`java.lang.NullPointerException`	if `value == null`.
`java.lang.ClassCastException`	if the specified object's type prevents it from being compared to this object.

divide

Added in API level 1

open fun divide(divisor: BigInteger): BigInteger

Returns a BigInteger whose value is this / divisor.

Parameters
`divisor`	BigInteger: value by which `this` is divided.

Return
`BigInteger`	`this / divisor`.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `divisor == 0`.

divideAndRemainder

Added in API level 1

open fun divideAndRemainder(divisor: BigInteger): Array<BigInteger!>

Returns a two element BigInteger array containing this / divisor at index 0 and this % divisor at index 1.

Parameters
`divisor`	BigInteger: value by which `this` is divided.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `divisor == 0`.

See Also

#divide
#remainder

equals

Added in API level 1

open fun equals(other: Any?): Boolean

Parameters
`obj`	the reference object with which to compare.

Return
`Boolean`	`true` if this object is the same as the obj argument; `false` otherwise.

flipBit

Added in API level 1

open fun flipBit(n: Int): BigInteger

Returns a BigInteger which has the same binary representation as this but with the bit at position n flipped. The result is equivalent to this ^ pow(2, n).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters
`n`	Int: position where the bit in `this` has to be flipped.

Exceptions
`java.lang.ArithmeticException`	if `n < 0`.

gcd

Added in API level 1

open fun gcd(value: BigInteger): BigInteger

Returns a BigInteger whose value is greatest common divisor of this and value. If this == 0 and value == 0 then zero is returned, otherwise the result is positive.

Parameters
`value`	BigInteger: value with which the greatest common divisor is computed.

Exceptions
`java.lang.NullPointerException`	if `value == null`.

getLowestSetBit

Added in API level 1

open fun getLowestSetBit(): Int

Returns the position of the lowest set bit in the two's complement representation of this BigInteger. If all bits are zero (this==0) then -1 is returned as result.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

hashCode

Added in API level 1

open fun hashCode(): Int

Return
`Int`	a hash code value for this object.

isProbablePrime

Added in API level 1

open fun isProbablePrime(certainty: Int): Boolean

Tests whether this BigInteger is probably prime. If true is returned, then this is prime with a probability greater than 1 - 1/2certainty). If false is returned, then this is definitely composite. If the argument certainty <= 0, then this method returns true.

Parameters
`certainty`	Int: tolerated primality uncertainty.

Return
`Boolean`	`true`, if `this` is probably prime, `false` otherwise.

max

Added in API level 1

open fun max(value: BigInteger): BigInteger

Returns the maximum of this BigInteger and value.

Parameters
`value`	BigInteger: value to be used to compute the maximum with `this`

Exceptions
`java.lang.NullPointerException`	if `value == null`

min

Added in API level 1

open fun min(value: BigInteger): BigInteger

Returns the minimum of this BigInteger and value.

Parameters
`value`	BigInteger: value to be used to compute the minimum with `this`.

Exceptions
`java.lang.NullPointerException`	if `value == null`.

mod

Added in API level 1

open fun mod(m: BigInteger): BigInteger

Returns a BigInteger whose value is this mod m. The modulus m must be positive. The result is guaranteed to be in the interval [0, m) (0 inclusive, m exclusive). The behavior of this function is not equivalent to the behavior of the % operator defined for the built-in int's.

Parameters
`m`	BigInteger: the modulus.

Return
`BigInteger`	`this mod m`.

Exceptions
`java.lang.NullPointerException`	if `m == null`.
`java.lang.ArithmeticException`	if `m < 0`.

modInverse

Added in API level 1

open fun modInverse(m: BigInteger): BigInteger

Returns a BigInteger whose value is 1/this mod m. The modulus m must be positive. The result is guaranteed to be in the interval [0, m) (0 inclusive, m exclusive). If this is not relatively prime to m, then an exception is thrown.

Parameters
`m`	BigInteger: the modulus.

Exceptions
`java.lang.NullPointerException`	if `m == null`
`java.lang.ArithmeticException`	if `m < 0 or` if `this` is not relatively prime to `m`

modPow

Added in API level 1

open fun modPow(
    exponent: BigInteger, 
    modulus: BigInteger
): BigInteger

Returns a BigInteger whose value is pow(this, exponent) mod modulus. The modulus must be positive. The result is guaranteed to be in the interval [0, modulus). If the exponent is negative, then pow(this.modInverse(modulus), -exponent) mod modulus is computed. The inverse of this only exists if this is relatively prime to the modulus, otherwise an exception is thrown.

Exceptions
`java.lang.NullPointerException`	if `modulus == null` or `exponent == null`.
`java.lang.ArithmeticException`	if `modulus < 0` or if `exponent < 0` and not relatively prime to `modulus`.

multiply

Added in API level 1

open fun multiply(value: BigInteger): BigInteger

Returns a BigInteger whose value is this * value.

Exceptions
`java.lang.NullPointerException`	if `value == null`.

negate

Added in API level 1

open fun negate(): BigInteger

Returns a BigInteger whose value is the -this.

nextProbablePrime

Added in API level 1

open fun nextProbablePrime(): BigInteger

Returns the smallest integer x > this which is probably prime as a BigInteger instance. The probability that the returned BigInteger is prime is greater than 1 - 1/2100.

Return
`BigInteger`	smallest integer > `this` which is probably prime.

Exceptions
`java.lang.ArithmeticException`	if `this < 0`.

not

Added in API level 1

open fun not(): BigInteger

Returns a BigInteger whose value is ~this. The result of this operation is -this-1.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

or

Added in API level 1

open fun or(value: BigInteger): BigInteger

Returns a BigInteger whose value is this | value.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

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

Exceptions
`java.lang.NullPointerException`	if `value == null`.

pow

Added in API level 1

open fun pow(exp: Int): BigInteger

Returns a BigInteger whose value is pow(this, exp).

Exceptions
`java.lang.ArithmeticException`	if `exp < 0`.

probablePrime

Added in API level 1

open static fun probablePrime(
    bitLength: Int, 
    random: Random
): BigInteger

Returns a random positive BigInteger instance in the range [0, pow(2, bitLength)-1] which is probably prime. The probability that the returned BigInteger is prime is greater than 1 - 1/2100).

Parameters
`bitLength`	Int: length of the new `BigInteger` in bits.

Return
`BigInteger`	probably prime random `BigInteger` instance.

Exceptions
`java.lang.IllegalArgumentException`	if `bitLength < 2`.

remainder

Added in API level 1

open fun remainder(divisor: BigInteger): BigInteger

Returns a BigInteger whose value is this % divisor. Regarding signs this methods has the same behavior as the % operator on ints: the sign of the remainder is the same as the sign of this.

Parameters
`divisor`	BigInteger: value by which `this` is divided.

Exceptions
`java.lang.NullPointerException`	if `divisor == null`.
`java.lang.ArithmeticException`	if `divisor == 0`.

setBit

Added in API level 1

open fun setBit(n: Int): BigInteger

Returns a BigInteger which has the same binary representation as this but with the bit at position n set. The result is equivalent to this | pow(2, n).

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters
`n`	Int: position where the bit in `this` has to be set.

Exceptions
`java.lang.ArithmeticException`	if `n < 0`.

shiftLeft

Added in API level 1

open fun shiftLeft(n: Int): BigInteger

Returns a BigInteger whose value is this << n. The result is equivalent to this * pow(2, n) if n >= 0. The shift distance may be negative which means that this is shifted right. The result then corresponds to floor(this / pow(2, -n)).

Implementation Note: Usage of this method on negative values is not recommended as the current implementation is not efficient.

Parameters
`n`	Int: shift distance.

Return
`BigInteger`	`this << n` if `n >= 0`; `this >> (-n)`. otherwise

shiftRight

Added in API level 1

open fun shiftRight(n: Int): BigInteger

Returns a BigInteger whose value is this >> n. For negative arguments, the result is also negative. The shift distance may be negative which means that this is shifted left.

Implementation Note: Usage of this method on negative values is not recommended as the current implementation is not efficient.

Parameters
`n`	Int: shift distance

Return
`BigInteger`	`this >> n` if `n >= 0`; `this << (-n)` otherwise

signum

Added in API level 1

open fun signum(): Int

Returns the sign of this BigInteger.

Return
`Int`	`-1` if `this < 0`, `0` if `this == 0`, `1` if `this > 0`.

subtract

Added in API level 1

open fun subtract(value: BigInteger): BigInteger

Returns a BigInteger whose value is this - value.

testBit

Added in API level 1

open fun testBit(n: Int): Boolean

Tests whether the bit at position n in this is set. The result is equivalent to this & pow(2, n) != 0.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters
`n`	Int: position where the bit in `this` has to be inspected.

Exceptions
`java.lang.ArithmeticException`	if `n < 0`.

toByteArray

Added in API level 1

open fun toByteArray(): ByteArray!

Returns the two's complement representation of this BigInteger in a byte array.

toDouble

Added in API level 1

open fun toDouble(): Double

Returns this BigInteger as a double. If this is too big to be represented as a double, then Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY is returned. Note that not all integers in the range [-Double.MAX_VALUE, Double.MAX_VALUE] can be exactly represented as a double.

Return
`Double`	the numeric value represented by this object after conversion to type `double`.

toFloat

Added in API level 1

open fun toFloat(): Float

Returns this BigInteger as a float. If this is too big to be represented as a float, then Float.POSITIVE_INFINITY or Float.NEGATIVE_INFINITY is returned. Note that not all integers in the range [-Float.MAX_VALUE, Float.MAX_VALUE] can be exactly represented as a float.

Return
`Float`	the numeric value represented by this object after conversion to type `float`.

toInt

Added in API level 1

open fun toInt(): Int

Returns this BigInteger as an int value. If this is too big to be represented as an int, then this % (1 << 32) is returned.

Return
`Int`	the numeric value represented by this object after conversion to type `int`.

toLong

Added in API level 1

open fun toLong(): Long

Returns this BigInteger as a long value. If this is too big to be represented as a long, then this % pow(2, 64) is returned.

Return
`Long`	the numeric value represented by this object after conversion to type `long`.

toString

Added in API level 1

open fun toString(): String

Returns a string representation of this BigInteger in decimal form.

Return
`String`	a string representation of the object.

toString

Added in API level 1

open fun toString(radix: Int): String

Returns a string containing a string representation of this BigInteger with base radix. If radix < Character.MIN_RADIX or radix > Character.MAX_RADIX then a decimal representation is returned. The characters of the string representation are generated with method Character.forDigit.

Parameters
`radix`	Int: base to be used for the string representation.

valueOf

Added in API level 1

open static fun valueOf(value: Long): BigInteger

Returns a BigInteger whose value is equal to value.

xor

Added in API level 1

open fun xor(value: BigInteger): BigInteger

Returns a BigInteger whose value is this ^ value.

Implementation Note: Usage of this method is not recommended as the current implementation is not efficient.

Parameters
`value`	BigInteger: value to be xor'ed with `this`

Exceptions
`java.lang.NullPointerException`	if `value == null`

Properties

ONE

Added in API level 1

static val ONE: BigInteger

The BigInteger constant 1.

TEN

Added in API level 1

static val TEN: BigInteger

The BigInteger constant 10.

ZERO

Added in API level 1

static val ZERO: BigInteger

The BigInteger constant 0.