floating
Luna-Flow/floating 是面向 MoonBit 的任意精度浮点算术库：提供任意精度下具有 IEEE 754 语义的二进制值、IEEE 754 与 General Decimal Arithmetic 十进制数，以及遵循 IEEE 1788 的经认证区间（球）算术。精度、舍入、指数范围、特殊值、状态标志、陷阱和包络在每个 API 中都是显式的值，而不是隐藏的全局状态。本手册记录当前分支；当前发布版本为 0.8.0。
安装
moon add Luna-Flow/floating@0.8.0然后在 moon.pkg 中导入所需的包，例如 "Luna-Flow/floating/bin_float"。本模块需要 MoonBit 工具链 0.10 或更高版本（moonc ≥ 0.10）。它依赖 Luna-Flow/arithmetic（舍入模式、上下文、checked 与 contextual trait）和 Luna-Flow/luna-generic（代数 trait）；当你直接使用 Luna-Flow/arithmetic 的类型时，需要自行添加它。快速上手将带你完成第一个程序。
指南
| 指南 | 阅读目的 |
|---|---|
| 快速上手 | 选择包、安装、初始值、上下文与失败模型 |
| 数值语义 | 共享术语：精确值与舍入结果、舍入函数、ulp 与单位舍入误差、标志、量子、带符号零、NaN、包络 |
| 架构 | 包的分层、数值核心流水线、经认证的初等函数、不变量 |
| 验证 | 检查关卡、已发布的符合性声明及其复现方法 |
| 性能审计 | 优化算术路径的证明与证据 |
| 仓库约定 | 文档规则与评审清单 |
包地图
每个包都有教程（如何使用）、API 参考（可以调用什么）和设计页面（为何如此设计）。四个数值核心还有符合性页面和性能页面。
数值核心
| 包 | 用途 | 页面 |
|---|---|---|
bin_float | 任意精度二进制浮点、IEEE 754 二进制运算以及 binary16/32/64/128 交换格式 | 教程 · API · 设计 · 符合性 · 性能 |
decimal | IEEE 754 任意精度十进制，提供逐运算的标志以及 DPD/BID 交换格式 | 教程 · API · 设计 · 符合性 · 性能 |
decimal_gda | 带粘滞状态与陷阱的 General Decimal Arithmetic | 教程 · API · 设计 · 符合性 · 性能 |
ball_float | 外向舍入的裸区间与带装饰区间（IEEE 1788） | 教程 · API · 设计 · 符合性 · 性能 |
组合与共享词汇
| 包 | 用途 | 页面 |
|---|---|---|
def | Sign、PartialOrder、Floating trait、谓词以及重新导出的 arithmetic 类型 | 教程 · API · 设计 |
bin_float_checked | 在首个错误处停止的二进制流水线 | 教程 · API · 设计 |
decimal_checked | 累积标志的 IEEE 十进制流水线 | 教程 · API · 设计 |
decimal_gda_checked | 串联传递状态并在陷阱处停止的 GDA 流水线 | 教程 · API · 设计 |
ball_float_checked | 在首个错误处停止的区间流水线 | 教程 · API · 设计 |
semantic | 用于跨包比较的精确且与表示无关的投影 | 教程 · API · 设计 |
表达式与语料前端
| 包 | 用途 | 页面 |
|---|---|---|
numeric_expr | 与宿主无关的数值表达式语法及求值 | 教程 · API · 设计 |
frontend/gda_expr | 解析并执行 GDA .decTest 文件 | 教程 · API · 设计 |
frontend/itl_expr | 解析并执行 ITF1788 区间测试行 | 教程 · API · 设计 |
frontend/mpfr_expr | 解析并执行固定版本的 MPFR 见证数据 | 教程 · API · 设计 |
frontend/testfloat_expr | 解析并执行 Berkeley TestFloat 向量 | 教程 · API · 设计 |
符合性测试命令行
| 包 | 用途 | 页面 |
|---|---|---|
cli | 四个符合性测试后端的原生调度器 | 教程 · API · 设计 |
cli/gda_expr_cli | .decTest 运行的文件与输出适配器 | 教程 · API · 设计 |
cli/itl_expr_cli | ITF1788 运行的文件与 JSON 适配器 | 教程 · API · 设计 |
cli/mpfr_expr_cli | MPFR 见证数据运行的命令适配器 | 教程 · API · 设计 |
cli/testfloat_expr_cli | TestFloat 运行的命令适配器 | 教程 · API · 设计 |
基础设施与证据
| 包 | 用途 | 页面 |
|---|---|---|
internal | 共享的精确有理数、大整数、解析、规范化与舍入辅助函数 | 教程 · API · 设计 |
internal/conformance | 源位置、确定性分片、用例处置与汇总 | 教程 · API · 设计 |
internal/runner_cli | 共享的 CLI 选项、文件、诊断信息与 JSON | 教程 · API · 设计 |
consistency | 白盒的跨包定律与 API 审计 | 教程 · API · 设计 |
doc_examples | 由 just docs 运行的可执行文档示例 | 教程 · API · 设计 |
bench | 共享的 Maremark 基准测试基础设施 | 教程 · API · 设计 |
bench/bin_float | 二进制算术与初等函数基准测试 | 教程 · API · 设计 |
bench/decimal | IEEE 十进制基准测试 | 教程 · API · 设计 |
bench/decimal_gda | GDA 十进制基准测试 | 教程 · API · 设计 |
bench/ball_float | 区间算术基准测试 | 教程 · API · 设计 |
应用接口包括各数值核心、def 和 checked 包装器；semantic 和 numeric_expr 是暂定的集成接口。其他包之所以公开接口，是因为仓库工具需要组合它们，其设计页面会给出范围更窄的稳定性承诺。
阅读路径
- 初次接触本库。 阅读快速上手，然后阅读所选包的教程，例如
bin_float教程或decimal教程。阅读时可随时查阅数值语义中的术语。 - 在应用或库中使用。 先通读一遍数值语义，然后以所用包的 API 页面为依据进行开发。在依赖某项标准行为之前，请查看对应的符合性页面；对于流水线，请阅读相应 checked 包装器的教程。
- 参与贡献。 阅读架构、验证和仓库约定，然后阅读你要修改的包的设计页面。修改优化路径时，还需阅读性能审计以及该包的性能页面。
证据快照
- 固定版本的 GDA
official语料通过了 64,986/64,986 条合法的可执行标量行，official0通过了 16,124/16,124 条。其余 141 条#占位行或非标量行属于诊断性排除项。 - 二进制 TestFloat level-1 矩阵在 binary16/32/64/128 上通过了 254,227,872 个向量，涵盖融合乘加、余数、舍入到整数、整数转换和比较谓词，此外还通过了固定版本的 MPFR 平方根与初等函数见证数据。
- 严格的 ITF1788 汇总通过了 4,656/4,656 个选定的区间用例。
- IEEE 十进制检查关卡在四个目标平台上覆盖 decimal32/64/128 的 DPD 与 BID 编码、标志和算术。
这些有限的结果并不意味着支持每一种运算、每一个未来的语料修订版或每一个实数输入。在将某项结果转化为兼容性声明之前，请先阅读该包的符合性页面。
权威依据
pkg.generated.mbti 定义哪些内容是公开的，源码和测试定义行为；如果页面与生成的接口不一致，以接口为准。