Matrix
Representation of a rectangle of (maybe boxed) cell values. For the purposes of compact representation of a common redundancy structure, the rectangle should be thought of as consisting of four quadrants whose contents are specified as follows:
- the top-left quadrant is arbitrary data, specified with a dense array of
dense arrays of
MaybeBoxed<ArrayValue>, each array representing one row of that quadrant, all arrays having the same length. - the bottom-right quadrant has the same value in all its elements
- the top-right quadrant either has the same value as the bottom-right
quadrant in all its elements (if
_defaultColumnis empty), or else consists of constant-value rows, i.e. each row has a single value repeating in all its elements (but this value can differ between rows) - the bottom-left quadrant likewise either has the same value as the
bottom-right quadrant in all its elements (if
_defaultRowis empty), or else consists of constant-value columns, i.e. each column has a single value repeating in all its elements (but this value can differ between columns)
The populatedHeight and populatedWidth properties specify the dimensions
of the top left quadrant, and width and height then specify the remaining
quadrants, so if populatedHeight === height, then the bottom quadrants
are empty, and if populatedWidth === width, then the rightmost quadrants
are empty.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new Matrix(
width,height,defaultValue):Matrix
Construct a new Matrix with a given width and height and default value,
and populatedHeight and populatedWidth of 0.
The default value applies at any coordinates to the right of, and/or
downwards of, the largest X and Y coordinates for which a value has been
set, with .set or .setData. Within the range (0,0) to
(populatedWidth, populatedHeight), any coordinates at which a value has
not been set is blank (the value is null).
Parameters
Section titled “Parameters”number = 0
height
Section titled “height”number = 0
defaultValue
Section titled “defaultValue”MaybeBoxed<ArrayValue> = null
Returns
Section titled “Returns”Matrix
Properties
Section titled “Properties”_data:
MaybeBoxed<ArrayValue>[][]
Values of the elements in the top-left quadrant. Invariant: all rows are the same length.
_defaultColumn
Section titled “_defaultColumn”_defaultColumn:
MaybeBoxed<ArrayValue>[]
Values that apply in the rows of the top-right quadrant. This is either:
- the same length as
_data, in which case each value in this array specifies the value of every element along the corresponding row of the top-right quadrant - or empty, in which case
_defaultValuespecifies the value of every element in all rows of the top-right quadrant.
_defaultRow
Section titled “_defaultRow”_defaultRow:
MaybeBoxed<ArrayValue>[]
Values that apply in the columns of the bottom-left quadrant. This is either:
- the same length as each row of
_data, in which case each value in this array specifies the value of every element along the corresponding column of the bottom-left quadrant - or empty, in which case
_defaultValuespecifies the value of every element in all columns of the bottom-left quadrant.
_defaultValue
Section titled “_defaultValue”_defaultValue:
MaybeBoxed<ArrayValue>
The value of:
- every element of the bottom-right quadrant
- every element of the top-right quadrant, if
_defaultColumnis empty - every element of the bottom-left quadrant, if
_defaultRowis empty
Accessors
Section titled “Accessors”height
Section titled “height”Get Signature
Section titled “Get Signature”get height():
number
Returns
Section titled “Returns”number
Set Signature
Section titled “Set Signature”set height(
newHeight):void
Parameters
Section titled “Parameters”newHeight
Section titled “newHeight”number
Returns
Section titled “Returns”void
isPartiallyPopulated
Section titled “isPartiallyPopulated”Get Signature
Section titled “Get Signature”get isPartiallyPopulated():
boolean
Indicates whether or not this matrix is partially populated
Returns
Section titled “Returns”boolean
populatedHeight
Section titled “populatedHeight”Get Signature
Section titled “Get Signature”get populatedHeight():
number
Returns
Section titled “Returns”number
populatedWidth
Section titled “populatedWidth”Get Signature
Section titled “Get Signature”get populatedWidth():
number
Returns
Section titled “Returns”number
Get Signature
Section titled “Get Signature”get size():
number
Returns
Section titled “Returns”number
Get Signature
Section titled “Get Signature”get valid():
boolean
Returns
Section titled “Returns”boolean
Get Signature
Section titled “Get Signature”get width():
number
Returns
Section titled “Returns”number
Set Signature
Section titled “Set Signature”set width(
newWidth):void
Parameters
Section titled “Parameters”newWidth
Section titled “newWidth”number
Returns
Section titled “Returns”void
Methods
Section titled “Methods”_ensureSizeAttributesEncompass()
Section titled “_ensureSizeAttributesEncompass()”_ensureSizeAttributesEncompass(
x,y):void
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”void
_get()
Section titled “_get()”_get(
x,y,strict,leaveBoxed):MaybeBoxed<ArrayValue>
Parameters
Section titled “Parameters”number
number
strict
Section titled “strict”boolean = false
leaveBoxed
Section titled “leaveBoxed”boolean = false
Returns
Section titled “Returns”_resolveArea()
Section titled “_resolveArea()”_resolveArea<
O>(options):AreaArray<AreaArrayElement<O>>
Type Parameters
Section titled “Type Parameters”O extends Readonly<{ returnBoxed: boolean; returnCells: boolean; returnLambda: boolean; }>
Parameters
Section titled “Parameters”options
Section titled “options”ResolveAreaOptions<O>
Returns
Section titled “Returns”AreaArray<AreaArrayElement<O>>
_resolveRange()
Section titled “_resolveRange()”_resolveRange<
Boxed>(opts?):Boxedextendsfalse?ArrayValue:MaybeBoxed<ArrayValue>[]
Type Parameters
Section titled “Type Parameters”Boxed extends boolean = false
Parameters
Section titled “Parameters”IterationOptions<Boxed>
Returns
Section titled “Returns”Boxed extends false ? ArrayValue : MaybeBoxed<ArrayValue>[]
applyTrim()
Section titled “applyTrim()”applyTrim(
trim):FormulaError|Matrix
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”FormulaError | Matrix
clone()
Section titled “clone()”clone():
Matrix
Returns
Section titled “Returns”Matrix
collapseToCell()
Section titled “collapseToCell()”collapseToCell(
r,c):FormulaError|Matrix
Parameters
Section titled “Parameters”number = 0
number = 0
Returns
Section titled “Returns”FormulaError | Matrix
collapseToColumn()
Section titled “collapseToColumn()”collapseToColumn(
c):FormulaError|Matrix
Parameters
Section titled “Parameters”number = 0
Returns
Section titled “Returns”FormulaError | Matrix
collapseToNthCell()
Section titled “collapseToNthCell()”collapseToNthCell(
n):FormulaError|Matrix
Return a matrix of the zero-based nth element in a left-to-right-then-top-down traversal of this matrix.
Note that bounds checking is not performed; this can yield a cell outside this range.
The returned instance is guaranteed to be new, even if it is identical to this.
Parameters
Section titled “Parameters”number = 0
zero-based index of the value to return
Returns
Section titled “Returns”FormulaError | Matrix
matrix containing the single value specified, or error if n out of bounds
collapseToRow()
Section titled “collapseToRow()”collapseToRow(
r):FormulaError|Matrix
Parameters
Section titled “Parameters”number = 0
Returns
Section titled “Returns”FormulaError | Matrix
every()
Section titled “every()”every(
predicate):boolean
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value) => boolean
Returns
Section titled “Returns”boolean
expand()
Section titled “expand()”expand(
paddingValue,toRows,toCols):Matrix
Expand matrix to the given dimensions, using fillWith as a padding value.
If either dimension of the matrix is already the given size or larger, it
is not changed.
Parameters
Section titled “Parameters”paddingValue
Section titled “paddingValue”Value to use for padding the expanded matrix
toRows
Section titled “toRows”number
Desired number of rows in the expanded matrix.
toCols
Section titled “toCols”number
Desired number of columns in the expanded matrix.
Returns
Section titled “Returns”Matrix
get(
x,y,strict):ArrayValue
Parameters
Section titled “Parameters”number
number
strict
Section titled “strict”boolean = false
Returns
Section titled “Returns”getBoxed()
Section titled “getBoxed()”getBoxed(
x,y):MaybeBoxed<ArrayValue>
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”getByIndex()
Section titled “getByIndex()”getByIndex(
i):ArrayValue
Get the i’th element of this Matrix in by-rows iteration order.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”getColumnBoxed()
Section titled “getColumnBoxed()”getColumnBoxed(
c,includeDefaulted):MaybeBoxed<ArrayValue>[]
Get the (possibly boxed) values of column c as a simple (not area) array.
Parameters
Section titled “Parameters”number
includeDefaulted
Section titled “includeDefaulted”boolean = true
Returns
Section titled “Returns”getRowBoxed()
Section titled “getRowBoxed()”getRowBoxed(
r,includeDefaulted):MaybeBoxed<ArrayValue>[]
Get the (possibly boxed) values of row r as a simple (not area) array.
Parameters
Section titled “Parameters”number
includeDefaulted
Section titled “includeDefaulted”boolean = true
Returns
Section titled “Returns”hasDefaultValueFulfilling()
Section titled “hasDefaultValueFulfilling()”hasDefaultValueFulfilling(
predicate):boolean
Does this Matrix have a default value which fulfills the given predicate?
Parameters
Section titled “Parameters”predicate
Section titled “predicate”(value) => boolean
Returns
Section titled “Returns”boolean
hstack()
Section titled “hstack()”hstack(
other):Matrix
Stack matrices in a sequence horizontally (column wise). See e.g. https://numpy.org/doc/stable/reference/generated/numpy.hstack.html
Invariant: this.height === other.height
Parameters
Section titled “Parameters”Matrix
Other matrix. Must have the same height as this.
Returns
Section titled “Returns”Matrix
Horizontally stacked matrix
is1D()
Section titled “is1D()”is1D():
boolean
Returns
Section titled “Returns”boolean
iterAll()
Section titled “iterAll()”iterAll<
Boxed>(opts?):IterableIterator<{value:Boxedextendsfalse?ArrayValue:MaybeBoxed<ArrayValue>;x:number;y:number; }>
Yield all values in rows-first order, including default values for
unpopulated areas (unless they are blank and skipBlanks is not 'none').
Type Parameters
Section titled “Type Parameters”Boxed extends boolean = false
Parameters
Section titled “Parameters”IterationOptions<Boxed>
Returns
Section titled “Returns”IterableIterator<{ value: Boxed extends false ? ArrayValue : MaybeBoxed<ArrayValue>; x: number; y: number; }>
iterAllColumnWise()
Section titled “iterAllColumnWise()”iterAllColumnWise(
leaveBoxed):IterableIterator<{value:MaybeBoxed<ArrayValue>;x:number;y:number; }>
Parameters
Section titled “Parameters”leaveBoxed
Section titled “leaveBoxed”boolean = false
Returns
Section titled “Returns”IterableIterator<{ value: MaybeBoxed<ArrayValue>; x: number; y: number; }>
iterAllWithCount()
Section titled “iterAllWithCount()”iterAllWithCount():
IterableIterator<{count:number;value:ArrayValue; }>
Yield all values, including default values for unpopulated areas (but only once, with a count for how many times they are repeated), in unspecified order. The same value may be yielded multiple times, so the count each time is not necessarily the total number of occurrences of that value in the matrix; this is just run-length encoding to cut down on repetition.
Returns
Section titled “Returns”IterableIterator<{ count: number; value: ArrayValue; }>
iterColumnsBoxed()
Section titled “iterColumnsBoxed()”iterColumnsBoxed():
IterableIterator<{column:MaybeBoxed<ArrayValue>[];x:number; }>
Returns
Section titled “Returns”IterableIterator<{ column: MaybeBoxed<ArrayValue>[]; x: number; }>
iterPopulated()
Section titled “iterPopulated()”iterPopulated<
Boxed>(opts?):IterableIterator<{value:Boxedextendsfalse?ArrayValue:MaybeBoxed<ArrayValue>;x:number;y:number; }>
Type Parameters
Section titled “Type Parameters”Boxed extends boolean = false
Parameters
Section titled “Parameters”IterationOptions<Boxed>
Returns
Section titled “Returns”IterableIterator<{ value: Boxed extends false ? ArrayValue : MaybeBoxed<ArrayValue>; x: number; y: number; }>
iterRowsBoxed()
Section titled “iterRowsBoxed()”iterRowsBoxed():
IterableIterator<{row:MaybeBoxed<ArrayValue>[];y:number; }>
Returns
Section titled “Returns”IterableIterator<{ row: MaybeBoxed<ArrayValue>[]; y: number; }>
map(
fn):Matrix
Parameters
Section titled “Parameters”(element, coords) => MaybeBoxed<ArrayValue>
Returns
Section titled “Returns”Matrix
permuteColumns()
Section titled “permuteColumns()”permuteColumns(
permutation):Matrix
When providing the permutations for a matrix where width is
greater than populatedWidth, the length of permutation should
be populatedWidth + 1. Given a Matrix like so:
Matrix { populatedWidth: 3, width: 1000 }
permutation should should be of length 4, where
- indices 0, 1, 2 represent the indices of the populated rows, and
- index 3 represents all of the indices in the default quadrant.
Providing permutation = [ 0, 2, 1, 3 ] would create a matrix
of width 1000 with a populatedWidth of 3.
However, providing permutation = [ 0, 3, 1, 2 ] would create
a matrix of width 1000 where the populatedWidth is 1000
as well. permutation = [0, 3, 1, 2] is equivalent to:
permutation = [ 0, 3, 3, 3, (…994 more 3’s), 1, 2 ]
Parameters
Section titled “Parameters”permutation
Section titled “permutation”number[]
Returns
Section titled “Returns”Matrix
permuteRows()
Section titled “permuteRows()”permuteRows(
permutation):Matrix
When providing the permutations for a matrix where height is
greater than populatedHeight, the length of permutation should
be populatedHeight + 1. Given a Matrix like so:
Matrix { populatedHeight: 3, height: 1000 }
permutation should should be of length 4, where
- indices 0, 1, 2 represent the indices of the populated rows, and
- index 3 represents all of the indices in the default quadrant.
Providing permutation = [ 0, 2, 1, 3 ] would create a matrix
of height 1000 with a populatedHeight of 3.
However, providing permutation = [ 0, 3, 1, 2 ] would create
a matrix of height 1000 where the populatedHeight is 1000
as well. permutation = [0, 3, 1, 2] is equivalent to:
permutation = [ 0, 3, 3, 3, (…994 more 3’s), 1, 2 ]
Parameters
Section titled “Parameters”permutation
Section titled “permutation”number[]
Returns
Section titled “Returns”Matrix
resolveAreaBoxed()
Section titled “resolveAreaBoxed()”resolveAreaBoxed():
AreaBoxedValueArray
Returns
Section titled “Returns”resolveAreaCells()
Section titled “resolveAreaCells()”resolveAreaCells(
cropTo?):AreaCellArray
Parameters
Section titled “Parameters”cropTo?
Section titled “cropTo?”"any-cell-information" | "cells-with-non-blank-values"
Returns
Section titled “Returns”resolveAreaValues()
Section titled “resolveAreaValues()”resolveAreaValues():
AreaValueArray
Returns
Section titled “Returns”resolveCell()
Section titled “resolveCell()”resolveCell():
CellItem
Returns
Section titled “Returns”resolveRange()
Section titled “resolveRange()”resolveRange<
Boxed>(opts?):Boxedextendsfalse?ArrayValue:MaybeBoxed<ArrayValue>[]
Type Parameters
Section titled “Type Parameters”Boxed extends boolean = false
Parameters
Section titled “Parameters”IterationOptions<Boxed>
Returns
Section titled “Returns”Boxed extends false ? ArrayValue : MaybeBoxed<ArrayValue>[]
resolveSingle()
Section titled “resolveSingle()”resolveSingle():
ArrayValue
Returns
Section titled “Returns”resolveSingleBoxed()
Section titled “resolveSingleBoxed()”resolveSingleBoxed():
MaybeBoxed<ArrayValue>
Returns
Section titled “Returns”set(
x,y,value):void
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”void
setData()
Section titled “setData()”setData(
data):Matrix
Populate this matrix with the given data array.
The rows in data will be referenced, not copied, so data should be
considered to belong to this matrix henceforth, i.e. not mutated elsewhere.
Parameters
Section titled “Parameters”MaybeBoxed<ArrayValue>[][] | AreaBoxedValueArray | AreaValueArray
Returns
Section titled “Returns”Matrix
shrink()
Section titled “shrink()”shrink():
void
Shrink the _data property (populated top-left quadrant) if possible, by pruning away bottommost rows and rightmost columns in which all elements are exactly equal to _defaultValue. If the matrix starts out fully populated (i.e. has only a top-left quadrant, no defaulted quadrants), then first check whether the bottom row (if tall) or rightmost column (if wide) is all the same value, and if so, set _defaultValue to that.
Returns
Section titled “Returns”void
take()
Section titled “take()”take(
startRow,startCol,numRows,numCols):FormulaError|Matrix
Parameters
Section titled “Parameters”startRow
Section titled “startRow”number
startCol
Section titled “startCol”number
numRows
Section titled “numRows”number
numCols
Section titled “numCols”number
Returns
Section titled “Returns”FormulaError | Matrix
toMatrix()
Section titled “toMatrix()”toMatrix():
Matrix
Returns
Section titled “Returns”Matrix
toString()
Section titled “toString()”toString():
string
Returns
Section titled “Returns”string
trimBottom()
Section titled “trimBottom()”trimBottom():
void
Returns
Section titled “Returns”void
uniqueValues()
Section titled “uniqueValues()”uniqueValues():
Set<ArrayValue>
Returns
Section titled “Returns”Set<ArrayValue>
visitAllWithCount()
Section titled “visitAllWithCount()”visitAllWithCount(
visitor,minVisitWidth?,minVisitHeight?):boolean
Visit all cells with count-based run-length encoding. Unlike iterAllWithCount (which yields a flat iterator of { value, count } without coordinates), this method calls the visitor with x,y coordinates for each visited region.
Optional minVisitWidth and minVisitHeight parameters extend the individual-visit
region beyond this matrix’s populated dimensions. This is useful when other
matrices (e.g., criteria matrices) have larger populated regions - we need to
visit each coordinate individually where ANY matrix has non-default values.
The visitor receives (x, y, value, count, regionWidth, regionHeight):
- x, y: top-left coordinates of the region
- value: the value at (x, y), which applies to all cells in the region
- count: total number of cells in the region (= regionWidth * regionHeight)
- regionWidth, regionHeight: dimensions of the region (useful for dependency tracking)
The visitor may return true to stop iteration early.
Calls visitor for:
- Each cell in the individual-visit region (count: 1, regionWidth: 1, regionHeight: 1)
- Each row’s remaining column region (count: width - visitWidth, regionHeight: 1)
- Each column’s remaining row region (count: height - visitHeight, regionWidth: 1)
- The remaining corner region (count: remainingWidth * remainingHeight)
Parameters
Section titled “Parameters”visitor
Section titled “visitor”(x, y, value, count, regionWidth, regionHeight) => boolean | void
minVisitWidth?
Section titled “minVisitWidth?”number
minVisitHeight?
Section titled “minVisitHeight?”number
Returns
Section titled “Returns”boolean
true if visitor returned true (early termination), false otherwise
vstack()
Section titled “vstack()”vstack(
other):Matrix
Stack matrices in a sequence vertically (row wise). See e.g. https://numpy.org/doc/stable/reference/generated/numpy.vstack.html
Invariant: this.width === other.width
Parameters
Section titled “Parameters”Matrix
Other matrix. Must have the same width as this.
Returns
Section titled “Returns”Matrix
Vertically stacked matrix
createColumn()
Section titled “createColumn()”
staticcreateColumn(columnValues):Matrix
Parameters
Section titled “Parameters”columnValues
Section titled “columnValues”Returns
Section titled “Returns”Matrix
createRow()
Section titled “createRow()”
staticcreateRow(rowValues):Matrix
Parameters
Section titled “Parameters”rowValues
Section titled “rowValues”Returns
Section titled “Returns”Matrix
staticnew<T>(data):Matrix
Type Parameters
Section titled “Type Parameters”T extends MatrixNewData
Parameters
Section titled “Parameters”T & RequireWidthForDefaultColumn<T> & RequireHeightForDefaultRow<T> & RequireDimensionForDefaultValue<T>
Returns
Section titled “Returns”Matrix
staticof(value):Matrix
Parameters
Section titled “Parameters”MaybeBoxed<ArrayValue> | (undefined | null | MaybeBoxed<ArrayValue> | undefined[])[]
Returns
Section titled “Returns”Matrix
ofTransposed()
Section titled “ofTransposed()”
staticofTransposed(value):Matrix
Parameters
Section titled “Parameters”Matrix | MaybeBoxed<ArrayValue> | MaybeBoxed<ArrayValue>[][]
Returns
Section titled “Returns”Matrix