From 8a53e2717ba6fcd27d93997467b1fd66c194a091 Mon Sep 17 00:00:00 2001 From: marcin-kordas-hoc Date: Fri, 19 Jun 2026 11:40:02 +0000 Subject: [PATCH 1/2] docs(guide): document named ranges in formulas + fix limitations pointer (HF-222) Adds a 'Using named ranges in formulas' section to named-expressions.md (behavior as function arg / operator operand / bare ref, incl. array mode) and replaces the inaccurate top-level named-ranges bullet in known-limitations.md with a neutral pointer. Docs-only. Co-Authored-By: Claude Opus 4.8 --- docs/guide/known-limitations.md | 4 +--- docs/guide/named-expressions.md | 12 ++++++++++++ 2 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/guide/known-limitations.md b/docs/guide/known-limitations.md index 3da1d2eece..e585233729 100644 --- a/docs/guide/known-limitations.md +++ b/docs/guide/known-limitations.md @@ -14,9 +14,7 @@ the full evaluation of expressions and condition statements. The most prominent example of this behavior is the "IF" function which returns a cycle error regardless of whether TRUE or FALSE causes a circular reference. -* There is no data validation against named ranges. For example, -you can't compare the arguments in a formula like this: -=IF(firstRange>secondRange, TRUE, FALSE). +* Named ranges behave differently depending on where they are used in a formula. For details, see [Using named ranges in formulas](named-expressions.md#using-named-ranges-in-formulas). * [Custom functions](custom-functions.md) don't automatically recalculate the size of their [result arrays](custom-functions.md#return-an-array-of-data) when the formula dependencies change. * There is no relative referencing in named ranges. * The library doesn't offer (at least not yet) the following features: diff --git a/docs/guide/named-expressions.md b/docs/guide/named-expressions.md index 939e131482..666c1fcbf3 100644 --- a/docs/guide/named-expressions.md +++ b/docs/guide/named-expressions.md @@ -87,6 +87,18 @@ hfInstance.setCellContents({sheet: 0, col: 2, row: 0}, [['=SUM(SalesData)']]); hfInstance.setCellContents({sheet: 0, col: 2, row: 1}, [['=SUM(SalesData) * TaxRate']]); ``` +## Using named ranges in formulas + +A named expression that resolves to a range of cells behaves differently depending on where it is used: + +- **As a function argument** — it works as expected. `=SUM(myRange)`, `=COUNT(myRange)`, and `=INDEX(myRange, 1, 1)` all operate on the full range. +- **As an operand of an operator** — the range is reduced to a single cell before the operation. In `=myRange + 1`, only the cell of the range that shares the formula's row (for a vertical range) or column (for a horizontal range) is used. If the formula's row or column falls outside the range, or the range is two-dimensional, the result is a `#VALUE!` error. +- **As a bare reference** — `=myRange` on its own returns a `#VALUE!` error; a range cannot be placed directly into a single cell. + +The range is reduced before the operator runs, so `=SUM(myRange + 1)` receives a single value rather than adding 1 to every element. + +When array arithmetic is enabled (`useArrayArithmetic: true`), named ranges still work as function arguments and aggregate correctly, but they do not spill: `=myRange + 1` returns a `#VALUE!` error rather than producing one result per element. + ## Available methods These are the basic methods that can be used to add and manipulate named From 284436779db581459228368560a09bae00c8d52c Mon Sep 17 00:00:00 2001 From: marcin-kordas-hoc Date: Wed, 24 Jun 2026 11:45:55 +0000 Subject: [PATCH 2/2] docs(named-expr): correct SUM(myRange+1) array-mode behavior per review (HF-222) The previous wording stated unconditionally that SUM(myRange+1) receives a single reduced value. The unit tests (PR #15) and the engine confirm it is element-wise in array mode (SUM(2,3,4,5,6)=20). Scope the reduction claim to default mode and document the array-mode element-wise behavior. Co-Authored-By: Claude Opus 4.8 --- docs/guide/named-expressions.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/guide/named-expressions.md b/docs/guide/named-expressions.md index 666c1fcbf3..625b80416d 100644 --- a/docs/guide/named-expressions.md +++ b/docs/guide/named-expressions.md @@ -95,9 +95,12 @@ A named expression that resolves to a range of cells behaves differently dependi - **As an operand of an operator** — the range is reduced to a single cell before the operation. In `=myRange + 1`, only the cell of the range that shares the formula's row (for a vertical range) or column (for a horizontal range) is used. If the formula's row or column falls outside the range, or the range is two-dimensional, the result is a `#VALUE!` error. - **As a bare reference** — `=myRange` on its own returns a `#VALUE!` error; a range cannot be placed directly into a single cell. -The range is reduced before the operator runs, so `=SUM(myRange + 1)` receives a single value rather than adding 1 to every element. +In the default mode the range is reduced before the operator runs, so `=SUM(myRange + 1)` adds 1 to that single reduced value rather than to every element (for a formula in row 1 of a vertical range, the result is `SUM(A1 + 1)`). -When array arithmetic is enabled (`useArrayArithmetic: true`), named ranges still work as function arguments and aggregate correctly, but they do not spill: `=myRange + 1` returns a `#VALUE!` error rather than producing one result per element. +When array arithmetic is enabled (`useArrayArithmetic: true`), named ranges still work as function arguments and aggregate correctly, but as an operand they behave differently from the default mode: + +- A bare `=myRange + 1` does not spill — it returns a `#VALUE!` error rather than producing one result per element. +- Inside an aggregate the operator becomes element-wise. `=SUM(myRange + 1)` adds 1 to every element and then sums, so for `myRange` covering values `1..5` it returns `20` (`SUM(2, 3, 4, 5, 6)`), not the single reduced value of the default mode. ## Available methods