struct BigInt

public struct BigInt <: Comparable<BigInt> & Hashable & ToString

功能：BigInt 定义为任意精度（二进制）的有符号整数。仓颉的 struct BigInt 用于任意精度有符号整数的计算，类型转换等。

[h2]prop bitLen

public prop bitLen: Int64

功能：获取此 BigInt 的最短 bit 长度。如 -3 (101) 返回 3，-1 (11) 返回 2，0 (0) 返回 1。

类型：Int64

[h2]prop sign

public prop sign: Int64

功能：获取此 BigInt 的符号。正数返回 1；0 返回 0；负数返回 -1。

类型：Int64

[h2]init(Array<Byte>)

public init(bytes: Array<Byte>)

功能：通过大端的 Byte 数组以补码形式构建一个 BigInt 结构体。

数据存储方法有以下两种：

大端存储方式：高位字节存放在低位地址。
小端存储方式：将数据的低位字节存放在内存的高位地址。

参数：

bytes: Array<Byte> - 大端二进制补码数组，数组长度不能为空。

异常：

IllegalArgumentException - 当传入空数组时，抛此异常。

[h2]init(Bool, Array<Byte>)

public init(sign: Bool, magnitude: Array<Byte>)

功能：通过符号位和真值的绝对值构建一个 BigInt 结构体。视空数组为 0。

参数：

sign: Bool - 符号。true 表示非负数，false 表示负数。
magnitude: Array<Byte> - 真值绝对值的二进制原码。

异常：

IllegalArgumentException - 当 sign 为 false 且传入的数组为 0 时，抛此异常。

[h2]init(Bool, Int64, Random)

public init(sign: Bool, bitLen: Int64, rand!: Random = Random())

功能：通过指定正负、bit 长度和随机数种子构建一个随机的 BigInt 结构体。bit 长度需要大于 0。

参数：

sign: Bool - 指定随机 BigInt 的正负。
bitLen: Int64 - 指定随机 BigInt 的 bit 长度上限。
rand!: Random - 指定的随机数种子。

异常：

IllegalArgumentException - 如果指定的 bit 长度小于等于 0，则抛此异常。

[h2]init(Int16)

public init(n: Int16)

功能：通过 16 位有符号整数构建一个 BigInt 结构体。

参数：

n: Int16 - 16 位有符号整数。

[h2]init(Int32)

public init(n: Int32)

功能：通过 32 位有符号整数构建一个 BigInt 结构体。

参数：

n: Int32 - 32 位有符号整数。

[h2]init(Int64)

public init(n: Int64)

功能：通过 64 位有符号整数构建一个 BigInt 结构体。

参数：

n: Int64 - 64 位有符号整数。

[h2]init(Int8)

public init(n: Int8)

功能：通过 8 位有符号整数构建一个 BigInt 结构体。

参数：

n: Int8 - 8 位有符号整数。

[h2]init(IntNative)

public init(n: IntNative)

功能：通过平台相关有符号整数构建一个 BigInt 结构体。

参数：

n: IntNative - 平台相关有符号整数。

[h2]init(String, Int64)

public init(s: String, base!: Int64 = 10)

功能：通过字符串和进制构建一个 BigInt 结构体，支持 2 进制到 36 进制。

字符串的规则如下，即开头是可选的符号（正号或负号），接一串字符串表示的数字：

IntegerString : (SignString)? ValueString

SignString : + | -
ValueString : Digits
- Digits: Digit | Digit Digits
  - Digit : '0' ~ '9' | 'A' ~ 'Z' | 'a' ~ 'z'
    - 如果 Digit 在 '0' ~ '9' 内，需要满足 (Digit - '0') < base；
    - 如果 Digit 在 'A' ~ 'Z' 内，需要满足 (Digit - 'A') + 10 < base；
    - 如果 Digit 在 'a' ~ 'z' 内，需要满足 (Digit - 'A') + 10 < base。

参数：

s: String - 用于构建 BigInt 结构体的字符串。字符串规则为，开头可选一个正号（+）或者负号（-）。接下来必选非空阿拉伯数字或大小写拉丁字母的字符序列，大小写字符含义一样，'a' 和 'A' 的大小等于十进制的 10，'b' 和 'B' 的大小等于十进制的 11，以此类推。序列中的字符大小不得大于等于进制大小。
base!: Int64 - 进制。字符串所表示的进制，范围为 [2, 36]。

异常：

IllegalArgumentException - 如果字符串 s 不符合上述规则，或 base 表示的进制不在 [2, 36] 区间内，抛此异常。

[h2]init(UInt16)

public init(n: UInt16)

功能：通过 16 位无符号整数构建一个 BigInt 结构体。

参数：

n: UInt16 - 16 位无符号整数。

[h2]init(UInt32)

public init(n: UInt32)

功能：通过 32 位无符号整数构建一个 BigInt 结构体。

参数：

n: UInt32 - 32 位无符号整数。

[h2]init(UInt64)

public init(n: UInt64)

功能：通过 64 位无符号整数构建一个 BigInt 结构体。

参数：

n: UInt64 - 64 位无符号整数。

[h2]init(UInt8)

public init(n: UInt8)

功能：通过 8 位无符号整数构建一个 BigInt 结构体。

参数：

n: UInt8 - 8 位无符号整数。

[h2]init(UIntNative)

public init(n: UIntNative)

功能：通过平台相关无符号整数构建一个 BigInt 结构体。

参数：

n: UIntNative - 平台相关无符号整数。

[h2]static func randomProbablePrime(Int64, UInt64, Random)

public static func randomProbablePrime(bitLen: Int64, certainty: UInt64, rand!: Random = Random()): BigInt

功能：通过可选的随机数种子构建一个随机的 BigInt 素数，素数的 bit 长度不超过入参 bitLen。

显然，素数必定是大于等于 2 的整数，因此 bitLen 必须大于等于 2。素数检测使用 Miller-Rabin 素数测试算法。Miller-Rabin 测试会有概率将一个合数判定为素数，其出错概率随着入参 certainty 的增加而减少。

参数：

bitLen: Int64 - 所要生成的随机素数的 bit 长度的上限。
certainty: UInt64 - 生成的随机素数通过 Miller-Rabin 素数测试算法的次数，通过的次数越多，将合数误判为素数的概率越低。
rand!: Random - 指定的随机数种子。

返回值：

BigInt - 返回生成的随机素数。

异常：

IllegalArgumentException - 如果指定的 bit 长度小于等于 1，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let randomProbablePrime = BigInt.randomProbablePrime(6, 3)
    println(randomProbablePrime)
}

运行结果:

[h2]func clearBit(Int64)

public func clearBit(index: Int64): BigInt

功能：通过将指定索引位置的 bit 修改为 0 来构造一个新 BigInt。

参数：

index: Int64 - 需要设置的 bit 位置的索引。index 需要大于等于 0。

返回值：

BigInt - 一个新的 BigInt，它是将原 BigInt 的 index 处的 bit 改为 0 的产物。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let clearBit = bigInt.clearBit(10)
    println(clearBit)
}

运行结果:

[h2]func compare(BigInt)

public func compare(that: BigInt): Ordering

功能：判断 BigInt 与另一个 BigInt 的关系。

参数：

that: BigInt - 另一个 BigInt。

返回值：

Ordering - 返回此 BigInt 与另一个 BigInt 的关系。如果等于，返回 Ordering.EQ；如果小于，返回 Ordering.LT；如果大于，返回 Ordering.GT。

[h2]func divAndMod(BigInt)

public func divAndMod(that: BigInt): (BigInt, BigInt)

功能：BigInt 的除法运算。

与另一个 BigInt 相除，返回商和模。此除法运算的行为与基础类型保持一致，即商向靠近 0 的方向取整，模的符号与被除数保持一致。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

(BigInt, BigInt) - 商和模。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let (div, mod) = bigInt.divAndMod(that)
    println(div)
    println(mod)
}

运行结果:

2
1

[h2]func flipBit(Int64)

public func flipBit(index: Int64): BigInt

功能：通过翻转指定索引位置的 bit 来构造一个新 BigInt。

参数：

index: Int64 - 需要翻转的 bit 位置的索引。index 需要大于等于 0。

返回值：

BigInt - 一个新的 BigInt，它是将原 BigInt index 处的 bit 翻转后的产物。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let flipBit = bigInt.flipBit(10)
    println(flipBit)
}

运行结果:

[h2]func hashCode()

public func hashCode(): Int64

功能：计算并返回此 BigInt 的哈希值。

返回值：

Int64 - 返回此 BigInt 的哈希值。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let hashCode = bigInt.hashCode()
    println(hashCode)
}

运行结果:

[h2]func isProbablePrime(UInt64)

public func isProbablePrime(certainty: UInt64): Bool

功能：判断一个数是不是素数。

该函数使用了 Miller-Rabin 测试算法，此算法的准确率会随着 certainty 参数的增加而增加。如果该数是素数，那么 Miller-Rabin 测试必定返回 true；如果该数是合数（期待返回 false），那么会有低于 1/4^certainty 概率返回 true。素数只对大于等于 2 的正整数有意义，即负数，0，1 都不是素数。

参数：

certainty: UInt64 - 需要执行 Miller-Rabin 测试的次数。注意，如果测试次数为 0，表示不测试，那么总是返回 true（即不是素数的数也必定返回 true）。

返回值：

Bool - 如果使用此函数测定了一个数为素数，则返回 true；不为素数，则返回 false。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1024)
    let isProbablePrime = bigInt.isProbablePrime(10)
    println(isProbablePrime)
}

运行结果:

false

[h2]func lowestOneBit()

public func lowestOneBit(): Int64

功能：判断为 1 的最低位的 bit 的位置。

返回值：

Int64 - 返回为 1 的最低位的 bit 的位置。如果 bit 全为 0，则返回 -1。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(-1)
    let lowestOneBit = bigInt.lowestOneBit()
    println(lowestOneBit)
}

运行结果:

[h2]func modInverse(BigInt)

public func modInverse(that: BigInt): BigInt

功能：求模逆元。

模逆元 r 满足 $(this * r) % that == 1$。显然，this 和 that 必须互质。当 that 为正负 1 时，结果总是 0。

参数：

that: BigInt - 另外一个 BigInt。入参不得为 0，且需要与 this 互质。

返回值：

BigInt - 返回模逆元。

异常：

IllegalArgumentException - 当 this 和 that 不互质或 that 为 0 时，抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let modInverse = bigInt.modInverse(that)
    println(modInverse)
}

运行结果:

[h2]func modPow

public func modPow(n: BigInt, m!: ?BigInt = None): BigInt

功能：计算此 BigInt 的 n 次幂模 m 的结果，并返回。

模的规则与基础类型一致，即模的符号与被除数保持一致。

参数：

n: BigInt - 指数，必须为非负数。
m!: ?BigInt - 除数，此入参不得为 0。

返回值：

BigInt - 乘方后取模的运算结果。

异常：

ArithmeticException - 除数为 0 抛此异常。
IllegalArgumentException - 指数为负数时抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(2)
    let n = BigInt(10)
    let modPow = bigInt.modPow(n)
    println(modPow)
}

运行结果:

[h2]func quo(BigInt)

public func quo(that: BigInt): BigInt

功能：BigInt 的除法运算。

与另一个 BigInt 相除，返回结果。此除法运算的行为与运算符重载函数区别于，如果被除数为负数，此函数的结果向着远离 0 的方向取整，保证余数大于等于 0。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相除后的结果

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let quo = bigInt.quo(that)
    println(quo)
}

运行结果:

[h2]func quoAndRem(BigInt)

public func quoAndRem(that: BigInt): (BigInt, BigInt)

功能：BigInt 的除法运算。

与另一个 BigInt 相除，返回商和余数。此除法运算的行为与 divAndMod 函数区别于，如果被除数为负数，此函数的结果向着远离 0 的方向取整，保证余数总是大于等于 0。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

(BigInt, BigInt) - 商和余数。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let (quo, rem) = bigInt.quoAndRem(that)
    println(quo)
    println(rem)
}

运行结果:

2
1

[h2]func rem(BigInt)

public func rem(that: BigInt): BigInt

功能：BigInt 的模运算。

与另一个 BigInt 相除，返回余数。余数的结果总是大于等于 0。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相除后的余数。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(1025)
    let that = BigInt(512)
    let rem = bigInt.rem(that)
    println(rem)
}

运行结果:

[h2]func setBit(Int64)

public func setBit(index: Int64): BigInt

功能：通过将指定索引位置的 bit 修改为 1 来构造一个新 BigInt。

参数：

index: Int64 - 需要设置的 bit 位置的索引。index 需要大于等于 0。

返回值：

BigInt - 一个新的 BigInt，它是将原 BigInt index 处的 bit 改为 1 的产物。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0)
    let setBit = bigInt.setBit(10)
    println(setBit)
}

运行结果:

[h2]func testBit(Int64)

public func testBit(index: Int64): Bool

功能：判断指定位置的 bit 信息，如果指定位置的 bit 为 0，则返回 false；为 1，则返回 true。

参数：

index: Int64 - 需要知道的 bit 的索引。index 需要大于等于 0。

返回值：

Bool - 指定位置的 bit 信息。

异常：

IllegalArgumentException - 如果入参 index 小于 0，则抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(-1)
    let testBit = bigInt.testBit(100)
    println(testBit)
}

运行结果:

true

[h2]func toBytes()

public func toBytes(): Array<Byte>

功能：计算并返回此 BigInt 的大端补码字节数组。

字节数组最低索引的最低位为符号位，如 128 返回 [0, 128]（符号位为 0），-128 返回 [128]（符号位为 1）。

返回值：

Array<Byte> - 返回此 BigInt 的大端补码字节数组。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0x400)
    let toBytes = bigInt.toBytes()
    println(toBytes)
}

运行结果:

[4, 0]

[h2]func toInt16(OverflowStrategy)

public func toInt16(overflowHandling!: OverflowStrategy = throwing): Int16

功能：将当前 BigInt 对象转化为 Int16 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

Int16 - 返回转换后的 Int16 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt(0x8000_0000_0000)
    let toInt16 = bigInt.toInt16(overflowHandling: saturating)
    println(toInt16)
}

运行结果:

[h2]func toInt32(OverflowStrategy)

public func toInt32(overflowHandling!: OverflowStrategy = throwing): Int32

功能：将当前 BigInt 对象转化为 Int32 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

Int32 - 返回转换后的 Int32 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt(0x8000_0000_00FF)
    let toInt32 = bigInt.toInt32(overflowHandling: wrapping)
    println(toInt32)
}

运行结果:

[h2]func toInt64(OverflowStrategy)

public func toInt64(overflowHandling!: OverflowStrategy = throwing): Int64

功能：将当前 BigInt 对象转化为 Int64 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

Int64 - 返回转换后的 Int64 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toInt64 = bigInt.toInt64(overflowHandling: wrapping)
    println(toInt64)
}

运行结果:

[h2]func toInt8(OverflowStrategy)

public func toInt8(overflowHandling!: OverflowStrategy = throwing): Int8

功能：将当前 BigInt 对象转化为 Int8 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

Int8 - 返回转换后的 Int8 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt(1024)
    let toInt8 = bigInt.toInt8(overflowHandling: saturating)
    println(toInt8)
}

运行结果:

[h2]func toIntNative(OverflowStrategy)

public func toIntNative(overflowHandling!: OverflowStrategy = throwing): IntNative

功能：将当前 BigInt 对象转化为 IntNative 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

IntNative - 返回转换后的 IntNative 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toIntNative = bigInt.toIntNative(overflowHandling: wrapping)
    println(toIntNative)
}

运行结果:

[h2]func toString()

public func toString(): String

功能：计算并返回此 BigInt 的十进制字符串表示。

返回值：

String - 返回此 BigInt 的十进制字符串。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0x400)
    let toString = bigInt.toString()
    println(toString)
}

运行结果:

[h2]func toString(Int64)

public func toString(base: Int64): String

功能：计算并返回此 BigInt 的任意进制字符串表示。

参数：

base: Int64 - 进制。字符串所表示的进制，范围为 [2, 36]。

返回值：

String - 返回此 BigInt 的 base 进制字符串。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt(0x400)
    let toString = bigInt.toString(2)
    println(toString)
}

运行结果:

10000000000

[h2]func toUInt16(OverflowStrategy)

public func toUInt16(overflowHandling!: OverflowStrategy = throwing): UInt16

功能：将当前 BigInt 对象转化为 UInt16 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UInt16 - 返回转换后的 UInt16 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toUInt16 = bigInt.toUInt16(overflowHandling: wrapping)
    println(toUInt16)
}

运行结果:

[h2]func toUInt32(OverflowStrategy)

public func toUInt32(overflowHandling!: OverflowStrategy = throwing): UInt32

功能：将当前 BigInt 对象转化为 UInt32 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UInt32 - 返回转换后的 UInt32 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    let toUInt32 = bigInt.toUInt32(overflowHandling: wrapping)
    println(toUInt32)
}

运行结果:

[h2]func toUInt64(OverflowStrategy)

public func toUInt64(overflowHandling!: OverflowStrategy = throwing): UInt64

功能：将当前 BigInt 对象转化为 UInt64 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UInt64 - 返回转换后的 UInt64 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("-800000000000000000", base: 16)
    let toUInt64 = bigInt.toUInt64(overflowHandling: saturating)
    println(toUInt64)
}

运行结果:

[h2]func toUInt8(OverflowStrategy)

public func toUInt8(overflowHandling!: OverflowStrategy = throwing): UInt8

功能：将当前 BigInt 对象转化为 UInt8 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UInt8 - 返回转换后的 UInt8 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("800000000000000000", base: 16)
    try {
        bigInt.toUInt8(overflowHandling: throwing)
    } catch (e: OverflowException) {
        println(e.message)
    }
    return
}

运行结果:

Out of range of the UInt8

[h2]func toUIntNative(OverflowStrategy)

public func toUIntNative(overflowHandling!: OverflowStrategy = throwing): UIntNative

功能：将当前 BigInt 对象转化为 UIntNative 类型，支持自定义溢出策略。

参数：

overflowHandling!: OverflowStrategy - 转换溢出策略。
- "throwing"：异常模式。出现溢出抛出异常。
- "wrapping"：溢出模式。出现溢出高位截断。
- "saturating"：边界值模式。出现溢出，当前值大于目标类型的 MAX 值，返回目标类型 MAX 值，当前值小于目标类型的 MIN 值，返回目标类型 MIN 值。

返回值：

UIntNative - 返回转换后的 UInt64 值。

异常：

OverflowException - 当不指定溢出策略或溢出策略为 throwing 转换溢出时，抛出此异常。

示例：

import std.math.numeric.BigInt
import std.math.numeric.OverflowStrategy

main() {
    let bigInt = BigInt("-800000000000000000", base: 16)
    let toUIntNative = bigInt.toUIntNative(overflowHandling: saturating)
    println(toUIntNative)
}

运行结果:

[h2]operator func !()

public operator func !(): BigInt

功能：按位非。将操作数中的二进制位 0 变 1，1 变 0。

返回值：

BigInt - 返回此 BigInt 按位非的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let no = !bigInt
    println(no)
}

运行结果:

[h2]operator func !=(BigInt)

public operator func !=(that: BigInt): Bool

功能：判不等运算。

参数：

that: BigInt - 判不等运算的另一个 BigInt。

返回值：

Bool - 判不等的结果。不等返回 true，相等返回 false。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt != that)
}

运行结果:

true

[h2]operator func %(BigInt)

public operator func %(that: BigInt): BigInt

功能：BigInt 的模运算。

取模运算的行为与基础类型保持一致，即符号与被除数保持一致。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相模后的结果。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let that = BigInt("-23456789123456789")
    let mod = bigInt % that
    println(mod)
}

运行结果:

[h2]operator func &(BigInt)

public operator func &(that: BigInt): BigInt

功能：按位与。其功能是参与运算的两数各对应的二进位相与。只有对应的两个二进位都为 1 时，结果位才为 1。

参数：

that: BigInt - 按位与运算的另外一个 BigInt。

返回值：

BigInt - 返回与另一个 BigInt 的按位与的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("8")
    let that = BigInt("7")
    let and = bigInt & that
    println(and)
}

运行结果:

[h2]operator func *(BigInt)

public operator func *(that: BigInt): BigInt

功能：BigInt 乘法。

参数：

that: BigInt - 乘数。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相乘后的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-23456789123456789")
    let mul = bigInt * that
    println(mul)
}

运行结果:

23456789123456789

[h2]operator func **(UInt64)

public operator func **(n: UInt64): BigInt

功能：求 BigInt 的 n 次幂。

参数：

n: UInt64 - 指数。

返回值：

BigInt - 幂运算结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-2")
    let power = bigInt ** 64
    println(power.toString(16))
}

运行结果:

10000000000000000

[h2]operator func +(BigInt)

public operator func +(that: BigInt): BigInt

功能：BigInt 加法。

参数：

that: BigInt - 加数。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相加后的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("123456789123456789")
    let that = BigInt("-23456789123456789")
    let plus = bigInt + that
    println(plus)
}

运行结果:

100000000000000000

[h2]operator func -()

public operator func -(): BigInt

功能：求 BigInt 的相反数。

返回值：

BigInt - 返回此 BigInt 的相反数。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let opposite = -bigInt
    println(opposite)
}

运行结果:

23456789123456789

[h2]operator func -(BigInt)

public operator func -(that: BigInt): BigInt

功能：BigInt 减法。

参数：

that: BigInt - 减数。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相减后的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("100000000000000000")
    let that = BigInt("-23456789123456789")
    let sub = bigInt - that
    println(sub)
}

运行结果:

123456789123456789

[h2]operator func <(BigInt)

public operator func <(that: BigInt): Bool

功能：小于比较运算。

参数：

that: BigInt - 小于比较运算的另一个 BigInt。

返回值：

Bool - 比较的结果。小于返回 true，否则返回 false。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt < that)
}

运行结果:

false

[h2]operator func <<(Int64)

public operator func <<(n: Int64): BigInt

功能：左移运算。

参数：

n: Int64 - 左移 n 位，n 需要大于等于 0。

返回值：

BigInt - 返回此 BigInt 左移 n 位的结果。

异常：

ArithmeticException - 入参小于 0 时抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let leftShift = bigInt << 64
    println(leftShift.toString(16))
}

运行结果:

-10000000000000000

[h2]operator func <=(BigInt)

public operator func <=(that: BigInt): Bool

功能：小于等于比较运算。

参数：

that: BigInt - 小于等于比较运算的另一个 BigInt。

返回值：

Bool - 比较的结果。小于等于返回 true，否则返回 false。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt <= that)
}

运行结果:

false

[h2]operator func ==(BigInt)

public operator func ==(that: BigInt): Bool

功能：判等运算。

参数：

that: BigInt - 判等运算的另一个 BigInt。

返回值：

Bool - 判等的结果。相等返回 true，不等返回 false。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt == that)
}

运行结果:

false

[h2]operator func >(BigInt)

public operator func >(that: BigInt): Bool

功能：大于比较运算。

参数：

that: BigInt - 大于比较运算的另一个 BigInt。

返回值：

Bool - 比较的结果。大于返回 true，否则返回 false。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt > that)
}

运行结果:

true

[h2]operator func >=(BigInt)

public operator func >=(that: BigInt): Bool

功能：大于等于比较运算。

参数：

that: BigInt - 大于等于比较运算的另一个 BigInt。

返回值：

Bool - 比较的结果。大于等于返回 true，否则返回 false。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("-2")
    println(bigInt >= that)
}

运行结果:

true

[h2]operator func >>(Int64)

public operator func >>(n: Int64): BigInt

功能：右移运算。

参数：

n: Int64 - 右移 n 位，n 需要大于等于 0。

返回值：

BigInt - 返回此 BigInt 右移 n 位的结果。

异常：

ArithmeticException - 入参小于 0 时抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let rightShift = bigInt >> 10000
    println(rightShift)
}

运行结果:

-1

[h2]operator func /(BigInt)

public operator func /(that: BigInt): BigInt

功能：BigInt 除法。

除法运算的行为与基础类型保持一致，即结果向靠近 0 的方向取整。

参数：

that: BigInt - 除数。除数不得为 0。

返回值：

BigInt - 一个新 BigInt，它是此 BigInt 与另外一个 BigInt 相除后的结果。

异常：

ArithmeticException - 除数为 0 抛此异常。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-23456789123456789")
    let that = BigInt("-23456789123456789")
    let div = bigInt / that
    println(div)
}

运行结果:

[h2]operator func ^(BigInt)

public operator func ^(that: BigInt): BigInt

功能：按位异或。其功能是参与运算的两数各对应的二进位相异或。二进制位结果不相同时，异或结果为 1；二进制位结果相同时，异或结果为 0。

参数：

that: BigInt - 按位异或运算的另外一个 BigInt。

返回值：

BigInt - 返回与另一个 BigInt 的按位异或的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("-1")
    let that = BigInt("7")
    let xor = bigInt ^ that
    println(xor)
}

运行结果:

-8

[h2]operator func |(BigInt)

public operator func |(that: BigInt): BigInt

功能：按位或。其功能是参与运算的两数各对应的二进位相或。只有对应的两个二进位都为 0 时，结果位才为 0。

参数：

that: BigInt - 按位或运算的另外一个 BigInt。

返回值：

BigInt - 返回与另一个 BigInt 的按位或的结果。

示例：

import std.math.numeric.BigInt

main() {
    let bigInt = BigInt("8")
    let that = BigInt("7")
    let or = bigInt | that
    println(or)
}

运行结果:

目录

结构体

struct BigInt

[h2]prop bitLen

[h2]prop sign

[h2]init(Array<Byte>)

[h2]init(Bool, Array<Byte>)

[h2]init(Bool, Int64, Random)

[h2]init(Int16)

[h2]init(Int32)

[h2]init(Int64)

[h2]init(Int8)

[h2]init(IntNative)

[h2]init(String, Int64)

[h2]init(UInt16)

[h2]init(UInt32)

[h2]init(UInt64)

[h2]init(UInt8)

[h2]init(UIntNative)

[h2]static func randomProbablePrime(Int64, UInt64, Random)

[h2]func clearBit(Int64)

[h2]func compare(BigInt)

[h2]func divAndMod(BigInt)

[h2]func flipBit(Int64)

[h2]func hashCode()

[h2]func isProbablePrime(UInt64)

[h2]func lowestOneBit()

[h2]func modInverse(BigInt)

[h2]func modPow

[h2]func quo(BigInt)

[h2]func quoAndRem(BigInt)

[h2]func rem(BigInt)

[h2]func setBit(Int64)

[h2]func testBit(Int64)

[h2]func toBytes()

[h2]func toInt16(OverflowStrategy)

[h2]func toInt32(OverflowStrategy)

[h2]func toInt64(OverflowStrategy)

[h2]func toInt8(OverflowStrategy)

[h2]func toIntNative(OverflowStrategy)

[h2]func toString()

[h2]func toString(Int64)

[h2]func toUInt16(OverflowStrategy)

[h2]func toUInt32(OverflowStrategy)

[h2]func toUInt64(OverflowStrategy)

[h2]func toUInt8(OverflowStrategy)

[h2]func toUIntNative(OverflowStrategy)

[h2]operator func !()

[h2]operator func !=(BigInt)

[h2]operator func %(BigInt)

[h2]operator func &(BigInt)

[h2]operator func *(BigInt)

[h2]operator func **(UInt64)

[h2]operator func +(BigInt)

[h2]operator func -()

[h2]operator func -(BigInt)

[h2]operator func <(BigInt)

[h2]operator func <<(Int64)

[h2]operator func <=(BigInt)

[h2]operator func ==(BigInt)

[h2]operator func >(BigInt)

[h2]operator func >=(BigInt)

[h2]operator func >>(Int64)

[h2]operator func /(BigInt)

[h2]operator func ^(BigInt)

[h2]operator func |(BigInt)