Class VBArrayValue
A VBTypedValue representing a runtime value of the VBArrayType data type.
public abstract record VBArrayValue : VBTypedValue, IEquatable<VBTypedValue>, IEquatable<VBArrayValue>
- Inheritance
-
VBArrayValue
- Implements
- Derived
- Inherited Members
- Extension Methods
Remarks
👉 The element store is a single flat block of IBindingHandle cells addressed in
column-major order (the first subscript varies fastest, as an OLE SAFEARRAY).
Bounds live in Dimensions as metadata (LBound/UBound/rank); the cells
are mutable storage. An uninitialized array (Dim a()) has no dimensions and no cells.
Constructors
VBArrayValue(IBindingHandle, (int lBound, int uBound)[], VBType)
Creates an array value bound to handle. The array's own binding is a
storage concern distinct from the element cells; it is currently inert (see the
session-storage follow-up).
protected VBArrayValue(IBindingHandle handle, (int lBound, int uBound)[] dimensions, VBType itemType)
Parameters
VBArrayValue(VBArrayValue)
protected VBArrayValue(VBArrayValue original)
Parameters
originalVBArrayValue
VBArrayValue((int lBound, int uBound)[], VBType, Func<VBTypedValue>?, Func<IBindingHandle>?)
Creates an array value with the given dimension bounds and element type.
protected VBArrayValue((int lBound, int uBound)[] dimensions, VBType itemType, Func<VBTypedValue>? elementDefault = null, Func<IBindingHandle>? elementCell = null)
Parameters
dimensions(int lBound, int uBound)[]The lower and upper bound of each dimension, outermost first.
itemTypeVBTypeThe element type. Use VBVariantType when unspecified.
elementDefaultFunc<VBTypedValue>What each element starts as, when it is more than the element type's own default value can say (ElementDefaultOf(VBType)); null for that default.
elementCellFunc<IBindingHandle>Makes the cell each element is stored in, holding the element type's default value, when the runtime stores elements of
itemTypein cells of its own (ElementCellOf(VBType)); null for a cell that holds the default value as it is. Not used for an element that is a record, whichelementDefaultmakes.
Fields
MaximumLength
The most elements an array holds in RD-VBA: 16,777,216 (224), in every dimension together.
public const long MaximumLength = 16777216
Field Value
Remarks
Each element of an array is a cell of its own (IBindingHandle), where an element of an MS-VBA array is the bytes of its data type in one
block of memory: MS-VBA (64-bit) allocates ReDim b(2147483647) As Byte as long as the memory is there, and RD-VBA refuses an array that size
before making a cell of it. A ReDim of more elements is run-time error 7, Out of memory
(RD-VBAL §5.4.3.3).
Properties
Dimensions
The bounds of each dimension (outermost first). Empty for an uninitialized array.
public ImmutableArray<VBArrayValue.VBArrayDimension> Dimensions { get; init; }
Property Value
IsInitialized
true if this array has at least one dimension.
public bool IsInitialized { get; }
Property Value
this[int[]]
Gets the element at the given subscripts, or null when any subscript is out of bounds
(semantics raise SubscriptOutOfRange in that case) or the subscript count does not match
the array rank.
public VBTypedValue? this[params int[] subscripts] { get; }
Parameters
subscriptsint[]
Property Value
ItemType
public VBType ItemType { get; init; }
Property Value
Length
The total number of elements across every dimension.
public int Length { get; }
Property Value
Rank
The number of dimensions of this array. 0 for an uninitialized array.
public int Rank { get; }
Property Value
Size
The allocated size (in bytes) of this value.
public override int Size { get; }
Property Value
Methods
CellAt(int)
Gets the binding of the element at a flat index, in the order ElementAt(int) reads them, or null when there is no element
there.
public IBindingHandle? CellAt(int flatIndex)
Parameters
Returns
Remarks
For whoever walks every cell of the array without subscripts - what the objects its elements hold are held by, each by its own cell.
DataCopy()
The declared VBType of the elements in this array.
public VBArrayValue DataCopy()
Returns
Remarks
Each element is a copy in a cell of its own, deep through what a Variant element holds, and the copy is bound to no storage: it is
whichever variable it is assigned to that gives it an address.
ElementAt(int)
Gets the element at the given flat (column-major) index, or null when out of bounds.
public VBTypedValue? ElementAt(int flatIndex)
Parameters
flatIndexint
Returns
Remarks
MS-VBAL §5.4.2.4.1 Array Enumeration Order: the first element has every index
at its dimension's lower bound; the next increments the leftmost (outermost) dimension, carrying
into the next dimension to its right on overflow — exactly this store's own column-major layout,
so a For Each over an array can walk Length flat indices directly, without
re-deriving per-dimension subscripts.
ForgetElements(IRuntimeValue?)
Makes the elements that an assignment to an element that could be any of them may have replaced not known.
public void ForgetElements(IRuntimeValue? assigned = null)
Parameters
assignedIRuntimeValueThe value the assignment stores, when it is known: an element that already holds it is the same after the assignment whichever element was assigned, so it stays known. null when the value is not known, which leaves no element that is.
Remarks
An assignment to A(i) with an unknown i replaces exactly one element, and which one is not known: afterwards each element holds
either what it held or the value assigned. That is a value the array does not know, unless the two are the same.
GetElementHandle(params int[])
Gets the binding of the element at the given subscripts, or null when any subscript is out of
bounds or the subscript count does not match the array rank.
public IBindingHandle? GetElementHandle(params int[] subscripts)
Parameters
subscriptsint[]
Returns
Remarks
Unlike the indexer, this never constructs a typed value, so it also reads an element whose type has no value that can be built from a binding alone (a class, user-defined type or Object element). A cell that was never assigned holds an inert binding.
IndexOf(ReadOnlySpan<int>)
The flat index of the element at the given subscripts, in the order ElementAt(int) and CellAt(int) read them; -1 when any
subscript is out of bounds or the subscript count does not match the array rank (MS-VBAL §5.6.13's error 9, for the caller to
raise).
public int IndexOf(ReadOnlySpan<int> subscripts)
Parameters
subscriptsReadOnlySpan<int>One subscript per dimension, outermost first.
Returns
Remarks
For a caller that already has the subscripts as integers and reads or writes the element's cell itself, without the array of subscripts the
params members are given.
LengthOf(IEnumerable<(int LBound, int UBound)>)
The number of elements an array of the given bounds has, which may be more than an int holds: (0, 2147483647) is
2,147,483,648 of them.
public static long LengthOf(IEnumerable<(int LBound, int UBound)> bounds)
Parameters
boundsIEnumerable<(int LBound, int UBound)>The lower and upper bound of each dimension.
Returns
- long
The product of the lengths of the dimensions, or MaximumLength + 1 for any product greater than that (which three dimensions of 231 elements would overflow);
0when a dimension has an upper bound below its lower bound.
ResetElements()
Gives each element of this array the default value of its element type, in place: the array keeps its bounds, and a ByRef parameter given
an element (MS-VBAL §5.3.1.11) reads the default.
public void ResetElements()
Remarks
An element that is a record has each of its fields reset in its turn (TryResetFieldAt(int)). An element never assigned is left as it is, since it already holds the default.
TryAllocateIn(ISessionStorage, out VBArrayValue?)
Reserves storage sized for this array's own slot through storage, and returns
a copy of this value bound to the resulting address. This is the array variable's
identity, distinct from its element cells (which remain the same managed storage): a real
address is what lets ReDim, Erase, and array-identity comparisons have something
to point at, matching how a SAFEARRAY variable's own slot is a pointer, never the array's
contents.
public bool TryAllocateIn(ISessionStorage storage, out VBArrayValue? allocated)
Parameters
storageISessionStorageallocatedVBArrayValue
Returns
- bool
falseif the underlying memory space is exhausted.
TryLetElementAt(int, VBTypedValue)
Let-assigns value to the element at a flat index, in the order ElementAt(int) reads them, in its own cell: a
ByRef parameter given the element (MS-VBAL §5.3.1.11) reads the value assigned, as it does after TryLetFrom(VBArrayValue).
public bool TryLetElementAt(int flatIndex, VBTypedValue value)
Parameters
flatIndexintFrom 0 to Length - 1.
valueVBTypedValueThe value to assign, of the array's element type.
Returns
Remarks
An element whose cell cannot be written, one never assigned, is given the cell of value instead, which must share no cell with
anything else.
TryLetFrom(VBArrayValue)
Let-assigns the elements of source to the elements of this array, in place (MS-VBAL §5.4.3.8). A fixed-size array
field of a record is let this way when the record is let, since the record holds the array's elements itself.
public bool TryLetFrom(VBArrayValue source)
Parameters
sourceVBArrayValueThe array assigned, of this array's element type and bounds.
Returns
Remarks
Each element is written in its own cell, which a ByRef parameter given the element is bound to (MS-VBAL §5.3.1.11), so the parameter reads
what the element holds after the assignment: an element of an object type or a Variant as much as one of a scalar type. An element that is
a record is let in place in its turn (TryLetFrom(VBUserDefinedTypeValue)).
An element whose cell cannot be written, one never assigned, is given the cell of source's element instead: no ByRef
parameter is bound to it, since passing the element gives it a cell that can be written first. source is the copy the
assignment made (DataCopy()), which shares no cell with anything else.
TrySetElement(IBindingHandle, params int[])
Rebinds the element at the given subscripts to value. Mutates the cell in
place — array element storage is mutable. Returns false when the subscripts are out of
bounds or their count does not match the array rank.
public bool TrySetElement(IBindingHandle value, params int[] subscripts)
Parameters
valueIBindingHandlesubscriptsint[]
Returns
TrySetElementAt(int, IBindingHandle)
Rebinds the element at a flat index, in the order ElementAt(int) reads them, to value: what writes an element at its
address in memory, which is where it is in that order.
public bool TrySetElementAt(int flatIndex, IBindingHandle value)
Parameters
flatIndexintFrom 0 to Length - 1.
valueIBindingHandleThe element's new binding.
Returns
- bool
falsewhen there is no element at the index.