java.math
类 BigInteger

java.lang.Object
  java.lang.Number
      java.math.BigInteger

所有已实现的接口：

Serializable, Comparable<BigInteger>

public class BigInteger
extends Number
implements Comparable<BigInteger>

不可变的任意精度的整数。所有操作中，都以二进制补码形式表示 BigInteger（如 Java 的基本整数类型）。BigInteger 提供所有 Java 的基本整数操作符的对应物，并提供 java.lang.Math 的所有相关方法。另外，BigInteger 还提供以下运算：模算术、GCD 计算、质数测试、素数生成、位操作以及一些其他操作。

算术运算的语义完全模仿 Java 整数算术运算符的语义，如 The Java Language Specification 中所定义的。例如，以零作为除数的除法抛出 ArithmeticException，而负数除以正数的除法则产生一个负（或零）的余数。Spec 中关于溢出的细节都被忽略了，因为 BigIntegers 所设置的实际大小能适应操作结果的需要。

位移操作的语义扩展了 Java 的位移操作符的语义以允许产生负位移距离。带有负位移距离的右移操作会导致左移操作，反之亦然。忽略无符号的右位移运算符（>>>），因为该操作与由此类提供的“无穷大的词大小”抽象结合使用时毫无意义。

逐位逻辑运算的语义完全模仿 Java 的逐位整数运算符的语义。在执行操作之前，二进制运算符（and、or、xor）对两个操作数中的较短操作数隐式执行符号扩展。

比较操作执行有符号的整数比较，类似于 Java 的关系运算符和相等性运算符执行的比较。

提供的模算术操作用来计算余数、求幂和乘法可逆元。这些方法始终返回非负结果，范围在 0 和 (modulus - 1)（包括）之间。

位操作对其操作数的二进制补码表示形式的单个位进行操作。如有必要，操作数会通过扩展符号来包含指定的位。单一位操作不能产生与正在被操作的 BigInteger 符号不同的 BigInteger，因为它们仅仅影响单个位，并且此类提供的“无穷大词大小”抽象可保证在每个 BigInteger 前存在无穷多的“虚拟符号位”数。

为了简洁明了，在整个 BigInteger 方法的描述中都使用了伪代码。伪代码表达式 (i + j) 是“其值为 BigInteger i 加 BigInteger j 的 BigInteger”的简写。伪代码表达式 (i == j) 是“当且仅当 BigInteger i 表示与 BigInteger j 相同的值时，才为 true”的简写。可以类似地解释其他伪代码表达式。

当为任何输入参数传递 null 对象引用时，此类中的所有方法和构造方法都将抛出 NullPointerException。

从以下版本开始：

JDK1.1

另请参见：

BigDecimal, 序列化表格

ZERO

public static final BigInteger ZERO

BigInteger 的常量 0。

从以下版本开始：

1.2

ONE

public static final BigInteger ONE

BigInteger 的常量 1。

从以下版本开始：

1.2

TEN

public static final BigInteger TEN

BigInteger 的常量 10。

从以下版本开始：

1.5

BigInteger

public BigInteger(byte[] val)

将包含 BigInteger 的二进制补码表示形式的 byte 数组转换为 BigInteger。输入数组假定为 big-endian 字节顺序：最高有效字节在第零个元素中。

参数：

val - BigInteger 的 big-endian 二进制补码表示形式。

抛出：

NumberFormatException - val 为零字节长。

BigInteger

public BigInteger(int signum,
                  byte[] magnitude)

将 BigInteger 的符号-数量表示形式转换为 BigInteger。该符号表示为一个正负号整数值：-1 表示负，0 表示零，1 表示正。该大小是一个 big-endian 字节顺序的 byte 数组：最高有效字节在第零个元素中。允许零长度数量数组，这会导致 BigInteger 的值为 0，无论其正负号是 -1、0 还是 1。

参数：

signum - 该数的正负号（-1 表示负，0 表示零，1 表示正）。

magnitude - 该数的大小的 big-endian 二进制表示形式。

抛出：

NumberFormatException - signum 不是三个合法值之一（-1、0 和 1），或者 signum 是 0 并且 magnitude 包含一个或多个非零字节。

BigInteger

public BigInteger(String val,
                  int radix)

将指定基数的 BigInteger 的字符串表示形式转换为 BigInteger。该字符串表示形式包括一个可选的减号，后跟一个或多个指定基数的数字。字符到数字的映射由 Character.digit 提供。该字符串不能包含任何其他字符（例如，空格）。

参数：

val - BigInteger 的字符串表示形式。

radix - 要在解释 val 时使用的基数。

抛出：

NumberFormatException - val 不是指定基数的 BigInteger 的有效表示形式，或者 radix 超出从 Character.MIN_RADIX 到 Character.MAX_RADIX（包括）的范围。

另请参见：

Character.digit(char, int)

BigInteger

public BigInteger(String val)

将 BigInteger 的十进制字符串表示形式转换为 BigInteger。该字符串表示形式包括一个可选的减号，后跟一个或多个十进制数字序列。字符到数字的映射由 Character.digit 提供。该字符串不能包含任何其他字符（例如，空格）。

参数：

val - BigInteger 的十进制字符串表示形式。

抛出：

NumberFormatException - val 不是 BigInteger 的有效表示形式。

另请参见：

Character.digit(char, int)

BigInteger

public BigInteger(int numBits,
                  Random rnd)

构造一个随机生成的 BigInteger，它是在 0 到 (2^numBits - 1)（包括）范围内均匀分布的值。该分布的均匀性假定 rnd 中提供了一个随机位的公平源 (fair source)。注意，此构造方法始终构造一个非负 BigInteger。

参数：

numBits - 新 BigInteger 的最大 bitLength。

rnd - 计算新 BigInteger 时使用的随机源。

抛出：

IllegalArgumentException - 如果 numBits 为负。

另请参见：

bitLength()

BigInteger

public BigInteger(int bitLength,
                  int certainty,
                  Random rnd)

构造一个随机生成的正 BigInteger，它可能是一个具有指定 bitLength 的素数。

相对于此构造方法，建议优先使用 probablePrime 方法，必须指定一个确定数的情况除外。

参数：

bitLength - 返回的 BigInteger 的 bitLength。

certainty - 调用方允许的不确定性的度量。新的 BigInteger 表示素数的概率超出 (1 - 1/2^certainty)。此构造方法的执行时间与此参数的值是成比例的。

rnd - 随机比特源，用这些随机比特选择用来进行质数测试的候选数。

抛出：

ArithmeticException - bitLength < 2。

另请参见：

bitLength()

probablePrime

public static BigInteger probablePrime(int bitLength,
                                       Random rnd)

返回有可能是素数的、具有指定长度的正 BigInteger。此方法返回的 BigInteger 是合数的概率不超出 2^-100。

参数：

bitLength - 返回的 BigInteger 的 bitLength。

rnd - 随机比特源，用这些随机比特选择用来进行质数测试的候选数。

返回：

可能是素数的 bitLength 个位的 BigInteger

抛出：

ArithmeticException - bitLength < 2。

从以下版本开始：

1.4

另请参见：

bitLength()

nextProbablePrime

public BigInteger nextProbablePrime()

返回大于此 BigInteger 的可能为素数的第一个整数。此方法返回的数是合数的概率不超出 2^-100。此方法在执行以下搜索时将始终不会跳过素数：如果它返回 p，则不存在 this < q < p 的素数 q。

返回：

返回大于此 BigInteger 的可能为素数的第一个整数。

抛出：

ArithmeticException - this < 0。

从以下版本开始：

1.5

valueOf

public static BigInteger valueOf(long val)

返回其值等于指定 long 的值的 BigInteger。提供的此“静态工厂方法”优先于 (long) 构造方法，因为前者允许重用经常使用的 BigInteger。

参数：

val - 要返回的 BigInteger 的值。

返回：

具有指定值的 BigInteger。

add

public BigInteger add(BigInteger val)

返回其值为 (this + val) 的 BigInteger。

参数：

val - 将添加到此 BigInteger 中的值。

返回：

this + val

subtract

public BigInteger subtract(BigInteger val)

返回其值为 (this - val) 的 BigInteger。

参数：

val - 从此 BigInteger 中减去的值。

返回：

this - val

multiply

public BigInteger multiply(BigInteger val)

返回其值为 (this * val) 的 BigInteger。

参数：

val - 要乘以此 BigInteger 的值。

返回：

this * val

divide

public BigInteger divide(BigInteger val)

返回其值为 (this / val) 的 BigInteger。

参数：

val - 此 BigInteger 要除以的值。

返回：

this / val

抛出：

ArithmeticException - val==0

divideAndRemainder

public BigInteger[] divideAndRemainder(BigInteger val)

返回包含 (this / val) 后跟 (this % val) 的两个 BigInteger 的数组。

参数：

val - 此 BigInteger 要除以的值和计算所得的余数。

返回：

两个 BigInteger 的数组：商 (this / val) 是初始元素，余数 (this % val) 是最终元素。

抛出：

ArithmeticException - val==0

remainder

public BigInteger remainder(BigInteger val)

返回其值为 (this % val) 的 BigInteger。

参数：

val - 此 BigInteger 要除以的值和计算所得的余数。

返回：

this % val

抛出：

ArithmeticException - val==0

pow

public BigInteger pow(int exponent)

返回其值为 (this^exponent) 的 BigInteger。注意，exponent 是一个整数而不是 BigInteger。

参数：

exponent - 此 BigInteger 的指数。

返回：

this^exponent

抛出：

ArithmeticException - exponent 为负。（这会导致该运算产生一个非整数值。）

gcd

public BigInteger gcd(BigInteger val)

返回一个 BigInteger，其值是 abs(this) 和 abs(val) 的最大公约数。如果 this==0 && val==0，则返回 0 。

参数：

val - 要一起计算最大公约数的值。

返回：

GCD(abs(this), abs(val))

abs

public BigInteger abs()

返回其值是此 BigInteger 的绝对值的 BigInteger。

返回：

abs(this)

negate

public BigInteger negate()

返回其值是 (-this) 的 BigInteger。

返回：

-this

signum

public int signum()

返回此 BigInteger 的正负号函数。

返回：

当此 BigInteger 的值为负、零或正时，返回 -1、0 或 1。

mod

public BigInteger mod(BigInteger m)

返回其值为 (this mod m) 的 BigInteger。此方法不同于 remainder，因为它始终返回一个 非负 BigInteger。

参数：

m - 模数。

返回：

this mod m

抛出：

ArithmeticException - m <= 0

另请参见：

remainder(java.math.BigInteger)

modPow

public BigInteger modPow(BigInteger exponent,
                         BigInteger m)

返回其值为 (this^exponent mod m) 的 BigInteger。（与 pow 不同，此方法允许使用负指数。）

参数：

exponent - 该指数。

m - 模数。

返回：

this^exponent mod m

抛出：

ArithmeticException - m <= 0

另请参见：

modInverse(java.math.BigInteger)

modInverse

public BigInteger modInverse(BigInteger m)

返回其值为 (this^-1 mod m) 的 BigInteger。

参数：

m - 模数。

返回：

this^-1 mod m.

抛出：

ArithmeticException - m <= 0，或者此 BigInteger 没有乘法可逆元 mod m（即此 BigInteger 不是 m 的相对素数）。

shiftLeft

public BigInteger shiftLeft(int n)

返回其值为 (this << n) 的 BigInteger。位移距离 n 可以为负，在此情况下，此方法执行右移操作。（计算 floor(this * 2ⁿ)。）

参数：

n - 以位为单位的位移距离。

返回：

this << n

另请参见：

shiftRight(int)

shiftRight

public BigInteger shiftRight(int n)

返回其值为 (this >> n) 的 BigInteger。执行符号扩展。位移距离 n 可以为负，在此情况下，此方法执行左移操作。（计算 floor(this / 2ⁿ)。）

参数：

n - 以位为单位的位移距离。

返回：

this >> n

另请参见：

shiftLeft(int)

and

public BigInteger and(BigInteger val)

返回其值为 (this & val) 的 BigInteger。（当且仅当 this 和 val 同时为负时，此方法返回一个负 BigInteger。）

参数：

val - 要与此 BigInteger 执行 AND（与）运算的值。

返回：

this & val

or

public BigInteger or(BigInteger val)

返回其值为 (this | val) 的 BigInteger。（当且仅当 this 和 val 之一为负时，此方法返回一个负 BigInteger。）

参数：

val - 要与此 BigInteger 执行或运算的值。

返回：

this | val

xor

public BigInteger xor(BigInteger val)

返回其值为 (this ^ val) 的 BigInteger。（当且仅当 this 和 val 中只有一个为负时，此方法返回一个负 BigInteger。）

参数：

val - 要与此 BigInteger 执行异或运算的值。

返回：

this ^ val

not

public BigInteger not()

返回其值为 (~this) 的 BigInteger。（当且仅当此 BigInteger 为非负时，此方法返回一个负值。）

返回：

~this

andNot

public BigInteger andNot(BigInteger val)

返回其值为 (this & ~val) 的 BigInteger。此方法等效于 and(val.not())，提供此方法是为了更方便地进行屏蔽操作。（当且仅当 this 为负且 val 为正时，此方法返回一个负 BigInteger。）

参数：

val - 要进行求补且与此 BigInteger 执行与运算的值。

返回：

this & ~val

testBit

public boolean testBit(int n)

当且仅当设置了指定的位时，返回 true。（计算 ((this & (1<<n)) != 0)。）

参数：

n - 要测试的位的索引。

返回：

当且仅当设置了指定的位时，返回 true。

抛出：

ArithmeticException - n 为负。

setBit

public BigInteger setBit(int n)

返回其值与设置了指定位的此 BigInteger 等效的 BigInteger。（计算 (this | (1<<n))。）

参数：

n - 要设置的位的索引。

返回：

this | (1<<n)

抛出：

ArithmeticException - n 为负。

clearBit

public BigInteger clearBit(int n)

返回其值与清除了指定位的此 BigInteger 等效的 BigInteger。（计算 (this & ~(1<<n))。）

参数：

n - 要清除的位的索引。

返回：

this & ~(1<<n)

抛出：

ArithmeticException - n 为负。

flipBit

public BigInteger flipBit(int n)

返回其值与对此 BigInteger 进行指定位翻转后的值等效的 BigInteger。（计算 (this ^ (1<<n))。）

参数：

n - 要翻转的位的索引。

返回：

this ^ (1<<n)

抛出：

ArithmeticException - n 为负。

getLowestSetBit

public int getLowestSetBit()

返回此 BigInteger 最右端（最低位）1 比特的索引（即从此字节的右端开始到本字节中最右端 1 比特之间的 0 比特的位数）。如果此 BigInteger 不包含一位，则返回 -1。（计算 (this==0? -1 : log₂(this & -this))。)

返回：

此 BigInteger 中最右端的一比特位的索引。

bitLength

public int bitLength()

返回此 BigInteger 的最小的二进制补码表示形式的位数，不包括 符号位。对于正 BigInteger，这等于常规二进制表示形式中的位数。（计算 (ceil(log₂(this < 0 ? -this : this+1)))。)

返回：

返回此 BigInteger 的最小的二进制补码表示形式中的位数，不包括 符号位。

bitCount

public int bitCount()

返回此 BigInteger 的二进制补码表示形式中与符号不同的位的数量。此方法在实现 BigInteger 上的位向量样式设置时非常有用。

返回：

返回此 BigInteger 的二进制补码表示形式中与符号位不同的位的数量。

isProbablePrime

public boolean isProbablePrime(int certainty)

如果此 BigInteger 可能为素数，则返回 true，如果它一定为合数，则返回 false。如果 certainty <= 0，则返回 true。

参数：

certainty - 调用方允许的不确定性的度量。如果该调用返回 true，则此 BigInteger 是素数的概率超出 (1 - 1/2^certainty)。此方法的执行时间与此参数的值是成比例的。

返回：

如果此 BigInteger 可能为素数，则返回 true，如果它一定为合数，则返回 false。

compareTo

public int compareTo(BigInteger val)

将此 BigInteger 与指定的 BigInteger 进行比较。对于针对六个布尔比较运算符 (<, ==, >, >=, !=, <=) 中的每一个运算符的各个方法，优先提供此方法。执行这些比较的建议语句是：(x.compareTo(y) <op> 0)，其中 <op> 是六个比较运算符之一。

指定者：

接口 Comparable<BigInteger> 中的 compareTo

参数：

val - 将此 BigInteger 与之比较的 BigInteger。

返回：

当此 BigInteger 在数值上小于、等于或大于 val 时，返回 -1，0，或 1。

equals

public boolean equals(Object x)

比较此 BigInteger 与指定的 Object 的相等性。

覆盖：

类 Object 中的 equals

参数：

x - 将此 BigInteger 与之比较的 Object。

返回：

当且仅当指定的 Object 是一个其值在数字上等于此 BigInteger 的 BigInteger 时，返回 true。

另请参见：

Object.hashCode(), Hashtable

min

public BigInteger min(BigInteger val)

返回此 BigInteger 和 val 的最小值。

参数：

val - 要计算最小值的值。

返回：

其值为此 BigInteger 和 val 中的较小值的 BigInteger。如果它们相等，可能返回其中之一。

max

public BigInteger max(BigInteger val)

返回此 BigInteger 和 val 的最大值。

参数：

val - 要计算最大值的值。

返回：

其值为此 BigInteger 和 val 中较大值的 BigInteger。如果它们相等，可能返回其中之一。

hashCode

public int hashCode()

返回此 BigInteger 的哈希码。

覆盖：

类 Object 中的 hashCode

返回：

此 BigInteger 的哈希码。

另请参见：

Object.equals(java.lang.Object), Hashtable

toString

public String toString(int radix)

返回此 BigInteger 的给定基数的字符串表示形式。如果该基数超出从 Character.MIN_RADIX 到 Character.MAX_RADIX（包括）这一范围，则其默认值为 10（Integer.toString 就是这种情况）。使用由 Character.forDigit 提供的从数字到字符的映射，并在需要时在前面加一个负号。（此表示形式与 (String, int) 构造方法兼容。）

参数：

radix - 字符串表示形式的基数。

返回：

此 BigInteger 给定基数的字符串表示形式。

另请参见：

Integer.toString(int, int), Character.forDigit(int, int), BigInteger(java.lang.String, int)

toString

public String toString()

返回此 BigInteger 的十进制字符串表示形式。使用由 Character.forDigit 提供的从数字到字符的映射，并在需要时在前面加一个负号。（此表示形式与 (String) 构造方法兼容，并允许使用 Java 的 + 运算符将字符串连接。）

覆盖：

类 Object 中的 toString

返回：

此 BigInteger 的十进制字符串表示形式。

另请参见：

Character.forDigit(int, int), BigInteger(java.lang.String)

toByteArray

public byte[] toByteArray()

返回一个 byte 数组，该数组包含此 BigInteger 的二进制补码表示形式。该 byte 数组将为 big-endian 字节顺序：最高有效字节在第零个元素中。此数组将包含表示此 BigInteger 所需的最小数量的字节，至少包括一个符号位，即 (ceil((this.bitLength() + 1)/8))。（此表示形式与 (byte[]) 构造方法兼容。）

返回：

一个包含此 BigInteger 的二进制补码表示形式的 byte 数组。

另请参见：

BigInteger(byte[])

intValue

public int intValue()

将此 BigInteger 转换为 int。此转换类似于 Java Language Specification 中定义的从 long 到 int 的基本收缩转换：如果此 BigInteger 太长而不适合用 int 表示，则仅返回 32 位的低位字节。注意，此转换会丢失关于该 BigInteger 值的总大小的信息，并返回带有相反符号的结果。

指定者：

类 Number 中的 intValue

返回：

转换为 int 的此 BigInteger。

longValue

public long longValue()

将此 BigInteger 转换为 long。此转换类似于 Java Language Specification 中定义的从 long 到 int 的基本收缩转换：如果此 BigInteger 太长而不适合用 long 表示，则仅返回 64 位的低位字节。注意，此转换会丢失关于该 BigInteger 值的总大小的信息，并返回带有相反符号的结果。

指定者：

类 Number 中的 longValue

返回：

转换为 long 的此 BigInteger。

floatValue

public float floatValue()

将此 BigInteger 转换为 float。此转换类似于 Java Language Specification 中定义的从 double 到 float 的基本收缩转换：如果此 BigInteger 的数量太大，不能表示为 float，则将其适当地转换为 Float.NEGATIVE_INFINITY 或 Float.POSITIVE_INFINITY。注意，即使在返回值是有限的情况下，此转换也可以丢失关于 BigInteger 值的精度的信息。

指定者：

类 Number 中的 floatValue

返回：

转换为 float 的此 BigInteger。

doubleValue

public double doubleValue()

将此 BigInteger 转换为 double。此转换类似于 Java Language Specification 中定义的从 double 到 float 的基本收缩转换：如果此 BigInteger 的数量太大，不能表示为 double，则将其适当地转换为 Double.NEGATIVE_INFINITY 或 Double.POSITIVE_INFINITY。注意，即使在返回值是有限的情况下，此转换也可以丢失关于 BigInteger 值的精度的信息。

指定者：

类 Number 中的 doubleValue

返回：

转换为 double 的此 BigInteger。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。