文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载导读std.math.numeric包为仓颉语言提供了超越基础类型表达范围的高精度数值能力其中Decimal用于表示任意精度的有符号十进制数是金融计算、科学运算等对精度敏感的典型场景下的首选类型。本文以官方示例 decimal_basic_prop.md 为主体完整讲解如何初始化Decimal对象、查询其sign、scale、value、precision四大基本属性并结合roundWithPrecision演示精度与舍入规则对属性取值的影响。读完本文你将掌握Decimal对象内部表示原理及属性间换算关系能够独立完成高精度数值的构造、属性分析与精度控制。一、Decimal 与 math.numeric 包Decimal定义于std.math.numeric包中用于表示任意精度的有符号十进制数。根据包概览 math_numeric_package_overview.md 的说明该包为超出基础类型可表达范围提供扩展能力包括支持大整数BigInt支持高精度十进制数Decimal类型提供常见数学运算能力包括高精度运算规则。从结构体定义 math_numeric_package_structs.md 可以看到Decimal是遵循ComparableDecimal Hashable ToString接口的结构体其内部由无标度整数BigInt与标度值共同描述一个十进制数这正是理解其属性体系的关键public struct Decimal : ComparableDecimal Hashable ToString { public init(val: String) public init(val: BigInt, scale: Int32) public init(val: BigInt) public init(val: Int8) public init(val: Int16) public init(val: Int32) public init(val: IntNative) public init(val: Int64) public init(val: UInt8) public init(val: UInt16) public init(val: UInt32) public init(val: UIntNative) public init(val: UInt64) public init(val: Float16) public init(val: Float32) public init(val: Float64) }Decimal支持从字符串、BigInt、各类整型与浮点类型直接构造。需要留意的是通过Float16/Float32/Float64构造时由于部分十进制小数无法被二进制浮点数精确表示构造函数以精确值构建Decimal打印结果可能与传入的浮点数值不完全一致例如Decimal(0.8f16)实际打印为0.7998046875因此对精度敏感的初始化建议优先使用字符串或BigInt方式。二、完整示例初始化并查询 Decimal 基本属性以下代码来自官方示例 decimal_basic_prop.md演示了用字符串解析初始化Decimal、查询四个基本属性以及通过roundWithPrecision控制精度后再次查询属性的完整流程import std.math.* import std.math.numeric.* main() { let decimalProperties Decimal.parse(-123456.7890123456789) println(decimal: ${decimalProperties}) println(decimal sign: ${decimalProperties.sign}) println(decimal scale: ${decimalProperties.scale}) println(decimal value: ${decimalProperties.value}) println(decimal precision: ${decimalProperties.precision}) // 如果希望初始化一个带有指定精度和舍入方式的 Decimal 对象可以采用如下方式 let decimalProperties2 Decimal.parse(-123456.7890123456789).roundWithPrecision(10, roundingMode: HalfEven) println(decimal2: ${decimalProperties2}) println(decimal2 sign: ${decimalProperties2.sign}) println(decimal2 scale: ${decimalProperties2.scale}) println(decimal2 value: ${decimalProperties2.value}) println(decimal2 precision: ${decimalProperties2.precision}) return 0 }运行结果decimal: -123456.7890123456789 decimal sign: -1 decimal scale: 13 decimal value: -1234567890123456789 decimal precision: 19 decimal2: -123456.7890 decimal2 sign: -1 decimal2 scale: 4 decimal2 value: -1234567890 decimal2 precision: 10这个例子虽短却完整展现了Decimal内部无标度整数 标度的表示模型-123456.7890123456789被分解为无标度整数值-1234567890123456789与标度13即小数点后有 13 位数字精度为 19全部有效数字位数。经过roundWithPrecision(10, roundingMode: HalfEven)舍入后小数位数缩减为 4 位无标度整数值变为-1234567890精度收敛为 10。三、四大基本属性逐一解析根据 math_numeric_package_structs.md 中struct Decimal的属性定义四个基本属性含义如下3.1 prop sign符号值public prop sign: Int64获取Decimal实例的符号值返回类型为Int64Decimal值大于 0返回1Decimal值等于 0返回0Decimal值小于 0返回-1。示例中两个对象均为负数因此sign均为-1。该属性与BigInt的 sign 属性 语义一致适合在分支判断中快速识别数值正负。3.2 prop scale标度值public prop scale: Int32获取Decimal的标度值即小数部分的位数。返回类型为Int32。示例一中-123456.7890123456789的小数部分为7890123456789共 13 位故scale 13示例二中经roundWithPrecision(10, HalfEven)舍入后变为-123456.7890小数部分 4 位故scale 4。标度值决定了小数点位置也直接反映数值的精确度等级。Decimal的scaleUnit()方法返回数值为 1、标度值与当前对象相等的Decimal可用作标度的单位参照。3.3 prop value无标度整数值public prop value: BigInt获取Decimal的无标度整数值unscaled value由BigInt承载。它表示去掉小数点后并按标度放大得到的整数部分示例一中无标度值为-1234567890123456789即将-123456.7890123456789小数点右移 13 位放大10^13倍的结果示例二中舍入后的无标度值为-1234567890。实际数值与三者的关系为实际值 value × 10^(-scale)。例如-1234567890123456789 × 10^(-13) -123456.7890123456789。由于value是BigInt可承载任意长度的整数这正是Decimal实现任意精度、避免浮点误差的根本原因。3.4 prop precision精度值public prop precision: Int64获取Decimal的精度值即无标度整数部分十进制有效数字的位数非负。返回类型为Int64。如果精度值为 0表示无精度限制即无限精度。示例一中无标度值-1234567890123456789去掉符号后有 19 位有效数字故precision 19示例二中无标度值-1234567890有 10 位有效数字故precision 10。precision与scale共同描述了Decimal的数值形态有效数字位数越多表示能力越强precision 0表示该对象按无限精度构建字符串解析、BigInt构造等默认路径即为无限精度。四、roundWithPrecision指定精度与舍入规则示例的第二部分展示了如何创建一个带有指定精度和舍入方式的Decimallet decimalProperties2 Decimal.parse(-123456.7890123456789).roundWithPrecision(10, roundingMode: HalfEven)roundWithPrecision的方法签名见 math_numeric_package_structs.mdpublic func roundWithPrecision(precision: Int64, roundingMode!: RoundingMode RoundingMode.HalfEven): Decimal参数说明precision目标精度值即保留的有效数字位数roundingMode!舍入规则默认为RoundingMode.HalfEven即四舍六入五取偶又称银行家舍入。返回值是舍入操作生成的一个新的Decimal对象原对象不会被修改Decimal为值类型结构体。需要注意的是当舍入操作结果的标度值溢出时会抛出OverflowException。原始值-123456.7890123456789有效数字为 19 位按精度 10 舍入后保留 10 位有效数字-1234567890对应十进制值为-123456.7890scale由 13 降为 4。这里HalfEven规则作用于第 11 位有效数字原值第 10、11 位为89向上进位后为-123456.7890。4.1 舍入规则 RoundingMode 全览RoundingMode定义于 math_package_enums.md共 6 种取值覆盖 IEEE 754 浮点标准的 5 种舍入规则并额外提供使用较多的四舍五入规则public enum RoundingMode : EquatableRoundingMode ToString { | Ceiling | Down | Floor | HalfEven | HalfUp | Up }各规则语义与典型示例对 7.5、4.5、-1.1、-4.5、-7.5 舍入到整数如下表十进制数UpDownCeilingFloorHalfUpHalfEven7.58787884.5545454-1.1-2-1-1-2-1-1-4.5-5-4-4-5-5-4-7.5-8-7-7-8-8-8Up向远离零的方向舍入Down向靠近零的方向舍入Ceiling向正无穷方向舍入Floor向负无穷方向舍入HalfUp四舍五入HalfEven四舍六入五取偶银行家舍入默认规则。从表中可见HalfEven与HalfUp的差异集中在恰好为 0.5的情形HalfUp一律进位4.5 → 5HalfEven则舍入到最近的偶数4.5 → 47.5 → 8。在金融统计等场景中HalfEven能避免系统性的累积偏差。该枚举还实现了toString()生成规则名称字符串与判等操作符。五、深入理解属性背后的表示模型5.1 Decimal 的字符串解析规则Decimal.parse(value: String)是官方推荐的高精度初始化方式。根据 math_numeric_package_structs.md 中静态方法的定义其语法格式为Decimal 字符串: SignString? ValueString ExponentString?SignString或-可选ValueStringIntegerPart.(FractionPart)?、.FractionPart或IntegerPartExponentStringExponentIndicator (SignString)? IntegerPart其中ExponentIndicator为e或E可选。因此Decimal.parse支持普通小数如-123456.7890123456789以及科学计数法字符串。解析失败字符串不符合格式时抛出IllegalArgumentException构建值标度溢出时抛出OverflowException。若不希望异常中断程序可改用Decimal.tryParse(value: String): ?Decimal解析失败时返回None。无论哪种方式默认采用精度值为 0无限精度构建。5.2 从 value scale 复原实际数值验证属性间关系最直观的方式是把value与scale组合还原原值。官方配套示例 decimal_basic_arithmetic.md 展示了Decimal(BigInt.parse(987654321), 6)的构造方式——通过无标度整数 标度直接组合出987.654321let decimal2: Decimal Decimal(BigInt.parse(987654321), 6)这印证了Decimal的核心表示模型数值 value(BigInt) × 10^(-scale)。反过来prop value与prop scale也正是从任意Decimal对象还原其内部表示的入口这在序列化、调试与精确比较场景中非常有用。5.3 与 BigInt 属性的一致性Decimal的sign语义与BigInt.sign完全一致正数 1、零 0、负数 -1而Decimal.value本身就是BigInt类型因此关于BigInt的位操作、比较等能力如 BigInt 结构体 中提供的compare、divAndMod、bitLen等同样适用于获取到的无标度值。Decimal自身亦实现了ComparableDecimal、Hashable、ToString可直接用于比较、哈希与字符串打印。六、实战要点与注意事项精度敏感场景优先用字符串初始化Decimal.parse按无限精度构建且完全基于十进制解析避免二进制浮点表示误差从Float系列构造时打印值可能与直觉不一致。precision 0 表示无限精度查询到precision为 0 时说明该对象无精度限制roundWithPrecision可将无限精度对象收敛为指定有效位数。属性是只读的sign、scale、value、precision均为prop属性用于查询而非修改需要改变标度或移动小数点时应使用shiftPoint(n: Int32)、reScale(newScale, roundingMode)等方法返回新对象。舍入会改变属性取值roundWithPrecision(10, HalfEven)后scale从 13 变为 4、precision从 19 变为 10、value从-1234567890123456789变为-1234567890但sign保持-1不变——符号不因舍入而改变。注意异常roundWithPrecision在结果标度溢出时抛出OverflowExceptionDecimal.parse在字符串非法时抛出IllegalArgumentException可使用tryParse获得?Decimal容错结果。配套能力丰富除基本属性外Decimal还提供divWithPrecision、powWithPrecision、sqrtWithPrecision等带精度控制的运算默认均使用HalfEven以及包级函数 abs(Decimal) 等可参见 math_numeric_package_overview.md 的 API 清单。七、小结Decimal通过无标度整数BigInt 标度scale的内部表示实现了任意精度十进制运算四个基本属性各司其职sign标识符号、scale记录小数位数、value承载无标度整数值、precision反映有效数字位数。结合Decimal.parse的字符串解析与roundWithPrecision的精度控制开发者可以在仓颉语言中精确地构造、分析和控制任意精度的十进制数值为金融计算、科学运算等精度敏感应用提供可靠基础。更多运算示例可进一步阅读 decimal_basic_arithmetic.md、decimal_compare_opration.md 等配套文档。赞分享文档知识库教程OpenHarmony【免费下载链接】CangjieCorpus本仓库为仓颉编程语言语料库聚焦 仓颉编程语言 核心知识体系整合官方开发指南、API 文档、典型代码示例及语法规范等多维度资源经结构化处理与专业标注构建为支持 RAG检索增强生成技术 的高质量知识基座适配智能编码助手、学习辅助工具等应用开发需求。 欢迎开发者基于本语料库构建仓颉语言智能应用推动鸿蒙开发生态智能化升级项目地址https://gitcode.com/Cangjie/CangjieCorpus点击查看免费下载相关推荐仓颉 BigInt 基本属性详解sign 与 bitLen 的语义、示例与底层原理仓颉 BigInt 基本属性详解sign 与 bitLen 的语义、示例与底层原理 BigInt 是仓颉 std.math.numeric 包提供的任意精度有文档知识库教程OpenHarmony仓颉语言 Decimal 高精度小数基础数学运算实战指南仓颉语言 Decimal 高精度小数基础数学运算实战指南 本文以 std.math.numeric 包中的 Decimal 类型为主线通过完整的可运行示例讲解文档知识库教程OpenHarmony仓颉语言属性prop完全指南getter/setter 定义、抽象属性与继承覆盖实战仓颉语言属性prop完全指南getter/setter 定义、抽象属性与继承覆盖实战 属性Properties是仓颉语言中用于间接获取和设置值的语言机文档编程语言上一篇OpenMMO水Shader重构海洋与河流无缝融合的关键技巧下一篇oh-my-codex 0.20.5 补丁版发布解析会话权威收紧、Ralplan 预检加固与发布门禁实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考