Optionalmessage: stringOptionaldetails: ErrorOptionsUse for introspection.
For runtime type checking.
Returns the size of the range this is the rows * columns.
Returns an iterator that allows you to iterate over the individual values within the range.
For more advanced iteration, use IRange.entries or IRange.forEach.
Reduces this range and any number of other ranges in lockstep — the fused, streaming form of
"align, apply an elementwise kernel, fold" (numpy's f(a, b).sum(), with no intermediate
range). Iteration and alignment follow alignValues: positions align by offset,
a position empty on every side is never visited, an absent/filtered member arrives as
null, and a null in others contributes the 1-based position ordinal.
Value policy (what to skip, how to accumulate) belongs to the callback — this is the same contract as reduce, over aligned members.
The parallel range(s); null entries yield the 1-based position ordinal.
The function to execute on each aligned position — values[0] is this
range's member, values[i+1] is others[i]'s.
The initial value of the accumulator.
Optionaloptions: ReduceOptions<U>
IRange.ReduceOptions Applied to this range's read; axis orders the
iteration for all sides. Supply emptyFold when the answer depends on the positions that are
empty on every side — they are never visited, so a fold that needs them must state their
contribution in closed form.
The reduced value.
Iterates this range and any number of other ranges in lockstep, yielding the corresponding
values at each position — values[0] is this range's member, values[i+1] is others[i]'s.
Positions are aligned by OFFSET from each range's start; there is no broadcasting or tiling —
dimension rules stay with the caller. Iteration is sparse: a position empty in EVERY range is
never visited, and a range with no member at a visited position contributes null. Each range
reads through its own declared type, so a filtered member (e.g. text under a number read)
surfaces as null exactly like an empty cell.
A null entry in others contributes the 1-based POSITION ordinal instead — the implied
{1,2,...,n} sequence. The ordinal is positional within this range's shape (empties advance it),
so a sparse member keeps the ordinal its cell occupies.
The parallel ranges; null entries yield the 1-based position ordinal.
Optionaloptions: IRange.IteratorOptions
IRange.IteratorOptions Applied to this range's read; axis orders the
iteration for all sides.
Pairs of [values, coords] with coords relative to this range.
Applies a callback function to elements from this range and another range or a scalar,
using Excel's broadcasting rules. This is the two-operand special case of zip:
a.broadcast(b, f) is a.zip([b], ([x, y]) => f(x, y)).
Broadcasting Rules (the same as zip):
misalignValue is set, in which
case the result is the union shape and every position outside the intersection holds
misalignValue. Here the pad is a RESULT; in zip it is an ARGUMENT.A new range with the broadcasted results.
Iteration is sparse: the positions visited are the union of both operands' stored cells. A
position empty on both sides has one answer, and a callback that reads only its two values
(callbackFn.length === 2) receives that answer computed ONCE and written as runs; a callback
that asks for coords or range is called per position instead.
Selects values from from by dispatching each element of condition to a 0-based index.
For each cell, selectFn receives the corresponding value from condition and returns a 0-based
index into from. If the index is out of bounds, the original value from this is kept.
Broadcasting Rules:
this, condition, and all from ranges.selectFn falls back to this at that position.The candidate ranges or scalars to select from (0-based).
Maps each condition value to a 0-based index into from.
Return -1 (or any out-of-bounds value) to keep the original value from this.
Optionaloptions: ValuesOptions
A new range with selected values overlaid onto this.
mask for the boolean shorthand (single condition, single value range).
Similar to empty, but returns an range with the same size but null values.
Returns a new range identical to the current one.
Applies a transformation function to this IRange, returning the result.
Equivalent to fn(this) — useful for applying named or reusable transforms
inline without breaking a fluent method chain.
Concatenates another range along the specified axis, returning a new range.
other below this. Both ranges must have the same column size, or the
narrower is padded to the wider with padWith.other to the right of this. Both ranges must have the same row size,
or the shorter is padded to the taller with padWith.The range to append.
Optionalaxis: IRange.Axis
The axis to concatenate along. Default is IRange.Axis.Row.
OptionalpadWith: Scalar
Value used to pad the narrower/shorter range. Default is #N/A.
Returns a range of 0x0.
Returns an iterator that allows you to iterate over the individual entries within the range,
yielding pairs of IRange.CellCoords and Scalar.
Optionaloptions: IRange.IteratorOptions
An iterator that yields a IRange.Entry for each value within the range.
Skips empty values by default.
const iterEntries:IterableIterator<IRange.Entry> = array.entries({
axis: IRange.Axis.Row, // Default but Column and 'fastest' are also available
includeEmpty: false // Default but true is also available but should be avoided if sparse.
});
let iter: IteratorResult<IRange.Entry> = iterEntries.next();
while (!iter.done) {
const entry = iter.value;
const value = entry.value;
const coords: Readonly<IRange.CellCoords> = entry.coords;
iter = iterEntries.next();
// ...interesting logic here. Perhaps a sparseBuilder.
}
Return true if two errors are same.
any object to compare.
if two errors are the same type.
Iterates the range's error members — every stored FormulaError — in row-major order
by default. Row-major is the identity order: errors().next() yields the error that
propagates under the engine's reject policy (#N/A stays #N/A).
Optionaloptions: Pick<IRange.IteratorOptions, "axis" | "bounds" | "reverse">
Narrowed iterator options — only axis, bounds, and reverse.
The narrowing is deliberate: type/onError/coerce are meaningless-to-contradictory
on an error iterator. Like hasError, the scan reads RAW stored members,
ignoring the range's read type and coercion policy.
hasError for existence-only checks.
Tests whether all elements in the range pass the test implemented by the provided function.
The function to test each element.
Optionaloptions: IRange.IteratorOptions
true if all elements pass the test, otherwise false.
Creates a new range with elements that pass the test implemented by the provided function.
The function to test each element.
Optionaloptions: IRange.IteratorOptions | TraversalAxis
A new range containing only the elements that pass the test.
The first error member in row-major order, or null when there is none — the identity that
propagates when a body refuses a range with an error inside it:
if (range.hasError()) return range.firstError();.
Errors INSIDE a range are the body's to judge: the engine hands a valid range over whole and never looks inside, so a function whose answer depends on every member says so with this line, placed before its own validation where Excel's error outranks it. A reshaper or a lookup, whose members pass through or are never read, needs no line at all.
Linearizes the range into a single column by flattened ordinal — the member at ordinal i
lands at row i, column 0.
Optionaloptions: IRange.IteratorOptions
options.axis is the TRAVERSAL order feeding the ordinal, not the orientation of the result:
the result is always Nx1, and a row is flatten().transpose(). The default is row-major,
which is the order Excel pairs two range operands in.
options.type carries a read type onto the result, so a member the type filters out becomes
a HOLE at its ordinal rather than compacting the column. That is what lets two operands be
paired position by position — see alignValues.
options.includeEmpty has no meaning here and is ignored: a range is inherently sparse, so
an empty position is simply absent. Sparsity is preserved and nothing is materialized.
Equivalent to reshape(rows * columns, 1), which is where the ordinal rule is stated.
getValuesFlat for the same linearization as a JS array.
Iterates over the cells within the range, applying the provided callback function to each cell.
This method is a more scalable alternative to getValues or getCells for large or sparse ranges,
as it:
A function that will be called for each non-empty cell in the range. The callback receives:
value: The Scalar at the current cell.coords: A IRange.CellCoords.{ break: T } to stop the iteration early.Optionaloptions: IRange.IteratorOptions
The value returned by the callback function if it explicitly returned to stop the iteration early; otherwise, void.
Returns the number of columns of the range.
Returns the number of rows of the range.
Returns the shape of the range in rows and columns.
Returns the statistics for the range.
Optionaloptions: IRange.IteratorOptionsIndicates if the range has a type. Returns undefined when no type was set —
consumers compare against an (optionally undefined) requested type, so null
must NOT be substituted here.
Returns a scalar value at a specific row and column index.
The row index of the value to retrieve.
The column index of the value to retrieve.
Optionaloptions: ValueOptions
Returns the values as a materialized 2D array.
Optionaloptions: IRange.GetValuesOptions
Returns true if any stored member of the range is a FormulaError.
Reads RAW stored members only — the range's read type and coercion policy are ignored.
A toType(Number) range with a text member does NOT "have an error"; a #VALUE!
synthesized by errorOnInvalidCoercion doesn't count.
The result is EXACT, never conservative: false guarantees there are no error members.
(Internal fast paths may be conservative; the public result may not be.)
Equivalent by definition to
getStats().getTypedCounts([ScalarType.Error])[ScalarType.Error] > 0 — the two
definitions of "error member" must never drift.
Deliberately takes no options: partial regions compose —
range.slice(coords).hasError() (slice is a zero-copy view).
errors to iterate the error members themselves.
Returns the position of the first member equal to value, or -1 when there is none.
The value to find.
Optionaloptions: IndexOfOptions
Equality is the = operator's: text is case-insensitive, and no value matches one of another
type (1 does not match "1", nor TRUE 1). Empty members, errors and rich data are never
a match. The position is the offset along a row or column vector, and the row-major offset
within a larger range. This is MATCH(value, range, 0) less one, and a range read by many
lookups is indexed once rather than scanned per call.
Returns true if the range is empty.
Applies a transformation function to each value, returning a new IRange.
A function applied to each non-empty cell
Optionaloptions: MapOptions
The result carries NO read type, even when the source had one — the values are the callback's
outputs and map cannot know what type they are. Use IRange.toType on the result if
you do know. (options.type still applies to the values handed TO the callback.)
Returns a new range where each cell is replaced with the value from ifTrues
where the corresponding conditions value is strictly true.
The mask rules are:
true then the value from ifTrues is used.ifTrues then options.misalignValue is used (default #N/A).Similar to pandas DataFrame.mask(cond, other).
broadcast for element-wise transformation with a callback
Applies a function against an accumulator and each element of the range (from left to right) to reduce it to a single value.
The function to execute on each element.
The initial value of the accumulator.
Optionaloptions: IRange.IteratorOptions
The reduced value.
Iteration is sparse — empty cells are not visited. A fold whose answer DEPENDS on the empty
cells wants alignReduce's emptyFold, which states their contribution in closed form;
pass no others for the single-range case.
Repeat the values in the range to a new width and height by repeating individual values.
Number of times to repeat each value vertically.
Number of times to repeat each value horizontally.
Note: Arguments follow matrix convention (rows, columns), not geometric order (columns, rows).
[1, 2].repeat(1, 3) → [1, 1, 1, 2, 2, 2] (expand horizontally)
[1, 2].repeat(2, 1) → [[1, 2], [1, 2]] (expand vertically)
To repeat the entire range as a block, see tile.
Returns a new range with values from another range overlaid at the given offset. Where they overlap, other wins. If other extends beyond this, the range expands.
The other range or a 2D array.
Optionaloffset: IRange.CellCoords
The starting coordinates for the replacement. Default: { rowIndex: 0, colIndex: 0 }
Reflows the range's members into a new shape by flattened row-major ordinal — numpy's
reshape: the member at flattened position i lands at row ⌊i / columns⌋, column
i % columns. Empty positions keep their ordinal (they reflow as gaps), so sparse ranges
stay sparse.
Contrast resize, which trims/pads in place WITHOUT reflowing, and repeat / tile, which duplicate values.
The new number of rows.
The new number of columns.
Returns a new range either trimmed or expanded to the new rows and columns.
The new number of rows of the range.
The new number of columns of the range.
OptionalfillValue: Scalar
If provided then when expanding the new cells will be filled with this value. DefaultValue null
Similar to choose, but matches by value equality rather than by index.
For each cell, searches match for the first element equal to the expression value and returns
the corresponding element from from. If no match is found, defaultValue is used (or the
original value from this if no default is provided).
Values to match against the expression range.
Values to return for each corresponding match.
OptionaldefaultValue: TS | IRange<TS>
Fallback value when no match is found.
OptionalselectFn: (Optional custom equality function. Defaults to strict equality (===).
Optionaloptions: ValuesOptions
choose for index-based dispatch.
Tests whether at least one element in the range passes the test implemented by the provided function.
The function to test each element.
Optionaloptions: IRange.IteratorOptions
true if at least one element passes the test, otherwise false.
Creates a SparseBuilder for efficiently updating sparsely populated values in a streaming low memory way.
Optionaloptions: TraversalAxis | IRange.SparseBuilderOptions
Ordering: By default updates must be added in either row-major or column-major order, as specified
by the axis parameter, with major/minor coordinates increasing monotonically. Unless
allowUnorderedWrites is set to true out of order updates will result in an error.
Performance: Setting axis to IRange.Axis.Column is generally faster as it aligns with the internal data representation.
Performance: Setting allowUnorderedWrites adds a nominal performance overhead for all updates and will do a full apply when an
out of order update is detected.
The default IRange.Axis.Row is provided for compatibility with common spreadsheet APIs.
Returns a new range by selecting values at the given indices along the specified axis.
The output size along the selected axis equals indices.length — no resizing is applied.
Indices refer to positions within this range (0-based, relative to origin). The same index may appear multiple times to repeat rows or columns.
The positions to select, in the desired output order.
Optionalaxis: IRange.Axis
The axis to select along. Default is IRange.Axis.Row (select rows). Pass IRange.Axis.Column to select columns.
Tile the range to a new width and height by repeating blocks of values.
Number of times to tile the range vertically.
Number of times to tile the range horizontally.
Note: Arguments follow matrix convention (rows, columns), not geometric order (columns, rows).
[1, 2, 3].tile(1, 3) → [[1, 2, 3, 1, 2, 3, 1, 2, 3]] (tile horizontally 3×)
[1, 2, 3].tile(3, 1) → [[1, 2, 3], [1, 2, 3], [1, 2, 3]] (tile vertically 3×)
To repeat individual values instead of blocks, see repeat.
Returns the scalar value of the range if it is a 1×1 range, otherwise throws an error.
Change the type of default range coercion for the values in the range.
The new scalar type or value options.
Returns the range transposed.
Returns the indices of the distinct rows (or columns) in this range, keeping the FIRST
occurrence of each. Analogous to np.unique(arr, axis=0, return_index=True), but returning
only the kept indices (numpy's sorted, unique-value form isn't what UNIQUE() wants).
Iterate values.
Optionaloptions: IRange.IteratorOptions
Aligns this range with any number of other ranges or scalars under Excel's broadcasting
rules, calls callbackFn with the aligned values at each position, and returns the results as
a new range of the broadcast shape. This is the N-ary form of broadcast, and the numpy
idiom "align once, apply the kernel, never index"
(np.frompyfunc(f, n, 1)(*np.broadcast_arrays(...))).
Broadcasting Rules (Excel's; broadcast shares them):
tile, default on).misalignValue
(default #N/A). The pad is an ARGUMENT, reaching the callback in that operand's slot for
the callback to decide what it means; it is not a result written around the callback.max(rows) × max(cols) over the operands, anchored at this range's origin.Iteration is sparse. The positions visited are the UNION of the operands' stored cells
after broadcast mapping; an operand with no cell at a visited position contributes its empty
value (null, or the empty of type). Where EVERY shaped operand is blank the answer depends
only on which operands are padded there, so those positions form REGIONS of equal padding,
one per combination of operand extents, and blankRegions says how they are answered:
'each' (default) calls the callback per position with its coordinates; 'once' calls it once
per region (the pandas SparseArray rule: the kernel runs once on fill_value and per stored
entry otherwise) — the unpadded region's answer is what the result's empty positions read as,
a padded region is written as runs. A region call carries coords of
{ rowIndex: -1, colIndex: -1 }: it answers for many positions and no one of them. Under
'once' a stretch of stored positions holding one value across every operand is one call too.
An operand's own empty positions read as its empty value (a fillEmpty, an earlier
elementwise result) and are never visited one by one.
Additional ranges or scalar values to align with this range, in argument order.
Called at each position with the aligned values (values[0] is this
range's, values[i + 1] is others[i]'s), the position relative to the output, and this
range. Returns the output value for that position. values is ONE buffer reused across
calls (the ufunc inner-loop rule): read it, do not retain it.
Optionaloptions: ZipOptions
IRange.ZipOptions. type reads EVERY operand's members, and the
empty, through that type; it defaults to this range's own type, as broadcast does.
Pass type: null to read every operand raw.
A new, untyped range of the broadcast shape (the values are the callback's, so this range's type does not describe them).
Calc.