Skip to content

Commit 8a53e27

Browse files
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 <noreply@anthropic.com>
1 parent 72205bd commit 8a53e27

2 files changed

Lines changed: 13 additions & 3 deletions

File tree

docs/guide/known-limitations.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,9 +14,7 @@ the full evaluation of expressions and condition statements. The
1414
most prominent example of this behavior is the "IF" function which
1515
returns a cycle error regardless of whether TRUE or FALSE causes
1616
a circular reference.
17-
* There is no data validation against named ranges. For example,
18-
you can't compare the arguments in a formula like this:
19-
=IF(firstRange>secondRange, TRUE, FALSE).
17+
* 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).
2018
* [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.
2119
* There is no relative referencing in named ranges.
2220
* The library doesn't offer (at least not yet) the following features:

docs/guide/named-expressions.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,18 @@ hfInstance.setCellContents({sheet: 0, col: 2, row: 0}, [['=SUM(SalesData)']]);
8787
hfInstance.setCellContents({sheet: 0, col: 2, row: 1}, [['=SUM(SalesData) * TaxRate']]);
8888
```
8989

90+
## Using named ranges in formulas
91+
92+
A named expression that resolves to a range of cells behaves differently depending on where it is used:
93+
94+
- **As a function argument** — it works as expected. `=SUM(myRange)`, `=COUNT(myRange)`, and `=INDEX(myRange, 1, 1)` all operate on the full range.
95+
- **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.
96+
- **As a bare reference**`=myRange` on its own returns a `#VALUE!` error; a range cannot be placed directly into a single cell.
97+
98+
The range is reduced before the operator runs, so `=SUM(myRange + 1)` receives a single value rather than adding 1 to every element.
99+
100+
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.
101+
90102
## Available methods
91103

92104
These are the basic methods that can be used to add and manipulate named

0 commit comments

Comments
 (0)