diff --git a/docs/guide/types-of-errors.md b/docs/guide/types-of-errors.md index 8a7ba22c4..216387a3c 100644 --- a/docs/guide/types-of-errors.md +++ b/docs/guide/types-of-errors.md @@ -9,7 +9,7 @@ tags: - "#CYCLE!" - "#ERROR!" - "#LIC!" - - division by zero + - "#SPILL!" --- # Types of errors @@ -37,4 +37,43 @@ according to the language settings. | #VALUE! | Wrong type of argument | It occurs when a formula tries to improperly use different types of data. For example, you will see this error when you will try to add a string to a number. | | #CYCLE! | Circular reference | It occurs when a formula refers to its own cell, both directly and indirectly. | | #ERROR! | An error occurred | It indicates that there is an unknown error in a formula. | -| #LIC! | License key problem | It occurs when the license key is missing or invalid, when it has expired and your [license terms](license-key.md#license-key-notifications) stop it from working after that, or when the function is not included in the [feature package](license-key.md#feature-packages-and-add-ons) your license key grants. | \ No newline at end of file +| #LIC! | License key problem | It occurs when the license key is missing or invalid, when it has expired and your [license terms](license-key.md#license-key-notifications) stop it from working after that, or when the function is not included in the [feature package](license-key.md#feature-packages-and-add-ons) your license key grants. | +| #SPILL! | No space for array result | It occurs when an array formula's result would overwrite one or more non-empty cells, so it has nowhere to spill into. | + +## Error messages and explanations + +An error's `message` property states the specific cause within its type — for +example, distinguishing *why* a formula returned `#NUM!` rather than only that it +did. HyperFormula does not turn that message into a longer, plain-language +explanation, and does not call out to a language model to generate one. An +application built on top of HyperFormula that wants to rephrase an error for its +end users — in natural language, or translated beyond the languages HyperFormula +ships with — should do so at the application layer, using the `type` and +`message` HyperFormula already provides as its input. + +## Finding out where an error came from + +Besides `type` and `message`, a `DetailedCellError` tells you what produced the +error and, when it was a function rejecting one of its own arguments, which +argument. `originFunction` names a function or an operator helper when one of them +rejected a value, and otherwise names what built the error: `reference` for a +reference that cannot be resolved, `removed reference` for one destroyed by +removing rows or columns, `parser` for a formula that could not be parsed, `user +input` for an error value typed into a cell, `literal` for one written into a +formula, or `array literal` for an array literal whose rows differ in length. +`argumentIndex` is zero-based. + +```javascript +const hf = HyperFormula.buildFromArray( + [['=SUM(SQRT(-1))'], ['=DATE(2000, "x", 1)'], ['=SUM(A99999999999:A99999999999)']], + { licenseKey: 'gpl-v3' } +); + +hf.getCellValue({ sheet: 0, row: 0, col: 0 }).originFunction; // 'SQRT', not 'SUM' +hf.getCellValue({ sheet: 0, row: 1, col: 0 }).argumentIndex; // 1, the second argument +hf.getCellValue({ sheet: 0, row: 2, col: 0 }).originFunction; // 'reference' +``` + +The first occurrence wins, so a function that only read an error never replaces +the identity already on it. `address` points at the cell where the error arose, +which is not always the cell you read it from.