class_name BigNumber
extends RefCounted

# ============================================================================
# BigNumber —— 大数红线工具（架构 §4.2）
#
# 口径：double 全程（MVP 终局 ≤1e14 已锁定，技术评估 §3.1 预留的大数系统路径
# 不启用）。本类只做两件事：
#   ① 红线断言：sim 门 #10 与 CI 用；超出 = push_error + 返回 false
#   ② 科学计数辅助：日志/报告用
#
# 纪律：core 层无 Node 依赖；零热路径分配（仅静态函数）。
# 知识缺口：4.7.x 超出训练数据——本文件只用 4.x 稳定 API。
# ============================================================================

## 终局红线（[B§10] 门 #10：终局 ≤1e14）
const RED_LINE := 1e14


## 断言 value 未超红线；超了返回 false 并 push_error（带上下文）。
static func assert_within(value: float, context: String = "") -> bool:
	if value > RED_LINE:
		# 注意：Godot 的 String % 不支持 C 风格 %g（首跑实证：%.3g 直接
		# "String formatting error: unsupported format character"）→ 走 NumberFormat.short
		push_error("BigNumber 超红线：%s > 1e14（上下文：%s）" % [NumberFormat.short(value, 3), context])
		return false
	return true


## 科学计数串（报告/日志用；游戏内显示走 NumberFormat.short）
static func sci(value: float, digits: int = 3) -> String:
	if value == 0.0:
		return "0"
	var sign := "" if value > 0.0 else "-"
	var v := absf(value)
	var exp := int(floor(log(v) / log(10.0)))
	# pow() 返回 Variant（4.x 数学校验函数家族）→ 显式标注；
	# %.*f 为 C 风格动态精度，Godot 不支持 → String.num
	var mant: float = v / pow(10.0, exp)
	return "%s%s e%d" % [sign, String.num(mant, digits), exp]