f8-engine 0.6.1__tar.gz → 0.6.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. {f8_engine-0.6.1 → f8_engine-0.6.3}/Cargo.lock +3 -3
  2. {f8_engine-0.6.1 → f8_engine-0.6.3}/Cargo.toml +1 -1
  3. {f8_engine-0.6.1 → f8_engine-0.6.3}/PKG-INFO +11 -8
  4. {f8_engine-0.6.1 → f8_engine-0.6.3}/README.md +10 -7
  5. f8_engine-0.6.3/crates/f8-core/src/functions/math/basic.rs +231 -0
  6. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/math/mod.rs +4 -1
  7. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/registry.rs +2 -2
  8. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/model/table.rs +14 -1
  9. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/cli.py +1 -1
  10. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/skills/f8-modeling/SKILL.md +1 -1
  11. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/skills/f8-modeling/references/functions.md +7 -4
  12. f8_engine-0.6.1/crates/f8-core/src/functions/math/basic.rs +0 -53
  13. {f8_engine-0.6.1 → f8_engine-0.6.3}/LICENSE +0 -0
  14. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/Cargo.toml +0 -0
  15. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/compiled/error.rs +0 -0
  16. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/compiled/mod.rs +0 -0
  17. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/compiled/model.rs +0 -0
  18. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/emission/error.rs +0 -0
  19. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/emission/format.rs +0 -0
  20. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/emission/mod.rs +0 -0
  21. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/emission/workbook.rs +0 -0
  22. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/error.rs +0 -0
  23. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/eval/context.rs +0 -0
  24. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/eval/error.rs +0 -0
  25. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/eval/expr.rs +0 -0
  26. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/eval/mod.rs +0 -0
  27. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/eval/model.rs +0 -0
  28. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/graph/cycle.rs +0 -0
  29. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/graph/dependency.rs +0 -0
  30. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/graph/error.rs +0 -0
  31. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/graph/mod.rs +0 -0
  32. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/graph/resolve.rs +0 -0
  33. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/ir/cell.rs +0 -0
  34. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/ir/error.rs +0 -0
  35. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/ir/expand.rs +0 -0
  36. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/ir/id.rs +0 -0
  37. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/ir/mod.rs +0 -0
  38. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/ir/symbol.rs +0 -0
  39. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/layout/a1.rs +0 -0
  40. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/layout/error.rs +0 -0
  41. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/layout/mod.rs +0 -0
  42. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/lowering/address.rs +0 -0
  43. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/lowering/error.rs +0 -0
  44. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/lowering/mod.rs +0 -0
  45. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/compiler/mod.rs +0 -0
  46. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/expr/ast.rs +0 -0
  47. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/expr/error.rs +0 -0
  48. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/expr/mod.rs +0 -0
  49. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/expr/parser.rs +0 -0
  50. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/binder.rs +0 -0
  51. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/common.rs +0 -0
  52. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/date/constructors.rs +0 -0
  53. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/date/mod.rs +0 -0
  54. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/date/parts.rs +0 -0
  55. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/date/yearfrac.rs +0 -0
  56. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/error.rs +0 -0
  57. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/financial/annuity.rs +0 -0
  58. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/financial/discounting.rs +0 -0
  59. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/financial/irr.rs +0 -0
  60. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/financial/mod.rs +0 -0
  61. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/information/mod.rs +0 -0
  62. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/logical/boolean.rs +0 -0
  63. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/logical/branching.rs +0 -0
  64. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/logical/error_handling.rs +0 -0
  65. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/logical/mod.rs +0 -0
  66. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/lookup/index.rs +0 -0
  67. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/lookup/mod.rs +0 -0
  68. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/lookup/search.rs +0 -0
  69. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/lookup/xlookup.rs +0 -0
  70. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/lookup/xmatch.rs +0 -0
  71. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/math/aggregation.rs +0 -0
  72. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/math/product.rs +0 -0
  73. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/math/rounding.rs +0 -0
  74. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/mod.rs +0 -0
  75. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/traits.rs +0 -0
  76. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/functions/typecheck.rs +0 -0
  77. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/lib.rs +0 -0
  78. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/model/error.rs +0 -0
  79. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/model/format.rs +0 -0
  80. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/model/id.rs +0 -0
  81. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/model/manifest.rs +0 -0
  82. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/model/mod.rs +0 -0
  83. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/model/theme.rs +0 -0
  84. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/value/date.rs +0 -0
  85. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/value/error.rs +0 -0
  86. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/value/format.rs +0 -0
  87. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-core/src/value/mod.rs +0 -0
  88. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-python/Cargo.toml +0 -0
  89. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-python/src/error.rs +0 -0
  90. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-python/src/lib.rs +0 -0
  91. {f8_engine-0.6.1 → f8_engine-0.6.3}/crates/f8-python/src/model.rs +0 -0
  92. {f8_engine-0.6.1 → f8_engine-0.6.3}/pyproject.toml +0 -0
  93. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/__init__.py +0 -0
  94. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/__main__.py +0 -0
  95. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/_core.pyi +0 -0
  96. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/audit.py +0 -0
  97. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/builder.py +0 -0
  98. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/py.typed +0 -0
  99. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/skills/f8-modeling/references/auditing-and-repair.md +0 -0
  100. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/skills/f8-modeling/references/syntax-and-grid.md +0 -0
  101. {f8_engine-0.6.1 → f8_engine-0.6.3}/python/f8/types.py +0 -0
@@ -58,7 +58,7 @@ checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
58
58
 
59
59
  [[package]]
60
60
  name = "f8-core"
61
- version = "0.6.1"
61
+ version = "0.6.3"
62
62
  dependencies = [
63
63
  "indexmap",
64
64
  "petgraph",
@@ -71,7 +71,7 @@ dependencies = [
71
71
 
72
72
  [[package]]
73
73
  name = "f8-python"
74
- version = "0.6.1"
74
+ version = "0.6.3"
75
75
  dependencies = [
76
76
  "f8-core",
77
77
  "pyo3",
@@ -80,7 +80,7 @@ dependencies = [
80
80
 
81
81
  [[package]]
82
82
  name = "f8-wasm"
83
- version = "0.6.1"
83
+ version = "0.6.3"
84
84
  dependencies = [
85
85
  "f8-core",
86
86
  "rust_xlsxwriter",
@@ -3,7 +3,7 @@ resolver = "3"
3
3
  members = ["crates/f8-core", "crates/f8-python"]
4
4
 
5
5
  [workspace.package]
6
- version = "0.6.1"
6
+ version = "0.6.3"
7
7
  edition = "2024"
8
8
  description = "Financial modeling engine with compiler verification and live Excel formulas"
9
9
  authors = ["Michael (Chencheng) Hu, CFA"]
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: f8-engine
3
- Version: 0.6.1
3
+ Version: 0.6.3
4
4
  Classifier: Development Status :: 4 - Beta
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: Intended Audience :: Financial and Insurance Industry
@@ -47,7 +47,7 @@ AI agents struggle to manipulate raw spreadsheets (`openpyxl`, Office.js, or GUI
47
47
  - Semantic 2D modeling: Author models with readable table, row, and column identifiers; `f8` handles spatial layout and lowers logic into native Excel formulas.
48
48
  - Compiler-enforced rigor: A 6-pass Rust compiler verifies grid completeness (zero unassigned cells or formula overlaps) and enforces a strict DAG via Tarjan cycle detection.
49
49
  - Closed-loop verification: Evaluates formulas in memory so AI agents and test suites (`pytest`, `vitest`) can audit tables, trace dependencies, and verify accounting checks in milliseconds, without opening Excel.
50
- - Verified Excel parity: Matches Excel across all 34 supported functions, combining compile-time type and shape verification with exact Excel domain error propagation and the 1900 leap day bug. The [parity workbook](https://github.com/mhcfa/f8/releases/latest/download/excel_parity_verification.xlsx) ships without cached values, so Excel itself recalculates and grades every case on open (`ParityVerification` sheet: exact match for integers, text, dates, and lookups; 1e-9 relative tolerance for floating-point and iterative functions; runtime error check via `ISERROR`; plus a dedicated `ExcelDivergences` sheet documenting intentional runtime domain and solver divergences from legacy Excel quirks).
50
+ - Verified Excel parity: Matches Excel across all 37 supported functions, combining compile-time type and shape verification with exact Excel domain error propagation and the 1900 leap day bug. The [parity workbook](https://github.com/mhcfa/f8/releases/latest/download/excel_parity_verification.xlsx) ships without cached values, so Excel itself recalculates and grades every case on open (`ParityVerification` sheet: exact match for integers, text, dates, and lookups; 1e-9 relative tolerance for floating-point and iterative functions; runtime error check via `ISERROR`; plus a dedicated `ExcelDivergences` sheet documenting intentional runtime domain and solver divergences from legacy Excel quirks).
51
51
 
52
52
  ## Getting started
53
53
 
@@ -175,15 +175,18 @@ Output:
175
175
 
176
176
  ## Sample deliverables
177
177
 
178
- Inspect compiled deliverables generated from real-world models:
178
+ ### Autonomous Costco equity research
179
179
 
180
- - [costco-valuation.xlsx](https://github.com/mhcfa/f8/releases/latest/download/costco-valuation.xlsx): Compiled 3-statement, DCF, and trading comparables financial model with live Excel formulas.
181
- - [costco-equity-valuation.pdf](https://github.com/mhcfa/f8/releases/latest/download/costco-equity-valuation.pdf): Equity valuation report and presentation rendered from the compiled `f8` model.
182
- - [lbo_model.xlsx](https://github.com/mhcfa/f8/releases/latest/download/lbo_model.xlsx): Multi-sheet leveraged buyout (LBO) model with transaction structuring, debt waterfall, and returns analysis.
180
+ Built in a 4-hour, ~$70 autonomous multi-agent run across 50 SEC and macro sources with zero human intervention:
183
181
 
184
- ### LBO model demo
182
+ - Model repo (TypeScript): [mhcfa/faac](https://github.com/mhcfa/faac) ([`public-equity/costco`](https://github.com/mhcfa/faac/tree/main/public-equity/costco))
183
+ - Write-up: [Running an Autonomous Agent on Costco Equity Research: Why It Called a Short](https://mhcfa.github.io/blog/autonomous-costco-equity-research/)
184
+ - Excel model: [costco-valuation.xlsx](https://github.com/mhcfa/f8/releases/latest/download/costco-valuation.xlsx) (9 sheets, 35 tables, 6,500 cells, 4,228 live Excel formulas across 3-statement, DCF, and trading comps)
185
+ - Valuation deck: [costco-equity-valuation.pdf](https://github.com/mhcfa/f8/releases/latest/download/costco-equity-valuation.pdf) (21 slides bound directly to the compiled `f8` model with no copy-paste)
185
186
 
186
- Complete model repo: https://github.com/mhcfa/f8-demo (this one is written in Python)
187
+ ### LBO model preview
188
+
189
+ - Excel model: [lbo_model.xlsx](https://github.com/mhcfa/f8/releases/latest/download/lbo_model.xlsx) (multi-sheet LBO workbook with transaction structuring, debt waterfall, and returns analysis)
187
190
 
188
191
  ![LBO Executive Dashboard](https://github.com/mhcfa/f8/releases/latest/download/lbo-dashboard.png)
189
192
 
@@ -21,7 +21,7 @@ AI agents struggle to manipulate raw spreadsheets (`openpyxl`, Office.js, or GUI
21
21
  - Semantic 2D modeling: Author models with readable table, row, and column identifiers; `f8` handles spatial layout and lowers logic into native Excel formulas.
22
22
  - Compiler-enforced rigor: A 6-pass Rust compiler verifies grid completeness (zero unassigned cells or formula overlaps) and enforces a strict DAG via Tarjan cycle detection.
23
23
  - Closed-loop verification: Evaluates formulas in memory so AI agents and test suites (`pytest`, `vitest`) can audit tables, trace dependencies, and verify accounting checks in milliseconds, without opening Excel.
24
- - Verified Excel parity: Matches Excel across all 34 supported functions, combining compile-time type and shape verification with exact Excel domain error propagation and the 1900 leap day bug. The [parity workbook](https://github.com/mhcfa/f8/releases/latest/download/excel_parity_verification.xlsx) ships without cached values, so Excel itself recalculates and grades every case on open (`ParityVerification` sheet: exact match for integers, text, dates, and lookups; 1e-9 relative tolerance for floating-point and iterative functions; runtime error check via `ISERROR`; plus a dedicated `ExcelDivergences` sheet documenting intentional runtime domain and solver divergences from legacy Excel quirks).
24
+ - Verified Excel parity: Matches Excel across all 37 supported functions, combining compile-time type and shape verification with exact Excel domain error propagation and the 1900 leap day bug. The [parity workbook](https://github.com/mhcfa/f8/releases/latest/download/excel_parity_verification.xlsx) ships without cached values, so Excel itself recalculates and grades every case on open (`ParityVerification` sheet: exact match for integers, text, dates, and lookups; 1e-9 relative tolerance for floating-point and iterative functions; runtime error check via `ISERROR`; plus a dedicated `ExcelDivergences` sheet documenting intentional runtime domain and solver divergences from legacy Excel quirks).
25
25
 
26
26
  ## Getting started
27
27
 
@@ -149,15 +149,18 @@ Output:
149
149
 
150
150
  ## Sample deliverables
151
151
 
152
- Inspect compiled deliverables generated from real-world models:
152
+ ### Autonomous Costco equity research
153
153
 
154
- - [costco-valuation.xlsx](https://github.com/mhcfa/f8/releases/latest/download/costco-valuation.xlsx): Compiled 3-statement, DCF, and trading comparables financial model with live Excel formulas.
155
- - [costco-equity-valuation.pdf](https://github.com/mhcfa/f8/releases/latest/download/costco-equity-valuation.pdf): Equity valuation report and presentation rendered from the compiled `f8` model.
156
- - [lbo_model.xlsx](https://github.com/mhcfa/f8/releases/latest/download/lbo_model.xlsx): Multi-sheet leveraged buyout (LBO) model with transaction structuring, debt waterfall, and returns analysis.
154
+ Built in a 4-hour, ~$70 autonomous multi-agent run across 50 SEC and macro sources with zero human intervention:
157
155
 
158
- ### LBO model demo
156
+ - Model repo (TypeScript): [mhcfa/faac](https://github.com/mhcfa/faac) ([`public-equity/costco`](https://github.com/mhcfa/faac/tree/main/public-equity/costco))
157
+ - Write-up: [Running an Autonomous Agent on Costco Equity Research: Why It Called a Short](https://mhcfa.github.io/blog/autonomous-costco-equity-research/)
158
+ - Excel model: [costco-valuation.xlsx](https://github.com/mhcfa/f8/releases/latest/download/costco-valuation.xlsx) (9 sheets, 35 tables, 6,500 cells, 4,228 live Excel formulas across 3-statement, DCF, and trading comps)
159
+ - Valuation deck: [costco-equity-valuation.pdf](https://github.com/mhcfa/f8/releases/latest/download/costco-equity-valuation.pdf) (21 slides bound directly to the compiled `f8` model with no copy-paste)
159
160
 
160
- Complete model repo: https://github.com/mhcfa/f8-demo (this one is written in Python)
161
+ ### LBO model preview
162
+
163
+ - Excel model: [lbo_model.xlsx](https://github.com/mhcfa/f8/releases/latest/download/lbo_model.xlsx) (multi-sheet LBO workbook with transaction structuring, debt waterfall, and returns analysis)
161
164
 
162
165
  ![LBO Executive Dashboard](https://github.com/mhcfa/f8/releases/latest/download/lbo-dashboard.png)
163
166
 
@@ -0,0 +1,231 @@
1
+ use crate::functions::common::{require_args, scalar_number};
2
+ use crate::functions::error::FunctionError;
3
+ use crate::functions::traits::{
4
+ EvalContext, ExcelFunction, FunctionArg, FunctionCategory, ParamKind, ParamType, ParameterDef,
5
+ VariadicRule,
6
+ };
7
+ use crate::value::{CellValue, ExcelError, MAX_SAFE_INTEGER, ValueType};
8
+
9
+ /// Positional parameter definitions for `ABS`.
10
+ static ABS_PARAMS: &[ParameterDef] = &[ParameterDef::required(
11
+ "number",
12
+ "The real number for which you want the absolute value.",
13
+ ParamKind::Scalar,
14
+ ParamType::Number,
15
+ )];
16
+
17
+ /// Positional parameter definitions for `LN`.
18
+ static LN_PARAMS: &[ParameterDef] = &[ParameterDef::required(
19
+ "number",
20
+ "The positive real number for which you want the natural logarithm.",
21
+ ParamKind::Scalar,
22
+ ParamType::Number,
23
+ )];
24
+
25
+ /// Positional parameter definitions for `EXP`.
26
+ static EXP_PARAMS: &[ParameterDef] = &[ParameterDef::required(
27
+ "number",
28
+ "The exponent applied to the base e.",
29
+ ParamKind::Scalar,
30
+ ParamType::Number,
31
+ )];
32
+
33
+ /// Positional parameter definitions for `MOD`.
34
+ static MOD_PARAMS: &[ParameterDef] = &[
35
+ ParameterDef::required(
36
+ "number",
37
+ "The number for which you want to find the remainder.",
38
+ ParamKind::Scalar,
39
+ ParamType::Number,
40
+ ),
41
+ ParameterDef::required(
42
+ "divisor",
43
+ "The number by which you want to divide number.",
44
+ ParamKind::Scalar,
45
+ ParamType::Number,
46
+ ),
47
+ ];
48
+
49
+ /// `ABS(number)`: Returns the absolute value of a number.
50
+ #[derive(Debug, Default, Clone, Copy)]
51
+ pub struct AbsFunction;
52
+
53
+ impl ExcelFunction for AbsFunction {
54
+ fn name(&self) -> &'static str {
55
+ "ABS"
56
+ }
57
+
58
+ fn category(&self) -> FunctionCategory {
59
+ FunctionCategory::Math
60
+ }
61
+
62
+ fn parameters(&self) -> &'static [ParameterDef] {
63
+ ABS_PARAMS
64
+ }
65
+
66
+ fn return_type(&self) -> Option<ValueType> {
67
+ Some(ValueType::Number)
68
+ }
69
+
70
+ fn variadic_rule(&self) -> VariadicRule {
71
+ VariadicRule::None
72
+ }
73
+
74
+ fn evaluate(
75
+ &self,
76
+ args: &[FunctionArg<'_>],
77
+ _ctx: &dyn EvalContext,
78
+ ) -> Result<CellValue, FunctionError> {
79
+ let [num_arg] = require_args(self, args)?;
80
+ match scalar_number(num_arg) {
81
+ Ok(n) => Ok(CellValue::number(n.abs())),
82
+ Err(err) => Ok(CellValue::Error(err)),
83
+ }
84
+ }
85
+ }
86
+
87
+ /// `LN(number)`: Returns the natural logarithm of a positive real number.
88
+ #[derive(Debug, Default, Clone, Copy)]
89
+ pub struct LnFunction;
90
+
91
+ impl ExcelFunction for LnFunction {
92
+ fn name(&self) -> &'static str {
93
+ "LN"
94
+ }
95
+
96
+ fn category(&self) -> FunctionCategory {
97
+ FunctionCategory::Math
98
+ }
99
+
100
+ fn parameters(&self) -> &'static [ParameterDef] {
101
+ LN_PARAMS
102
+ }
103
+
104
+ fn return_type(&self) -> Option<ValueType> {
105
+ Some(ValueType::Number)
106
+ }
107
+
108
+ fn variadic_rule(&self) -> VariadicRule {
109
+ VariadicRule::None
110
+ }
111
+
112
+ fn evaluate(
113
+ &self,
114
+ args: &[FunctionArg<'_>],
115
+ _ctx: &dyn EvalContext,
116
+ ) -> Result<CellValue, FunctionError> {
117
+ let [num_arg] = require_args(self, args)?;
118
+ let n = match scalar_number(num_arg) {
119
+ Ok(n) => n,
120
+ Err(err) => return Ok(CellValue::Error(err)),
121
+ };
122
+ if n <= 0.0 {
123
+ return Ok(CellValue::Error(ExcelError::Num));
124
+ }
125
+ Ok(CellValue::number(n.ln()))
126
+ }
127
+ }
128
+
129
+ /// `EXP(number)`: Returns `e` raised to the power of a number.
130
+ #[derive(Debug, Default, Clone, Copy)]
131
+ pub struct ExpFunction;
132
+
133
+ impl ExcelFunction for ExpFunction {
134
+ fn name(&self) -> &'static str {
135
+ "EXP"
136
+ }
137
+
138
+ fn category(&self) -> FunctionCategory {
139
+ FunctionCategory::Math
140
+ }
141
+
142
+ fn parameters(&self) -> &'static [ParameterDef] {
143
+ EXP_PARAMS
144
+ }
145
+
146
+ fn return_type(&self) -> Option<ValueType> {
147
+ Some(ValueType::Number)
148
+ }
149
+
150
+ fn variadic_rule(&self) -> VariadicRule {
151
+ VariadicRule::None
152
+ }
153
+
154
+ fn evaluate(
155
+ &self,
156
+ args: &[FunctionArg<'_>],
157
+ _ctx: &dyn EvalContext,
158
+ ) -> Result<CellValue, FunctionError> {
159
+ let [num_arg] = require_args(self, args)?;
160
+ match scalar_number(num_arg) {
161
+ Ok(n) => Ok(CellValue::number(n.exp())),
162
+ Err(err) => Ok(CellValue::Error(err)),
163
+ }
164
+ }
165
+ }
166
+
167
+ /// `MOD(number, divisor)`: Returns Excel's IEEE-754 floored remainder
168
+ /// `number - divisor * floor(number / divisor)` (matching the sign of `divisor` on exact/dyadic
169
+ /// values, with standard IEEE-754 rounding behavior on non-dyadic decimals).
170
+ #[derive(Debug, Default, Clone, Copy)]
171
+ pub struct ModFunction;
172
+
173
+ impl ExcelFunction for ModFunction {
174
+ fn name(&self) -> &'static str {
175
+ "MOD"
176
+ }
177
+
178
+ fn category(&self) -> FunctionCategory {
179
+ FunctionCategory::Math
180
+ }
181
+
182
+ fn parameters(&self) -> &'static [ParameterDef] {
183
+ MOD_PARAMS
184
+ }
185
+
186
+ fn return_type(&self) -> Option<ValueType> {
187
+ Some(ValueType::Number)
188
+ }
189
+
190
+ fn variadic_rule(&self) -> VariadicRule {
191
+ VariadicRule::None
192
+ }
193
+
194
+ fn evaluate(
195
+ &self,
196
+ args: &[FunctionArg<'_>],
197
+ _ctx: &dyn EvalContext,
198
+ ) -> Result<CellValue, FunctionError> {
199
+ let [num_arg, div_arg] = require_args(self, args)?;
200
+ let num = match scalar_number(num_arg) {
201
+ Ok(n) => n,
202
+ Err(err) => return Ok(CellValue::Error(err)),
203
+ };
204
+ let div = match scalar_number(div_arg) {
205
+ Ok(d) => d,
206
+ Err(err) => return Ok(CellValue::Error(err)),
207
+ };
208
+ if div == 0.0 {
209
+ return Ok(CellValue::Error(ExcelError::Div0));
210
+ }
211
+ let quotient = num / div;
212
+ if !quotient.is_finite() || quotient.abs() > MAX_SAFE_INTEGER {
213
+ return Ok(CellValue::Error(ExcelError::Num));
214
+ }
215
+ let q_floor =
216
+ if quotient == 0.0 && num != 0.0 && num.is_sign_negative() != div.is_sign_negative() {
217
+ -1.0
218
+ } else {
219
+ quotient.floor()
220
+ };
221
+ let product = div * q_floor;
222
+ let remainder = if product.is_finite() {
223
+ num - product
224
+ } else if q_floor < 0.0 {
225
+ (num - div * (q_floor + 1.0)) + div
226
+ } else {
227
+ num - div * (q_floor - 1.0)
228
+ };
229
+ Ok(CellValue::number(remainder))
230
+ }
231
+ }
@@ -8,7 +8,7 @@ use std::sync::Arc;
8
8
  pub use aggregation::{
9
9
  AverageFunction, CountFunction, MaxFunction, MedianFunction, MinFunction, SumFunction,
10
10
  };
11
- pub use basic::AbsFunction;
11
+ pub use basic::{AbsFunction, ExpFunction, LnFunction, ModFunction};
12
12
  pub use product::SumproductFunction;
13
13
  pub use rounding::{RoundFunction, RounddownFunction, RoundupFunction};
14
14
 
@@ -17,6 +17,9 @@ use crate::functions::registry::FunctionRegistry;
17
17
  /// Registers all standard mathematical and aggregation functions into the registry.
18
18
  pub fn register(registry: &mut FunctionRegistry) {
19
19
  registry.register(Arc::new(AbsFunction));
20
+ registry.register(Arc::new(LnFunction));
21
+ registry.register(Arc::new(ExpFunction));
22
+ registry.register(Arc::new(ModFunction));
20
23
  registry.register(Arc::new(SumFunction));
21
24
  registry.register(Arc::new(AverageFunction));
22
25
  registry.register(Arc::new(CountFunction));
@@ -33,13 +33,13 @@ impl FunctionRegistry {
33
33
  }
34
34
  }
35
35
 
36
- /// Returns a shared reference to the standard function registry populated with the 34 built-in Excel functions.
36
+ /// Returns a shared reference to the standard function registry populated with the 37 built-in Excel functions.
37
37
  #[must_use]
38
38
  pub fn standard_ref() -> &'static Self {
39
39
  &STANDARD_REGISTRY
40
40
  }
41
41
 
42
- /// Constructs a standard function registry populated with the 34 built-in Excel functions.
42
+ /// Constructs a standard function registry populated with the 37 built-in Excel functions.
43
43
  #[must_use]
44
44
  pub fn standard() -> Self {
45
45
  STANDARD_REGISTRY.clone()
@@ -443,11 +443,24 @@ impl Serialize for ValueLiteral {
443
443
  }
444
444
  }
445
445
 
446
+ fn deserialize_optional_value_literal<'de, D>(
447
+ deserializer: D,
448
+ ) -> Result<Option<ValueLiteral>, D::Error>
449
+ where
450
+ D: serde::Deserializer<'de>,
451
+ {
452
+ ValueLiteral::deserialize(deserializer).map(Some)
453
+ }
454
+
446
455
  /// Detailed cell override containing optional value, formula expression, formatting, note, or provenance.
447
456
  #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, Default)]
448
457
  #[serde(deny_unknown_fields)]
449
458
  pub struct DetailedCellInput {
450
- #[serde(default, skip_serializing_if = "Option::is_none")]
459
+ #[serde(
460
+ default,
461
+ deserialize_with = "deserialize_optional_value_literal",
462
+ skip_serializing_if = "Option::is_none"
463
+ )]
451
464
  pub value: Option<ValueLiteral>,
452
465
  #[serde(default, skip_serializing_if = "Option::is_none")]
453
466
  pub expr: Option<String>,
@@ -23,7 +23,7 @@ GUIDE_TOPICS: dict[str, tuple[str, str]] = {
23
23
  ),
24
24
  "functions": (
25
25
  "references/functions.md",
26
- "34 built-in Excel functions, signatures, omission syntax, errors",
26
+ "37 built-in Excel functions, signatures, omission syntax, errors",
27
27
  ),
28
28
  "audit": (
29
29
  "references/auditing-and-repair.md",
@@ -52,5 +52,5 @@ CLI commands (`f8` or `python -m f8`):
52
52
  ## Reference Index
53
53
 
54
54
  - `references/syntax-and-grid.md`: Container constructors (`Model`, `Sheet`, `Table`, `Cell`), lookup/mutation APIs (`get_sheet`, `get_table`, `set_cell`, `set_cells`), 2D coordinate grammar, 3-tier resolution rules, layout placement, formatting presets, and themes.
55
- - `references/functions.md`: 34 built-in Excel functions, compile-time type/shape validation, signatures, parameter defaults, conditional aggregation and debt amortization composition patterns, lookup modes, `YEARFRAC` day-count conventions, and domain error rules.
55
+ - `references/functions.md`: 37 built-in Excel functions, compile-time type/shape validation, signatures, parameter defaults, conditional aggregation and debt amortization composition patterns, lookup modes, `YEARFRAC` day-count conventions, and domain error rules.
56
56
  - `references/auditing-and-repair.md`: `CompiledModel` and `TableAuditor` APIs, `MarkdownTable` and dictionary/DataFrame exports, `TypedDict` inspection schemas, and `F8Error` exception attributes.
@@ -1,6 +1,6 @@
1
1
  # Function Reference
2
2
 
3
- Signatures, parameter defaults, compile-time type/shape rules, argument omission (`_`), conditional aggregation and debt amortization patterns, and domain error modes for the 34 built-in Excel functions in `f8`.
3
+ Signatures, parameter defaults, compile-time type/shape rules, argument omission (`_`), conditional aggregation and debt amortization patterns, and domain error modes for the 37 built-in Excel functions in `f8`.
4
4
 
5
5
  ---
6
6
 
@@ -18,19 +18,22 @@ Signatures, parameter defaults, compile-time type/shape rules, argument omission
18
18
  - Intermediate `_` slots bind to their declared default value (or `FunctionArg::Omitted` for `XLOOKUP`'s lazy `if_not_found`, returning `#N/A` on miss); absent trailing optional arguments are not synthetically padded.
19
19
  - In lowered Excel formulas, intermediate `_` emits an empty positional argument (`=PMT(C5,C6,C7,,1)`, `=XLOOKUP(..., ..., ..., , , -1)`).
20
20
  - Runtime Excel error values (returned as cell values and propagated through dependent formulas):
21
- - `#DIV/0!`: `x / 0`, `0 ^ -k`, `AVERAGE` on an all-empty slice, or `r = -1.0` in `NPV`.
21
+ - `#DIV/0!`: `x / 0`, `0 ^ -k`, `MOD(number, 0)`, `AVERAGE` on an all-empty slice, or `r = -1.0` in `NPV`.
22
22
  - `#VALUE!`: Out-of-bounds `index_num < 1` or `> N` in `CHOOSE`, zero `Boolean` values across sparse `AND`/`OR` range slices, unsupported `match_mode` (outside `{0, -1, 1}`, including wildcard `2`) or `search_mode` (outside `{1, -1, 2, -2}`) in `XLOOKUP`/`XMATCH`, or `Empty` / unsorted `lookup_array` under binary search (`search_mode = 2` or `-2`; `Error` cells inside binary-search `lookup_array`s bubble their `ExcelError`).
23
23
  - `#REF!`: Out-of-bounds `row_num` or `col_num` (`< 1` or exceeding slice dimensions) in `INDEX`.
24
- - `#NUM!`: Negative base with fractional exponent (`(-2) ^ 0.5`), `0 ^ 0`, `NaN`/`Inf` overflow, non-integer numeric arguments at discrete integer parameters (`ROUND`/`ROUNDUP`/`ROUNDDOWN` `num_digits`, `CHOOSE` `index_num`, `INDEX` `row_num`/`col_num`, `XLOOKUP`/`XMATCH` `match_mode`/`search_mode`, `DATE` `year`/`month`/`day`, `EDATE`/`EOMONTH` `months`, `YEARFRAC` `basis`, `PMT` `type`), `DATE(year, month, day)` outside `1900..=9999` / `1..=12` / `1..=days_in_month` (preserving `1900-02-29` -> `60.0` while rejecting 2-digit years and rollovers), input date serials outside `1.0..=2958465.0` (including `0` = `1900-01-00`) across `YEAR`/`MONTH`/`DAY`/`EDATE`/`EOMONTH`/`YEARFRAC` and `XNPV`/`XIRR` `dates`, `PMT` `type` outside `{0, 1}`, `YEARFRAC` `basis` outside `0..=4`, `MEDIAN` on an all-empty slice, `IRR`/`XIRR` with `guess <= -1.0`, `< 2` cash flows, missing sign alternation, or non-convergence, `XNPV` with `rate <= 0.0`, dates preceding the initial date (`trunc(d_i) < trunc(d_1)`) in `XNPV`/`XIRR`, `rate <= -1.0` or `nper = 0` in `PMT`, or `EDATE`/`EOMONTH` stepping a valid `start_date` outside `1900..=9999`.
24
+ - `#NUM!`: Negative base with fractional exponent (`(-2) ^ 0.5`), `0 ^ 0`, `LN(number <= 0)`, `EXP` overflow (`> ~709.78`), `MOD` with `|number / divisor| > 2^53 - 1` or non-finite quotient, `NaN`/`Inf` overflow, non-integer numeric arguments at discrete integer parameters (`ROUND`/`ROUNDUP`/`ROUNDDOWN` `num_digits`, `CHOOSE` `index_num`, `INDEX` `row_num`/`col_num`, `XLOOKUP`/`XMATCH` `match_mode`/`search_mode`, `DATE` `year`/`month`/`day`, `EDATE`/`EOMONTH` `months`, `YEARFRAC` `basis`, `PMT` `type`), `DATE(year, month, day)` outside `1900..=9999` / `1..=12` / `1..=days_in_month` (preserving `1900-02-29` -> `60.0` while rejecting 2-digit years and rollovers), input date serials outside `1.0..=2958465.0` (including `0` = `1900-01-00`) across `YEAR`/`MONTH`/`DAY`/`EDATE`/`EOMONTH`/`YEARFRAC` and `XNPV`/`XIRR` `dates`, `PMT` `type` outside `{0, 1}`, `YEARFRAC` `basis` outside `0..=4`, `MEDIAN` on an all-empty slice, `IRR`/`XIRR` with `guess <= -1.0`, `< 2` cash flows, missing sign alternation, or non-convergence, `XNPV` with `rate <= 0.0`, dates preceding the initial date (`trunc(d_i) < trunc(d_1)`) in `XNPV`/`XIRR`, `rate <= -1.0` or `nper = 0` in `PMT`, or `EDATE`/`EOMONTH` stepping a valid `start_date` outside `1900..=9999`.
25
25
  - `#N/A`: `NA()` or unmatched lookup in `XLOOKUP` (without `if_not_found`) or `XMATCH`.
26
26
 
27
27
  ---
28
28
 
29
- ## 2. Math and Aggregation Functions (11)
29
+ ## 2. Math and Aggregation Functions (14)
30
30
 
31
31
  | Function | Signature | Semantics |
32
32
  | :----------- | :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
33
33
  | `ABS` | `ABS(number)` | Absolute value of a `Number` scalar (`Text`, `Boolean`, and `Empty` raise `F8Error`). |
34
+ | `LN` | `LN(number)` | Natural logarithm of a positive `Number` scalar (`Text`, `Boolean`, and `Empty` raise `F8Error`; `number <= 0` returns `#NUM!`). |
35
+ | `EXP` | `EXP(number)` | Exponential `e ^ number` of a `Number` scalar (`Text`, `Boolean`, and `Empty` raise `F8Error`; overflow above ~`709.78` returns `#NUM!`; large negative inputs underflow to `0.0`). |
36
+ | `MOD` | `MOD(number, divisor)` | Floored remainder `number - divisor * floor(number / divisor)` of `Number` scalars matching Excel's divisor-sign rule (`Text`, `Boolean`, and `Empty` raise `F8Error`; `divisor = 0` returns `#DIV/0!`; `abs(number / divisor) > 2^53 - 1` or non-finite quotient returns `#NUM!`). |
34
37
  | `SUM` | `SUM(number1, [number2], ...)` | Sums `Number` scalars, `1x1` `measure` references, and `measure` range slices (`descriptor` columns, `Text`, `Boolean`, and scalar/`1x1` `Empty` raise `F8Error`; sparse `Empty` cells in `start..end` slices contribute `0.0`; float overflow returns `#NUM!`). |
35
38
  | `AVERAGE` | `AVERAGE(number1, [number2], ...)` | Arithmetic mean across `Number` scalars, `1x1` `measure` references, and `measure` range slices (`descriptor` columns, `Text`, `Boolean`, and scalar/`1x1` `Empty` raise `F8Error`; sparse `Empty` cells in `start..end` slices are skipped; returns `#DIV/0!` on all-empty slices). |
36
39
  | `COUNT` | `COUNT(value1, [value2], ...)` | Counts `Number` cells across `Table[...]` `measure` references (`descriptor` columns, `Text`, `Boolean`, and `1x1` `Empty` raise `F8Error`; ignores sparse `Empty` cells in `start..end` slices and runtime `Error` cells). |
@@ -1,53 +0,0 @@
1
- use crate::functions::common::{require_args, scalar_number};
2
- use crate::functions::error::FunctionError;
3
- use crate::functions::traits::{
4
- EvalContext, ExcelFunction, FunctionArg, FunctionCategory, ParamKind, ParamType, ParameterDef,
5
- VariadicRule,
6
- };
7
- use crate::value::{CellValue, ValueType};
8
-
9
- /// Positional parameter definitions for `ABS`.
10
- static ABS_PARAMS: &[ParameterDef] = &[ParameterDef::required(
11
- "number",
12
- "The real number for which you want the absolute value.",
13
- ParamKind::Scalar,
14
- ParamType::Number,
15
- )];
16
-
17
- /// `ABS(number)`: Returns the absolute value of a number.
18
- #[derive(Debug, Default, Clone, Copy)]
19
- pub struct AbsFunction;
20
-
21
- impl ExcelFunction for AbsFunction {
22
- fn name(&self) -> &'static str {
23
- "ABS"
24
- }
25
-
26
- fn category(&self) -> FunctionCategory {
27
- FunctionCategory::Math
28
- }
29
-
30
- fn parameters(&self) -> &'static [ParameterDef] {
31
- ABS_PARAMS
32
- }
33
-
34
- fn return_type(&self) -> Option<ValueType> {
35
- Some(ValueType::Number)
36
- }
37
-
38
- fn variadic_rule(&self) -> VariadicRule {
39
- VariadicRule::None
40
- }
41
-
42
- fn evaluate(
43
- &self,
44
- args: &[FunctionArg<'_>],
45
- _ctx: &dyn EvalContext,
46
- ) -> Result<CellValue, FunctionError> {
47
- let [num_arg] = require_args(self, args)?;
48
- match scalar_number(num_arg) {
49
- Ok(n) => Ok(CellValue::number(n.abs())),
50
- Err(err) => Ok(CellValue::Error(err)),
51
- }
52
- }
53
- }
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes