// Opt-in iterative calculation (Excel "Enable iterative calculation").
// The default recalc path is untouched: circular cells stay 0 there.
// Semantics here are provisional (source: manual) until the real-Excel iter
// corpus adjudicates fenceposts, iteration order and convergence details.
/// 迭代计算选项(对应 Excel「启用迭代计算」)。默认 100 次 / 最大变化 0.001。
pub(all) struct IterOptions {
/// 最大迭代次数(Excel 默认 100,上限 32767)。
max_iterations : Int
/// 收敛阈值:一轮内所有格的最大绝对变化小于它即停(Excel 默认 0.001)。
max_change : Double
} derive(Show, Debug)
/// 创建迭代选项;缺省即 Excel 默认(100 次、0.001)。
pub fn new_iter_options(
max_iterations~ : Int = 100,
max_change~ : Double = 0.001
) -> IterOptions {
{ max_iterations, max_change }
}
fn value_delta(a : Value, b : Value) -> Double {
match (a, b) {
(Num(x), Num(y)) => (x - y).abs()
_ => if a == b { 0.0 } else { 1.0e308 }
}
}
/// 启用迭代计算重算整个网格:环上格从 0 起按 grid 插入序就地迭代(Gauss-Seidel),
/// 直到最大变化 < `max_change` 或达到 `max_iterations`。
///
/// 环上格 `circular: true` 但值为迭代结果(不再是 0);非环格与 `recalc` 一致。
/// 默认 `recalc` 路径不受影响(迭代关闭是 Excel 默认)。
pub fn recalc_iterative(
grid : Grid,
options : EvalOptions,
iter : IterOptions
) -> RecalcOutput {
let cache = new_parse_cache()
// Base pass gives static cycle membership and DFS-order parse_errors.
let base = recalc_impl(grid, options, Some(cache.entries)).0
let work : Map[String, Value] = Map::new()
for key, cell in grid.cells {
match cell {
Literal(v) => work[key] = v
Formula(_) => work[key] = Value::Num(0.0)
}
}
let max_passes = if iter.max_iterations < 1 { 1 } else { iter.max_iterations }
let mut pass = 0
while pass < max_passes {
let ctx = new_ctx(grid, options, Some(cache.entries))
for key, v in work {
ctx.cache[key] = v
}
let mut max_delta = 0.0
for key, cell in grid.cells {
match cell {
Formula(src) => {
let old = work[key]
let new_v = match parse_formula(ctx, key, src) {
None => Value::Err(XlError::Value)
Some(e) => eval_expr(ctx, e)
}
let d = value_delta(old, new_v)
if d > max_delta {
max_delta = d
}
work[key] = new_v
ctx.cache[key] = new_v
}
Literal(_) => ()
}
}
pass += 1
if max_delta < iter.max_change {
break
}
}
let out : Map[String, EvalOutput] = Map::new()
for key, cell in grid.cells {
match cell {
Formula(_) =>
out[key] = {
value: scalar_output(work[key]),
circular: base.cells[key].circular,
}
Literal(_) => ()
}
}
{ cells: out, parse_errors: base.parse_errors }
}
/// 单公式迭代求值:公式挂到网格中一个确定不存在的键(从 ZZ1 探测)参与整网格迭代。
///
/// 解析失败返回 `Err(ParseError)`;`circular` 表示网格中出现过任何环(与 `eval_formula` 一致)。
pub fn eval_formula_iterative(
formula : String,
grid : Grid,
options : EvalOptions,
iter : IterOptions
) -> Result[EvalOutput, @syntax.ParseError] {
let _ = try @syntax.parse(formula) catch { e => return Err(e) }
let mut key = "ZZ1"
let mut n = 1
while grid.cells.contains(key) {
n += 1
key = "ZZ" + n.to_string()
}
let g2 : Grid = { cells: grid.cells.copy() }
g2.cells[key] = Formula(formula)
let out = recalc_iterative(g2, options, iter)
let any_cycle = {
let mut found = false
for _, o in out.cells {
if o.circular {
found = true
}
}
found
}
match out.cells.get(key) {
Some(o) => Ok({ value: o.value, circular: any_cycle })
None => Ok({ value: Value::Blank, circular: any_cycle })
}
}