结构体

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,它是将原 BigIntindex 处的 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$。显然,thisthat 必须互质。当 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(BigInt, BigInt)

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 用于表示任意精度的有符号的十进制数。允许操作过程指定结果精度及舍入规则。提供基础类型 (IntUIntStringFloat等) 与 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 实例符号值。

类型: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 位有符号二进制浮点数。

异常:

init(Float32)

public init(val: Float32)

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

注意:

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

参数:

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

异常:

init(Float64)

public init(val: Float64)

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

注意:

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

参数:

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

异常:

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 - 规定格式字符串。

异常:

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 对象,返回比较结果值。

参数:

返回值:

示例:

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 指定精度,则根据指定的精度对除法运算结果进行舍入。

参数:

返回值:

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

异常:

示例:

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 对象,返回整数商值和余数值。结果保留实际精度值。

参数:

返回值:

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

异常:

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 对象,用于存储乘方运算结果值。

异常:

示例:

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 对象。

参数:

返回值:

示例:

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 roundWithPrecision(Int64, RoundingMode)

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

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

参数:

返回值:

异常:

示例:

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 对象。

返回值:

示例:

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 指定的精度,则根据指定的精度对开方结果进行舍入。

参数:

返回值:

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

异常:

示例:

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 类型。

返回值:

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

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

参数:

返回值:

  • 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

功能:乘方运算,乘方运算符重载,获取当前对象为底数,入参 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

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

参数:

异常:

示例:

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 对象,返回结果值。保留减法运算结果实际精度值。

参数:

返回值:

  • 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

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

注意:

结果为无限小数场景时,默认采用 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