结构体

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> - 大端二进制补码数组，数组长度不能为空。

异常：

init(Bool, Array<Byte>)

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

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

参数：

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

异常：

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 - 指定的随机数种子。

异常：

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 结构体。

参数：

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 - 返回生成的随机素数。

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

11

func clearBit(Int64)

public func clearBit(index: Int64): BigInt

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

参数：

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

返回值：

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

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

0

func compare(BigInt)

public func compare(that: BigInt): Ordering

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

参数：

返回值：

func divAndMod(BigInt)

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

功能：BigInt 的除法运算。

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

参数：

  • that: BigInt - 除数。除数不得为 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 翻转后的产物。

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

0

func hashCode()

public func hashCode(): Int64

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

返回值：

示例：

import std.math.numeric.BigInt

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

运行结果:

1024

func isProbablePrime(UInt64)

public func isProbablePrime(certainty: UInt64): Bool

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

说明：

该函数使用了 Miller-Rabin 测试算法，此算法的准确率会随着 certainty 参数的增加而增加。如果该数是素数，那么 Miller-Rabin 测试必定返回 true；如果该数是合数（期待返回 false），那么会有低于 1/4certainty 概率返回 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)
}

运行结果:

0

func modInverse(BigInt)

public func modInverse(that: BigInt): BigInt

功能：求模逆元。

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

参数：

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

返回值：

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

1

func modPow

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

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

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

参数：

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

返回值：

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

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

1024

func quo(BigInt)

public func quo(that: BigInt): BigInt

功能：BigInt 的除法运算。

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

参数：

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

返回值：

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

2

func quoAndRem(BigInt)

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

功能：BigInt 的除法运算。

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

参数：

  • that: BigInt - 除数。除数不得为 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。

返回值：

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

1

func setBit(Int64)

public func setBit(index: Int64): BigInt

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

参数：

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

返回值：

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

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

1024

func testBit(Int64)

public func testBit(index: Int64): Bool

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

参数：

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

返回值：

  • Bool - 指定位置的 bit 信息。

异常：

示例：

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）。

返回值：

示例：

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 值。

返回值：

异常：

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

运行结果:

32767

func toInt32(OverflowStrategy)

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

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

参数：

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

返回值：

异常：

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

运行结果:

255

func toInt64(OverflowStrategy)

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

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

参数：

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

返回值：

异常：

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

运行结果:

0

func toInt8(OverflowStrategy)

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

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

参数：

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

返回值：

异常：

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

运行结果:

127

func toIntNative(OverflowStrategy)

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

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

参数：

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

返回值：

异常：

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

运行结果:

0

func toString()

public func toString(): String

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

返回值：

示例：

import std.math.numeric.BigInt

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

运行结果:

1024

func toString(Int64)

public func toString(base: Int64): String

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

参数：

  • base: Int64 - 进制。字符串所表示的进制，范围为 [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 值。

返回值：

异常：

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

运行结果:

0

func toUInt32(OverflowStrategy)

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

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

参数：

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

返回值：

异常：

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

运行结果:

0

func toUInt64(OverflowStrategy)

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

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

参数：

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

返回值：

异常：

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

运行结果:

0

func toUInt8(OverflowStrategy)

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

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

参数：

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

返回值：

异常：

  • 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 值。

返回值：

异常：

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

运行结果:

0

operator func !()

public operator func !(): BigInt

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

返回值：

示例：

import std.math.numeric.BigInt

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

运行结果:

0

operator func !=(BigInt)

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

功能：判不等运算。

参数：

返回值：

  • 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。

返回值：

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

0

operator func &(BigInt)

public operator func &(that: BigInt): BigInt

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

参数：

返回值：

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

示例：

import std.math.numeric.BigInt

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

运行结果:

0

operator func *(BigInt)

public operator func *(that: 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 次幂。

参数：

返回值：

示例：

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 加法。

参数：

返回值：

示例：

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 的相反数。

返回值：

示例：

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 减法。

参数：

返回值：

示例：

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

功能：小于比较运算。

参数：

返回值：

  • 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。

返回值：

异常：

示例：

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

功能：判等运算。

参数：

返回值：

  • 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

功能：大于比较运算。

参数：

返回值：

  • 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。

返回值：

异常：

示例：

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。

返回值：

异常：

示例：

import std.math.numeric.BigInt

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

运行结果:

1

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。

参数：

返回值：

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

示例：

import std.math.numeric.BigInt

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

运行结果:

15

struct Decimal

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

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

static let defaultDecimalContext

public static let defaultDecimalContext: DecimalContext

功能：默认上下文，精度值为 0，舍入规则为 “银行家舍入”。即无精度限制，保留操作结果实际精度，在操作结果为无限小数场景下，默认遵循 IEEE 754-2019 decimal128 规则，精度保留 34 位 “银行家” 规则舍入。

返回值：DecimalContext 默认值

类型：DecimalContext

prop precision

public prop precision: Int64

功能：获取 Decimal 精度值，即无标度整数部分十进制有效数字位数，非负数。

类型：Int64

prop scale

public prop scale: Int32

功能：获取 Decimal 标度值。

类型：Int32

prop sign

public prop sign: Int64

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

类型：Int64

prop value

public prop value: BigInt

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

类型：BigInt

init(BigInt, Int32, DecimalContext)

public init(val: BigInt, scale: Int32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过有符号大整数 BigInt 和标度值构建 Deciaml 结构体。

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

异常：

  • OverflowException - 当构建值范围超过 [-(maxValue(ctx.precision) * (10 Int32.MAX )), maxValue(ctx.precision) * (10 Int32.MAX)] 时，抛出此异常。

init(Float16, DecimalContext)

public init(val: Float16, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 16 位有符号浮点数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

注意：

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

参数：

异常：

init(Float32, DecimalContext)

public init(val: Float32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位有符号浮点数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

注意：

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

参数：

异常：

init(Float64, DecimalContext)

public init(val: Float64, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 64 位有符号浮点数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

注意：

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

参数：

异常：

init(Int16, DecimalContext)

public init(val: Int16, ctx!: DecimalContext = defaultDecimalContext)

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

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(Int32, DecimalContext)

public init(val: Int32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位有符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(Int64, DecimalContext)

public init(val: Int64, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 64 位有符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(Int8, DecimalContext)

public init(val: Int8, ctx!: DecimalContext = defaultDecimalContext)

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

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(IntNative, DecimalContext)

public init(val: IntNative, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位或 64 位 (具体长度与平台相关) 有符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(String, DecimalContext)

public init(val: String, ctx!: DecimalContext = defaultDecimalContext)

功能：通过规定格式字符串构建 Decimal 结构体。

允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。 字符串需满足格式如下，即开头可选的符号（正号或负号），接 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

参数：

异常：

init(UInt16, DecimalContext)

public init(val: UInt16, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 16 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(UInt32, DecimalContext)

public init(val: UInt32, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(UInt64, DecimalContext)

public init(val: UInt64, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 64 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(UInt8, DecimalContext)

public init(val: UInt8, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 8 位无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

init(UIntNative, DecimalContext)

public init(val: UIntNative, ctx!: DecimalContext = defaultDecimalContext)

功能：通过 32 位或 64 位 (具体长度与平台相关) 无符号整数构建 Decimal 对象。允许自行指定上下文，对构建结果限制精度，按指定舍入规则进行舍入操作。默认采用 defaultDecimalContext 即无限精度进行构建。

参数：

func abs()

public func abs(): Decimal

功能：获取当前 Decimal 对象的绝对值。

返回值：

func add(Decimal)

public func add(d: Decimal): Decimal

功能：加法运算，加上入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留加和结果实际精度值。

参数：

返回值：

  • Decimal - 生成一个新的 Decimal 对象，用于存储两个加数的加和结果值。

异常：

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

示例：

import std.math.numeric.Decimal

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

运行结果:

C = 5

func add(Decimal, DecimalContext)

public func add(d: Decimal, ctx: DecimalContext): Decimal

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

参数：

返回值：

  • Decimal - 生成一个新的 Decimal 对象，用于存储两个加数的加和结果值。

异常：

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

示例：

import std.math.numeric.Decimal

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

运行结果:

C = 5

func compare(Decimal)

public func compare(d: Decimal): Ordering

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

参数：

返回值：

示例：

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 div(Decimal)

public func div(d: Decimal): Decimal

功能：除法运算，除以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留除法运算结果实际精度值。

注意：

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

参数：

返回值：

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

异常：

func div(Decimal, DecimalContext)

public func div(d: Decimal, ctx: DecimalContext): Decimal

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

参数：

返回值：

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

异常：

示例：

import std.math.numeric.Decimal

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

运行结果:

C = 0.6666666666666666666666666666666667

func divAndRem(Decimal)

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

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

参数：

返回值：

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

异常：

func divAndRem(Decimal, DecimalContext)

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

功能：除法取商和余数运算，支持自定义运算上下文，除以入参 Decimal 对象，返回整数商值和余数值。如果结果精度超过上下文指定精度，则根据指定的上下文对除法运算结果进行舍入。

注意：

这里传入的舍入规则是无效的，默认使用 RoundingMode.DOWN。

参数：

返回值：

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

异常：

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(5)
    let B = Decimal(3)
    let (C, D)= A.divAndRem(B, Decimal.defaultDecimalContext)
    println("C = ${C}, D = ${D}")
}

运行结果:

C = 1, D = 2

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 mul(Decimal)

public func mul(d: Decimal): Decimal

功能：乘法运算，乘以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留乘法运算结果实际精度值。

参数：

返回值：

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

异常:

func mul(Decimal, DecimalContext)

public func mul(d: Decimal, ctx: DecimalContext): Decimal

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

参数：

返回值：

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

异常:

示例：

import std.math.numeric.Decimal

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

运行结果:

C = 6

func neg()

public func neg(): Decimal

功能：取反运算，对当前 Decimal 对象取反，返回结果值。上下文默认 defaultDecimalContext 保留取反运算结果实际精度值。

返回值：

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

func neg(DecimalContext)

public func neg(ctx: DecimalContext): Decimal

功能：取反运算，支持自定义运算上下文，对当前 Decimal 对象取反，返回结果值。如果结果精度超过上下文指定精度，则根据指定的上下文对取反运算结果进行舍入。

参数：

返回值：

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

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(-5)
    let B = Decimal(3)
    let C = A.neg()
    let D = B.neg(Decimal.defaultDecimalContext)
    println("C = ${C}, D = ${D}")
}

运行结果:

C = 5, D = -3

func pow(Int64)

public func pow(n: Int64): Decimal

功能：乘方运算，获取当前对象为底数，入参 Int64 为指数的乘方运算结果。

注意：

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

参数：

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

返回值：

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

异常：

func pow(Int64, DecimalContext)

public func pow(n: Int64, ctx: DecimalContext): Decimal

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

参数：

返回值：

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

异常：

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(2.5)
    println("A.pow(3, DecimalContext) = ${A.pow(3, Decimal.defaultDecimalContext)}")
}

运行结果:

A.pow(3, DecimalContext) = 15.625

func reScale(Int32, RoundingMode)

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

功能：调整 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 对象移除尾部零，不改变对象数值。

返回值：

示例：

import std.math.numeric.Decimal

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

运行结果:

A.removeTrailingZeros() = 1

func round(DecimalContext)

public func round(ctx: DecimalContext): Decimal

功能：按照指定上下文（舍入精度、舍入规则）对当前 Decimal 对象进行舍入操作。

参数：

返回值：

异常：

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(1.0)
    println("A.round(1.0) = ${A.round(Decimal.defaultDecimalContext)}")
}

运行结果:

A.round(1.0) = 1

func scaleUnit()

public func scaleUnit(): Decimal

功能：对当前 Decimal 对象返回标度单位，即数值为 1 ，标度值与当前对象相等的 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 sqrt(DecimalContext)

public func sqrt(ctx!: DecimalContext = defaultDecimalContext): Decimal

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

入参：

返回值：

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

异常：

示例：

import std.math.numeric.Decimal

main(): Unit {
    let A = Decimal(0.25)
    println("A.abs() = ${A.abs()}")
    println("A.sqrt() = ${A.sqrt()}")
}

运行结果:

A.abs() = 0.25
A.sqrt() = 0.5

func sub(Decimal)

public func sub(d: Decimal): Decimal

功能：减法运算，减去入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留减法运算结果实际精度值。

参数：

返回值：

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

异常：

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

func sub(Decimal, DecimalContext)

public func sub(d: Decimal, ctx: DecimalContext): Decimal

功能：减法运算，支持自定义运算上下文，减去入参 Decimal 对象，返回结果值，如果结果精度超过上下文指定精度，则根据指定的上下文对减法运算结果进行舍入。

参数：

返回值：

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

异常：

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

示例：

import std.math.numeric.Decimal

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

运行结果:

C = -1

func toBigInt()

public func toBigInt(): BigInt

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

返回值：

func toEngString()

public func toEngString(): String

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

返回值：

func toSciString()

public func toSciString(): String

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

返回值：

示例：

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 类型，支持自定义溢出策略。

入参：

返回值：

异常：

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

func toInt32(OverflowStrategy)

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

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

入参：

返回值：

异常：

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

func toInt64(OverflowStrategy)

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

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

入参：

返回值：

异常：

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

func toInt8(OverflowStrategy)

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

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

入参：

返回值：

异常：

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

func toIntNative(OverflowStrategy)

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

功能：将当前 Decimal 对象转化为 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 时，直接打印输出数字，不额外添加 “+”。

返回值：

示例：

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 类型，支持自定义溢出策略。

入参：

返回值：

异常：

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

func toUInt32(OverflowStrategy)

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

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

入参：

返回值：

异常：

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

func toUInt64(OverflowStrategy)

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

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

入参：

返回值：

异常：

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

func toUInt8(OverflowStrategy)

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

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

入参：

返回值：

异常：

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

func toUIntNative(OverflowStrategy)

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

功能：将当前 Decimal 对象转化为 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 对象与当前对象是否不相等，返回比较结果值。

参数：

返回值：

  • 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

功能：乘法运算，乘法运算符重载，行为与 mul 函数相同，乘以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留乘法运算结果实际精度值。

参数：

返回值：

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

异常：

示例：

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

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

注意：

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

参数：

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

返回值：

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

异常：

示例：

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

功能：加法运算，加法运算符重载，行为与 add 函数相同，加上入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留加合结果实际精度值。

参数：

异常：

示例：

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

功能：取反运算，一元负数运算符重载，行为与 neg 函数相同，对当前 Decimal 对象取反，返回结果值。上下文默认 defaultDecimalContext 保留取反运算结果实际精度值。

返回值：

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

operator func -(Decimal)

public operator func -(d: Decimal): Decimal

功能：减法运算，减法运算符重载，行为与 sub 函数相同，减去入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留减法运算结果实际精度值。

参数：

返回值：

  • 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 对象是否小于当前对象，返回比较结果值。

参数：

返回值：

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

operator func <=(Decimal)

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

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

参数：

返回值：

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

operator func ==(Decimal)

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

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

参数：

返回值：

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

operator func >(Decimal)

public operator func >(d: Decimal): Bool

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

参数：

返回值：

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

operator func >=(Decimal)

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

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

参数：

返回值：

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

operator func /(Decimal)

public operator func /(d: Decimal): Decimal

功能：除法运算，除法运算符重载，行为与 div 函数相同，除以入参 Decimal 对象，返回结果值。上下文默认 defaultDecimalContext 保留除法运算结果实际精度值。

注意：

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

参数：

返回值：

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

异常：

示例：

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

struct DecimalContext

public struct DecimalContext {
    public init(precision: Int64, roundingMode: RoundingMode)
}

功能：DecimalContext 对象作用于用户对 Decimal 操作过程中，对生成结果指定上下文，设定结果的精度与对应舍入规则。

let precision

public let precision: Int64

功能：获取上下文中指定的精度值。

类型：Int64

let roundingMode

public let roundingMode: RoundingMode

功能：获取上下文中指定的舍入规则。

类型：RoundingMode

init(Int64, RoundingMode)

public init(precision: Int64, roundingMode: RoundingMode)

功能：指定精度与舍入规则构建上下文结构体，可作用于 Decimal 操作结果。

参数：

  • precision: Int64 - 精度值，限制 Decimal 结果有效数值位数。
  • roundingMode: RoundingMode - 舍入规则，Decimal 结果有效位超出精度限制时舍入操作遵循该指定规则。

异常：