结构体

struct BigInt

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

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

父类型：

prop bitLen

public prop bitLen: Int64

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

类型：Int64

prop sign

public prop sign: Int64

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

类型：Int64

init(Array<Byte>)

public init(bytes: Array<Byte>)

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

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

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

参数：

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

异常：

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

init(Bool, Array<Byte>)

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

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

参数：

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

异常：

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

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，则抛此异常。

init(Int16)

public init(n: Int16)

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

参数：

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

init(Int32)

public init(n: Int32)

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

参数：

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

init(Int64)

public init(n: Int64)

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

参数：

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

init(Int8)

public init(n: Int8)

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

参数：

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

init(IntNative)

public init(n: IntNative)

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

参数：

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

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] 区间内，抛此异常。

init(UInt16)

public init(n: UInt16)

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

参数：

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

init(UInt32)

public init(n: UInt32)

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

参数：

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

init(UInt64)

public init(n: UInt64)

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

参数：

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

init(UInt8)

public init(n: UInt8)

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

参数：

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

init(UIntNative)

public init(n: UIntNative)

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

参数：

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

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)
}

运行结果:

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)
}

运行结果:

func compare(BigInt)

public func compare(that: BigInt): Ordering

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

参数：

that: BigInt - 另一个 BigInt。

返回值：

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

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

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)
}

运行结果:

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)
}

运行结果:

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

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)
}

运行结果:

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)
}

运行结果:

func modPow(BigInt, BigInt)

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)
}

运行结果:

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)
}

运行结果:

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

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)
}

运行结果:

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)
}

运行结果:

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

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]

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

func toString(Int64)

public func toString(base: Int64): String

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

参数：

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

返回值：

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

异常：

IllegalArgumentException - 当入参 base 不在 [2, 36] 范围内时，抛出异常。

示例：

import std.math.numeric.BigInt

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

运行结果:

10000000000

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)
}

运行结果:

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)
}

运行结果:

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)
}

运行结果:

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

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)
}

运行结果:

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)
}

运行结果:

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

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)
}

运行结果:

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)
}

运行结果:

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

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

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

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

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

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

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

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

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

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

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

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

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)
}

运行结果:

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

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 Decimal

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

功能：Decimal 用于表示任意精度的有符号的十进制数。允许操作过程指定结果精度及舍入规则。提供基础类型 (Int、UInt、String、Float等) 与 BigInt 类型互相转换能力，支持 Decimal 对象基本属性查询等能力，支持基础数学运算操作，提供对象比较、hash、字符串打印等基础能力。

父类型：

prop precision

public prop precision: Int64

功能：获取 Decimal 精度值，即无标度整数部分十进制有效数字位数，非负数。如果精度值为0，表示无精度限制。

类型：Int64

prop scale

public prop scale: Int32

功能：获取 Decimal 标度值。

类型：Int32

prop sign

public prop sign: Int64

功能：获取 Decimal 实例符号值。

Decimal 值大于 0，返回 1；
Decimal 值等于 0，返回 0；
Decimal 值小于 0，返回 -1。

类型：Int64

prop value

public prop value: BigInt

功能：获取 Decimal 无标度整数值，BigInt 承载。

类型：BigInt

init(BigInt)

public init(val: BigInt)

功能：通过有符号大整数 BigInt 构建 Deciaml 结构体。默认采用精度值为0，即无限精度进行构建。

参数：

val: BigInt - 有符号大整数值。

init(BigInt, Int32)

public init(val: BigInt, scale: Int32)

功能：通过有符号大整数 BigInt 和标度值构建 Deciaml 结构体。默认采用精度值为0，即无限精度进行构建。

参数：

val: BigInt - 有符号大整数值。
scale: Int32 - 标度值。

init(Float16)

public init(val: Float16)

功能：通过 16 位有符号浮点数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

注意：

由于部分十进制小数无法通过二进制浮点数精确表示，此构造函数以精确值构建 Decimal 对象，传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数：

val: Float16 - 16 位有符号二进制浮点数。

异常：

IllegalArgumentException - 当入参为 inf、-inf 或 nan 时，抛出此异常。

init(Float32)

public init(val: Float32)

功能：通过 32 位有符号浮点数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

注意：

由于部分十进制小数无法通过二进制浮点数精确表示，此构造函数以精确值构建 Decimal 对象，传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数：

val: Float32 - 32 位有符号二进制浮点数。

异常：

IllegalArgumentException - 当入参为 inf、-inf 或 nan 时，抛出此异常。

init(Float64)

public init(val: Float64)

功能：通过 64 位有符号浮点数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

注意：

由于部分十进制小数无法通过二进制浮点数精确表示，此构造函数以精确值构建 Decimal 对象，传入浮点数值可能与最终构建 Decimal 对象字符串打印值不一致。

参数：

val: Float64 - 64 位有符号二进制浮点数。

异常：

IllegalArgumentException - 当入参为 inf、-inf 或 nan 时，抛出此异常。

init(Int16)

public init(val: Int16)

功能：通过 16 位有符号整数构建 Decimal 结构体。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(Int32)

public init(val: Int32)

功能：通过 32 位有符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(Int64)

public init(val: Int64)

功能：通过 64 位有符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(Int8)

public init(val: Int8)

功能：通过 8 位有符号整数构建 Decimal 结构体。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(IntNative)

public init(val: IntNative)

功能：通过 32 位或 64 位 (具体长度与平台相关) 有符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

val: IntNative - 32 位或 64位有符号整数。

init(String)

public init(val: String)

功能：通过规定格式字符串构建 Decimal 结构体。默认采用精度值为0，即无限精度进行构建。字符串需满足如下格式，即开头可选的符号（正号或负号），接 ValueString 字符串，再接可选的 ExponentString 字符串：

Decimal 字符串: (SignString)? ValueString (ExponentString)?

SignString：+ | -
ValueString：IntegerPart.(FractionPart)? | .FractionPart | IntegerPart
- IntegerPart：Digits
- FractionPart：Digits
- Digits: Digit | Digit Digits
  - Digit：'0' ~ '9'
ExponentString：ExponentIndicator (SignString)? IntegerPart
- ExponentIndicator：e | E

参数：

val: String - 规定格式字符串。

异常：

IllegalArgumentException - 当入参字符串不满足规定格式时，抛此异常。
OverflowException - 当构建值标度溢出时，抛此异常。

init(UInt16)

public init(val: UInt16)

功能：通过 16 位无符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(UInt32)

public init(val: UInt32)

功能：通过 32 位无符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(UInt64)

public init(val: UInt64)

功能：通过 64 位无符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(UInt8)

public init(val: UInt8)

功能：通过 8 位无符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

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

init(UIntNative)

public init(val: UIntNative)

功能：通过 32 位或 64 位 (具体长度与平台相关) 无符号整数构建 Decimal 对象。默认采用精度值为0，即无限精度进行构建。

参数：

val: UIntNative - 32 位或 64位无符号整数。

func compare(Decimal)

public func compare(d: Decimal): Ordering

功能：比较当前对象与入参 Decimal 对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Ordering - 返回比较结果，当前对象小于入参时，返回 Ordering.LT，大于入参时，返回 Ordering.GT，否则返回 Ordering.EQ。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3)

    let C = A.compare(B)
    println(C)
}

运行结果:

Ordering.LT

func divWithPrecision(Decimal, Int64, RoundingMode)

public func divWithPrecision(d: Decimal, precision: Int64, roundingMode!: RoundingMode = HALF_EVEN): Decimal

功能：除法运算，支持自定义运算精度和舍入方式，除以入参 Decimal 对象，返回结果值，如果结果精度超过 precision 指定精度，则根据指定的精度对除法运算结果进行舍入。

参数：

d: Decimal - Decimal 除数对象。
precision: Int64 - 精度值。
roundingMode!: RoundingMode - 舍入规则。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储除法运算结果值。

异常：

ArithmeticException - 当除数为 0 时，抛出此异常。
OverflowException - 当除法结果值范围超过 [-(maxValue(precision) * (10 ^Int32.MAX)), maxValue(precision) * (10 ^Int32.MAX)] 时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A.divWithPrecision(B, 0)
    println("C = ${C}")
}

运行结果:

C = 0.6666666666666666666666666666666667

func divAndRem(Decimal)

public func divAndRem(d: Decimal): (BigInt, Decimal)

功能：除法取商和余数运算，除以入参 Decimal 对象，返回整数商值和余数值。结果保留实际精度值。

参数：

d: Decimal - Decimal 除数对象。

返回值：

(BigInt, Decimal) - 生成一个元组对象，分别用于存储整数商值结果和余数结果值。

异常：

IllegalArgumentException - 当除数为 0 时，抛出此异常。
OverflowException - 当除法结果值范围超过 [-(maxValue(precision) * (10 ^Int32.MAX)), maxValue(precision) * (10 ^Int32.MAX)] 时，抛出此异常。

func hashCode()

public func hashCode(): Int64

功能：获取当前对象哈希值。

返回值：

Int64 - 返回当前对象哈希值。

func isInteger()

public func isInteger(): Bool

功能：判断当前 Decimal 对象是否为整数。

返回值：

Bool - 返回当前对象是否为整数判断结果。当前对象为整数时返回 true，否则返回 false。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(100)
    println("${A}.isInteger() = ${A.isInteger()}")
}

运行结果:

100.isInteger() = true

func powWithPrecision(Int64, Int64, RoundingMode)

public func powWithPrecision(n: Int64, precision: Int64, roundingMode!: RoundingMode = RoundingMode.HALF_EVEN): Decimal

功能：乘方运算，支持自定义运算精度和舍入方式，获取当前对象为底数，入参 Int64 为指数的乘方运算结果，如果运算结果超过 precision 指定的精度，则根据指定的精度对乘方结果进行舍入。

参数：

n: Int64 - 乘方运算的指数值。
precision: Int64 - 精度值。
roundingMode!: RoundingMode - 舍入规则。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储乘方运算结果值。

异常：

OverflowException - 当乘方运算结果标度值溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2.5)
    println("A.powWithPrecision(3, 0) = ${A.powWithPrecision(3, 0, roundingMode: HALF_EVEN)}")
}

运行结果:

A.powWithPrecision(3, 0) = 15.625

func reScale(Int32, RoundingMode)

public func reScale(newScale: Int32, roundingMode!: RoundingMode = HALF_EVEN): Decimal

功能：调整 Decimal 对象标度值，允许指定舍入规则，返回标度调整后新的 Decimal 对象。

参数：

newScale: Int32 - 新的标度值。
roundingMode!: RoundingMode - 舍入规则。

返回值：

Decimal - 新的标度值的 Decimal 对象。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.234568)
    println("A.reScale(3) = ${A.reScale(3)}")
}

运行结果:

A.reScale(3) = 1.235

func removeTrailingZeros()

public func removeTrailingZeros(): Decimal

功能：对当前 Decimal 对象移除尾部零，不改变对象数值。

返回值：

Decimal - 新的无尾部零的 Decimal 对象。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.00)
    println("A.removeTrailingZeros() = ${A.removeTrailingZeros()}")
}

运行结果:

A.removeTrailingZeros() = 1

func roundWithPrecision(Int64, RoundingMode)

public func roundWithPrecision(precision: Int64, roundingMode!: RoundingMode = RoundingMode.HALF_EVEN): Decimal

功能：按照指定舍入精度和舍入规则对当前 Decimal 对象进行舍入操作。

参数：

precision: Int64 - 精度值。
roundingMode!: RoundingMode - 舍入规则。

返回值：

Decimal - 舍入操作生成的新的 Decimal 对象。

异常：

OverflowException - 当舍入操作结果标度值溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.0)
    println("A.roundWithPrecision(1.0) = ${A.roundWithPrecision(0, roundingMode: HALF_EVEN)}")
    let B = Decimal(0.1f16).roundWithPrecision(5, roundingMode: UP)
    println("B = ${B}")
}

运行结果:

A.roundWithPrecision(1.0) = 1
B = 0.099976

func scaleUnit()

public func scaleUnit(): Decimal

功能：对当前 Decimal 对象返回标度单位，即数值为 1 ，标度值与当前对象相等的 Decimal 对象。

返回值：

Decimal - 标度单位 Decimal 对象。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(100)
    println("A.scaleUnit() = ${A.scaleUnit()}")
}

运行结果:

A.scaleUnit() = 1

func shiftPoint(Int32)

public func shiftPoint(n: Int32): Decimal

功能：移动当前 Decimal 对象小数点 abs(n) 位返回结果对象，当 n 为正数时，左移小数点，n 为负数时，右移小数点，n 为零时，返回当前对象。

参数：

n: Int32 - 指定小数点移动位数及方向。

返回值：

Decimal - 对当前对象小数点移动指定位数后生成新的 Decimal 对象。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(25)
    println("A.shiftPoint(1) = ${A.shiftPoint(1)}")
}

运行结果:

A.shiftPoint(-1) = 2.5

func sqrtWithPrecision(Int64, RoundingMode)

public func sqrtWithPrecision(precision: Int64, roundingMode!: RoundingMode = RoundingMode.HALF_EVEN): Decimal

功能：开方运算，支持自定义运算精度和结果舍入方式，获取当前对象开方结果，如果运算结果超过 presision 指定的精度，则根据指定的精度对开方结果进行舍入。

参数：

precision: Int64 - 精度值。
roundingMode!: RoundingMode - 舍入规则。

返回值：

Decimal - 返回入参 Decimal 的算术平方根，根据输入精度和舍入方式进行取整。

异常：

IllegalArgumentException - 如果被计算平方根的对象为负数，则抛此异常。
OverflowException - 当计算平方根操作结果标度值溢出时，抛出此异常。

示例：

import std.math.numeric.*

main() {
    let n: Decimal = Decimal("2")
    let s = n.sqrtWithPrecision(2)
    println(s)
}

运行结果:

1.4

func toBigInt()

public func toBigInt(): BigInt

功能：将当前 Decimal 对象转化为 BigInt 类型。

返回值：

BigInt - 转换后的 BigInt 值。

func toEngString()

public func toEngString(): String

功能：以工程计数法的形式打印输出 Decimal 对象，指数为 3 的倍数, 当值小于 0 时以 “-” 开头后跟十进制数字，大于等于 0 时，直接打印输出数字，不额外添加 “+”。指数小于 0 时同样遵循以上规则。

返回值：

String - 工程计数法形式的 Decimal 字符串。

func toSciString()

public func toSciString(): String

功能：以科学计数法的形式打印输出 Decimal 对象，当值小于 0 时以 “-” 开头后跟十进制数字，大于等于 0 时，直接打印输出数字，不额外添加 “+”。指数小于 0 时同样遵循以上规则。

返回值：

String - 科学计数法形式的 Decimal 字符串。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(6.25)
    println("A.toFloat16() = ${A.toFloat16()}")
    println("A.toFloat32() = ${A.toFloat32()}")
    println("A.toFloat64() = ${A.toFloat64()}")
    println("A.toBigInt() = ${A.toBigInt()}")
    println("A.toEngString() = ${A.toEngString()}")
    println("A.toSciString() = ${A.toSciString()}")
}

运行结果:

A.toFloat16() = 6.250000
A.toFloat32() = 6.250000
A.toFloat64() = 6.250000
A.toBigInt() = 6
A.toEngString() = 6.25E0
A.toSciString() = 6.25E0

func toFloat16()

public func toFloat16(): Float16

功能：将当前 Decimal 对象转化为 Float16 类型。

返回值：

Float16 - 转换后的 Float16 值，溢出时，当前值为正数，返回 inf，当前值为负数，返回 -inf。

func toFloat32()

public func toFloat32(): Float32

功能：将当前 Decimal 对象转化为 Float32 类型。

返回值：

Float32 - 转换后的 Float32 值，溢出时，当前值为正数，返回 inf，当前值为负数，返回 -inf。

func toFloat64()

public func toFloat64(): Float64

功能：将当前 Decimal 对象转化为 Float64 类型。

返回值：

Float64 - 转换后的 Float64 值，溢出时，当前值为正数，返回 inf，当前值为负数，返回 -inf。

func toInt16(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int16 - 转换后的 Int16 值。

异常：

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

func toInt32(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int32 - 转换后的 Int32 值。

异常：

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

func toInt64(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int64 - 转换后的 Int64 值。

异常：

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

func toInt8(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

Int8 - 转换后的 Int8 值。

异常：

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

func toIntNative(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

IntNative - 转换后的 IntNative 值。

异常：

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

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(6.25)
    println("A.toInt8() = ${A.toInt8()}")
    println("A.toInt16() = ${A.toInt16()}")
    println("A.toInt32() = ${A.toInt32()}")
    println("A.toInt64() = ${A.toInt64()}")
    println("A.toIntNative() = ${A.toIntNative()}")
}

运行结果:

A.toInt8() = 6
A.toInt16() = 6
A.toInt32() = 6
A.toInt64() = 6
A.toIntNative() = 6

func toString()

public func toString(): String

功能：以不带指数形式打印输出 Decimal 对象，小于 0 时以 “-” 开头后跟十进制数字，大于等于 0 时，直接打印输出数字，不额外添加 “+”。

返回值：

String - 不带指数形式的 Decimal 字符串。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3 ** 5)

    println("A.hashCode() = ${A.hashCode()}")
    println("B.toString() = ${B.toString()}")
}

运行结果:

A.hashCode() = 155
B.toString() = 243

func toUInt16(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt16 - 转换后的 UInt16 值。

异常：

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

func toUInt32(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt32 - 转换后的 UInt32 值。

异常：

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

func toUInt64(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt64 - 转换后的 UInt64 值。

异常：

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

func toUInt8(OverflowStrategy)

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

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

入参：

overflowHanding!: OverflowStrategy - 转换溢出策略。

返回值：

UInt8 - 转换后的 UInt8 值。

异常：

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

func toUIntNative(OverflowStrategy)

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

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

入参：

overflowHandling!: OverflowStrategy - 转换溢出策略。

返回值：

UIntNative - 转换后的 UIntNative 值。

异常：

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

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(6.25)
    println("A.toUInt8() = ${A.toUInt8()}")
    println("A.toUInt16() = ${A.toUInt16()}")
    println("A.toUInt32() = ${A.toUInt32()}")
    println("A.toUInt64() = ${A.toUInt64()}")
    println("A.toUIntNative() = ${A.toUIntNative()}")
}

运行结果:

A.toUInt8() = 6
A.toUInt16() = 6
A.toUInt32() = 6
A.toUInt64() = 6
A.toUIntNative() = 6

operator func !=(Decimal)

public operator func !=(d: Decimal): Bool

功能：不等比较运算，不等运算符重载，判断入参 Decimal 对象与当前对象是否不相等，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回不等比较运算结果。当前对象不等于入参时，返回 true，否则返回 false。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3)

    println(" -A = ${-A}")
    println(" A <= B = ${ A <= B}")
    println(" A != B = ${ A != B}")
}

运行结果：

-A = 5
A <= B = true
A != B = true

operator func *(Decimal)

public operator func *(d: Decimal): Decimal

功能：乘法运算，乘法运算符重载，乘以入参 Decimal 对象，返回结果值。保留乘法运算结果实际精度值。

参数：

d: Decimal - Decimal 乘数对象。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储乘法运算结果值。

异常：

OverflowException - 当两个乘数标度值相加溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A * B
    println("C = ${C}")
}

运行结果:

C = 6

operator func **(Int64)

public operator func **(n: Int64): Decimal

功能：乘方运算，乘方运算符重载，获取当前对象为底数，入参 Int64 为指数的乘方运算结果，其中指数为入参 Decimal 对象的整数部分。

注意：

指数为负值且结果为无限小数场景时，默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数：

n: Int64 - 乘方运算的指数值。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储乘方运算结果值。

异常：

OverflowException - 当乘方运算结果标度值溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2.5)
    println("A ** 3 = ${A ** 3}")
}

运行结果:

A ** 3 = 15.625

operator func +(Decimal)

public operator func +(d: Decimal): Decimal

功能：加法运算，加法运算符重载，加上入参 Decimal 对象，返回结果值。结果保留实际精度值。

参数：

d: Decimal - Decimal 加数对象。

异常：

OverflowException - 当两个加数标度值相减溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A + B
    println("C = ${C}")
}

运行结果:

C = 5

operator func -()

public operator func -(): Decimal

功能：取反运算，一元负数运算符重载，对当前 Decimal 对象取反，返回结果值。保留取反运算结果实际精度值。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储取反结果值。

operator func -(Decimal)

public operator func -(d: Decimal): Decimal

功能：减法运算，减法运算符重载，减去入参 Decimal 对象，返回结果值。保留减法运算结果实际精度值。

参数：

d: Decimal - Decimal 减数对象。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储减法运算结果值。

异常：

OverflowException - 当被减数与减数标度值相减溢出时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A - B
    println("C = ${C}")
}

运行结果:

C = -1

operator func <(Decimal)

public operator func <(d: Decimal): Bool

功能：小于比较运算，小于运算符重载，判断入参 Decimal 对象是否小于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回小于比较运算结果。当前对象小于入参时，返回 true，否则返回 false。

operator func <=(Decimal)

public operator func <=(d: Decimal): Bool

功能：小于等于比较运算，小于等于运算符重载，判断入参 Decimal 对象是否小于等于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回小于等于比较运算结果。当前对象小于等于入参时，返回 true，否则返回 false

operator func ==(Decimal)

public operator func ==(d: Decimal): Bool

功能：等于比较运算，等于运算符重载，判断入参 Decimal 对象与当前对象是否相等，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回等于比较运算结果。当前对象等于入参时，返回 true，否则返回 false。

operator func >(Decimal)

public operator func >(d: Decimal): Bool

功能：大于比较运算，大于运算符重载，判断入参 Decimal 对象是否大于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象

返回值：

Bool - 返回大于比较运算结果。当前对象大于入参时，返回 true，否则返回 false

operator func >=(Decimal)

public operator func >=(d: Decimal): Bool

功能：大于等于比较运算，大于等于运算符重载，判断入参 Decimal 对象是否大于等于当前对象，返回比较结果值。

参数：

d: Decimal - Decimal 待比较对象。

返回值：

Bool - 返回大于等于比较运算结果。当前对象大于等于入参时，返回 true，否则返回 false。

operator func /(Decimal)

public operator func /(d: Decimal): Decimal

功能：除法运算，除法运算符重载，除以入参 Decimal 对象，返回结果值。

注意：

结果为无限小数场景时，默认采用 IEEE 754-2019 decimal128 对结果进行舍入。

参数：

d: Decimal - Decimal 除数对象。

返回值：

Decimal - 生成一个新的 Decimal 对象，用于存储除法运算结果值。

异常：

IllegalArgumentException - 当除数为 0 时，抛出此异常。
OverflowException - 当除法结果值范围超过 [-(maxValue(precision) * (10 ^Int32.MAX)), maxValue(precision) * (10 ^Int32.MAX)] 时，抛出此异常。

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2)
    let B = Decimal(3)
    let C = A / B
    println("C = ${C}")
}

运行结果:

C = 0.6666666666666666666666666666666667

仓颉编程语言库 API