buguoshixc/mooncalc/src/engine does not have a README file

    CachedAst

    type CachedAst

    Cell

    pub(all) enum Cell {
    Literal(
    Value
    )
    Formula(String)
    } derive(Eq, Show,
    Debug
    )
    单元格内容:字面值或公式源码。

    CritToken

    type CritToken

    Criteria

    type Criteria

    Ctx

    type Ctx

    Dec

    type Dec

    DepGraph

    pub(all) struct DepGraph {
    precedents : Map[String, Array[String]]
    dependents : Map[String, Array[String]]
    } derive(Show,
    Debug
    )
    网格依赖图(AST 级提取,区域展开、去重):公式格 → 直接前驱 / 格 → 直接下游。

    EvalOptions

    pub(all) struct EvalOptions {
    now : Double?
    } derive(Show,
    Debug
    )
    求值选项。

    EvalOutput

    pub(all) struct EvalOutput {
    value :
    Value

    circular : Bool
    } derive(Show,
    Debug
    )
    单格/单公式求值结果。

    ExplainOutput

    pub(all) struct ExplainOutput {
    target : String
    value :
    Value

    circular : Bool
    steps : Array[ExplainStep]
    sources : Array[String]
    parse_error : String?
    } derive(Show,
    Debug
    )
    错误解释结果。

    ExplainStep

    pub(all) struct ExplainStep {
    addr : String
    formula : String
    value :
    Value

    is_source : Bool
    precedents : Array[String]
    } derive(Show,
    Debug
    )
    错误传播路径上的一步。

    FmtCond

    type FmtCond

    FmtSection

    type FmtSection

    FmtTok

    type FmtTok

    FnSpec

    type FnSpec

    Grid

    pub(all) struct Grid {
    cells : Map[String, Cell]
    } derive(Show,
    Debug
    )
    单元格网格:引擎的唯一输入数据契约。键为 A1 形式的大写地址(CellAddr::key)。

    IterOptions

    pub(all) struct IterOptions {
    max_iterations : Int
    max_change : Double
    } derive(Show,
    Debug
    )
    迭代计算选项(对应 Excel「启用迭代计算」)。默认 100 次 / 最大变化 0.001。

    ParseCache

    pub struct ParseCache {
    // private fields
    }
    调用方持有的公式 AST 缓存:按公式全文缓存解析结果(含解析失败消息)。

    跨多次 recalc_cached 复用可跳过重复解析(如 playground 击键重算)。 公式文本变化即产生新键,无需手动失效;缓存随不同公式文本数增长, 长期持有的调用方可用 clear 释放。

    ParseCache::clear

    fn ParseCache::clear(self : ParseCache) -> Unit
    清空缓存(释放内存;后续重算会重新解析)。

    RecalcOutput

    pub(all) struct RecalcOutput {
    cells : Map[String, EvalOutput]
    parse_errors : Array[(String, String)]
    }
    全网格重算结果。

    RecalcState

    pub struct RecalcState {
    // private fields
    }
    增量重算状态(调用方持有,单所有者)。由 recalc_init 创建,传给 recalc_update 复用依赖图、AST 缓存与上次求值结果。

    SectionChoice

    type SectionChoice

    compare_values

    Excel 比较排序(= < 等):不跨类型强制转换,类型序 number < text < boolean, 文本大小写不敏感,故 "1" = 1 为 FALSE。返回 -1/0/1;错误值传播。

    date_serial

    fn date_serial(y0 : Int, m0 : Int, d0 : Int) -> Result[Int,
    XlError
    ]
    Excel DATE():年参数 0..1899 先 +1900,再按月溢出归一化(故 DATE(1900,0,1) 落在 1899 → #NUM!)。序列日按 Excel/Lotus 日历计算(幻影日 1900-02-29 = 60, DATE(1900,3,0) = 60、DATE(1900,2,30) = 61)。越界(序列 <0 或 >2958465)返回 #NUM!。

    days_in_month

    fn days_in_month(y : Int, m : Int) -> Int
    proleptic Gregorian 月份天数。注意 1900 在此不是闰年:真实 Excel 的 EOMONTH(60,0) 返回 59,即 1900 年 2 月按 28 天计算(显示层仍保留幻影序列 60)。 非法月份返回 0。

    dependency_graph

    fn dependency_graph(grid : Grid) -> DepGraph?
    提取整网格依赖图;任一区域超过 65536 格时返回 None(调用方降级)。

    eval_at

    求值网格中某个单元格;空白格返回 Blank。循环引用语义与 recalc 一致。

    eval_formula

    fn eval_formula(formula : String, grid : Grid, options : EvalOptions) -> Result[EvalOutput,
    ParseError
    ]
    解析并求值单条公式(不写入网格)。引用会递归求值。

    解析失败返回 Err(ParseError);求值阶段的错误值(如 #DIV/0!)作为 Ok 中的 Value::Err 返回。超过 Excel 公式限制(8192 字符 / 64 层嵌套)按解析失败处理。

    eval_formula_iterative

    fn eval_formula_iterative(formula : String, grid : Grid, options : EvalOptions, iter : IterOptions) -> Result[EvalOutput,
    ParseError
    ]
    单公式迭代求值:公式挂到网格中一个确定不存在的键(从 ZZ1 探测)参与整网格迭代。

    解析失败返回 Err(ParseError);circular 表示网格中出现过任何环(与 eval_formula 一致)。

    explain

    解释单元格的错误来源:返回贡献性错误传播路径(源→目标)与错误源头。

    目标非错误值或落在环上时 steps 为空。上游超过 256 格时降级为纯错误前驱链 (过近似,不做贡献性探针)。

    new_grid

    fn new_grid() -> Grid
    创建一个空的单元格网格。

    new_iter_options

    fn new_iter_options(max_iterations? : Int, max_change? : Double) -> IterOptions
    创建迭代选项;缺省即 Excel 默认(100 次、0.001)。

    new_parse_cache

    fn new_parse_cache() -> ParseCache
    创建一个空的公式 AST 缓存。

    number_to_text

    fn number_to_text(d : Double) -> String
    Excel 隐式数字→文本(&/CONCAT 用的 General 格式):先舍入到 15 位有效数字, 十进制指数在 [-18, 19] 内用定点表示,否则科学计数;科学计数尾数去尾零,定点整数补零。

    recalc

    fn recalc(grid : Grid, options : EvalOptions) -> RecalcOutput
    按依赖关系重算整个网格(DFS + 记忆化 + 环检测)。

    循环引用复刻 Excel 默认(迭代计算关闭):环上单元格结果为 0,元数据 circular: true。

    recalc_cached

    fn recalc_cached(grid : Grid, options : EvalOptions, cache : ParseCache) -> RecalcOutput
    按依赖关系重算整个网格,复用调用方持有的 AST 缓存。语义与 recalc 完全一致。

    循环引用复刻 Excel 默认(迭代计算关闭):环上单元格结果为 0,元数据 circular: true。

    recalc_init

    fn recalc_init(grid : Grid, options : EvalOptions) -> (RecalcState, RecalcOutput)
    全量重算并建立增量状态;输出与 recalc 完全一致。

    recalc_iterative

    fn recalc_iterative(grid : Grid, options : EvalOptions, iter : IterOptions) -> RecalcOutput
    启用迭代计算重算整个网格:环上格从 0 起按 grid 插入序就地迭代(Gauss-Seidel), 直到最大变化 < max_change 或达到 max_iterations。

    环上格 circular: true 但值为迭代结果(不再是 0);非环格与 recalc 一致。 默认 recalc 路径不受影响(迭代关闭是 Excel 默认)。

    recalc_update

    fn recalc_update(state : RecalcState, grid : Grid, changed : Array[String], options : EvalOptions) -> RecalcOutput
    增量重算:只重算 changed 的下游闭包,输出与 recalc(grid, options) 逐字段一致。

    changed 必须列出相对上次调用网格内容发生变化的全部地址(含 Literal↔Formula 切换与删除)。出现循环引用、解析错误或超大区域(>65536 格)时自动回退全量重算。

    round_excel

    fn round_excel(d : Double, digits : Int, mode : Int) -> Double
    Excel 十进制舍入(先归一到 15 位有效数字再舍入,避免二进制浮点尾差)。 digits 为保留小数位(负数舍入到十/百…位);mode:0=ROUND(四舍五入)、 1=ROUNDUP(远离零)、2=ROUNDDOWN(趋向零)。

    scalarize

    标量化:1×1 区域取其唯一单元格,其余值原样返回。

    serial_to_ymd

    fn serial_to_ymd(serial : Double) -> Result[(Int, Int, Int),
    XlError
    ]
    Excel 序列日 → (年, 月, 日)。含 Lotus 幻影日:序列 60 = 1900-02-29,序列 0 = (1900,1,0)。 非有限值或越界(<0 或 >2958465)返回 #NUM!;小数部分被截断。

    text_format

    fn text_format(d : Double, fmt : String) -> Result[String,
    XlError
    ]
    Excel TEXT():按格式码把数字格式化为文本。支持数字段(0/#/?/千分位/百分号/ 科学计数)、日期时间段(含 [h]/[m]/[s] 累计时长)、条件分段(如 [>100])与 正;负;零;文本四节。子集外格式返回 #VALUE!(含 "General" 关键字,zh-CN Excel 拒绝)。完整子集见 docs/semantics.md「TEXT 子集」。

    to_bool

    Excel 布尔强制转换(逻辑参数):布尔原样;数字≠0→TRUE;空白→FALSE; 文本仅接受大小写不敏感的 "TRUE"/"FALSE",其余→#VALUE!;错误传播。

    to_number

    Excel 数值强制转换(算术运算、数值参数):数字原样;空白→0;布尔→1/0; 文本按 Excel 数字文法解析(含千分位/百分号/科学计数,locale 不变);错误传播; 多格区域→#VALUE!。

    to_text

    Excel 文本强制转换(&、文本参数):数字按 General 格式(15 位有效数字); 布尔→"TRUE"/"FALSE";空白→"";错误传播;多格区域→#VALUE!。