FormulaError
Error value that may result from formula evaluation and be stored as a cell value.
Consumers of Apiary should typically not create instances of this class themselves. Instances are generally the constants ERROR_VALUE etc., or derived from them using FormulaError.detailed.
Properties
Section titled “Properties”readonly code: number;Positive integer identifying this error type, as returned by the
ERROR.TYPE function.
Example
Section titled “Example”3 for a `#VALUE!` error.detail
Section titled “detail”readonly detail: string | null = null;Detail message, with specific information about the nature and/or cause of the error.
Example
Section titled “Example”"YEARFRAC: basis must be 0, 1, 2, 3, or 4"readonly name: string;Name of the formula error as it appears in a cell.
Example
Section titled “Example”"#VALUE!"origin
Section titled “origin”readonly origin: Reference | null = null;Fully-prefixed reference to the formula cell or defined name in which
the error originally arose during formula evaluation, or null for error
instances that were not produced by formula evaluation (such as the shared
singleton constants ERROR_VALUE etc.
Populated automatically by evaluateAST when a formula produces an error,
but preserved (not overwritten) when a formula yields an existing error
originating in a different cell or defined name. Thus this property always
points back to the cell where the error first arose, not to the last cell
or intermediate cells along the propagation chain.
Accessors
Section titled “Accessors”detailedMessage
Section titled “detailedMessage”Get Signature
Section titled “Get Signature”get detailedMessage(): string;A string representation of this error including its detail message, if any, in parentheses.
Returns
Section titled “Returns”string
detailedMessageWithOrigin
Section titled “detailedMessageWithOrigin”Get Signature
Section titled “Get Signature”get detailedMessageWithOrigin(): string;A string representation of this error including its detail message and/or origin, if any. This is intended for development and debugging rather than for end-user display, and its exact format may change.
Returns
Section titled “Returns”string
Methods
Section titled “Methods”detailed()
Section titled “detailed()”detailed(detail): FormulaError;Get an instance of this error type with the given detail, available as the .detail property.
Intended usage:
- Instead of using ERROR_FOO, use ERROR_FOO.detailed(detailText) to include detail specific to this error
- When displaying an error, expose
.detailif and as appropriate (e.g. only in edit mode?) - The detail text should be short and oriented towards helping authors understand how their model goes wrong, e.g. for ERROR_NAME the detail text might be the function name or defined name that wasn’t recognized.
- Apiary internals should not be exposed (e.g. exception messages, except where known to be end-user-friendly)
Error instances created this way are memoized, so that only one error instance with a given code, name and detail will be created.
Parameters
Section titled “Parameters”detail
Section titled “detail”string
some textual detail about the error, e.g. the unrecognized function name for #NAME?
Returns
Section titled “Returns”FormulaError
equals()
Section titled “equals()”equals(other): boolean;Parameters
Section titled “Parameters”unknown
Returns
Section titled “Returns”boolean
toString()
Section titled “toString()”toString(): string;Returns
Section titled “Returns”string
valueOf()
Section titled “valueOf()”valueOf(): string;Returns
Section titled “Returns”string
withOrigin()
Section titled “withOrigin()”withOrigin(origin): FormulaError;Make a new FormulaError instance like this one but with the given origin.
Parameters
Section titled “Parameters”origin
Section titled “origin”Reference | null
a fully-prefixed reference to the formula cell or defined name in which this error originated, or null to set no origin.
Returns
Section titled “Returns”FormulaError
A new FormulaError instance with the given origin