Class VBUserDefinedTypeValue
Represents a value of a VBUserDefinedType. Like VBObjectValue the value is a MemoryAddress: a UDT has location identity and is never passed by value.
public record VBUserDefinedTypeValue : VBTypedValue, IEquatable<VBTypedValue>, IVBTypedValue<VBUserDefinedTypeValue, MemoryAddress>, IEquatable<IVBTypedValue<VBUserDefinedTypeValue, MemoryAddress>>, IEquatable<VBUserDefinedTypeValue>
- Inheritance
-
VBUserDefinedTypeValue
- Implements
- Inherited Members
- Extension Methods
Remarks
👉 The field store is a flat block of cells in declaration order, exactly as
VBArrayValue holds its elements and for the same reason: a UDT's real content is its
fields, and a scalar IRuntimeValue has nowhere to hold them. Declaration order is not an
implementation detail: it is the order MS-VBAL §5.4.5.11 writes a record in, and the
order VBUserDefinedTypeLayout assigns offsets in.
Constructors
VBUserDefinedTypeValue(VBUserDefinedType)
public VBUserDefinedTypeValue(VBUserDefinedType typeInfo)
Parameters
typeInfoVBUserDefinedType
VBUserDefinedTypeValue(VBUserDefinedType, IVariableDefaults)
A record of typeInfo whose fields each start as fieldDefaults says a variable declared as the field
is starts.
public VBUserDefinedTypeValue(VBUserDefinedType typeInfo, IVariableDefaults fieldDefaults)
Parameters
typeInfoVBUserDefinedTypeThe type of the record.
fieldDefaultsIVariableDefaultsWhat each field, a typed symbol, starts as.
Remarks
A field is declared as a variable is (MS-VBAL §5.2.3.3), and a fixed-size array field is as big as its declaration's bounds, constant expressions that the field's symbol carries and that only the runtime reduces: the type's own default gives such a field no dimensions. This is the record a declared variable of the type starts as.
VBUserDefinedTypeValue(IBindingHandle, VBUserDefinedType)
public VBUserDefinedTypeValue(IBindingHandle handle, VBUserDefinedType typeInfo)
Parameters
handleIBindingHandletypeInfoVBUserDefinedType
VBUserDefinedTypeValue(VBUserDefinedTypeValue)
protected VBUserDefinedTypeValue(VBUserDefinedTypeValue original)
Parameters
originalVBUserDefinedTypeValue
VBUserDefinedTypeValue(MemoryAddress, VBUserDefinedType)
public VBUserDefinedTypeValue(MemoryAddress reference, VBUserDefinedType typeInfo)
Parameters
referenceMemoryAddresstypeInfoVBUserDefinedType
Properties
FieldCount
The number of fields the record has.
public int FieldCount { get; }
Property Value
Fields
This type's fields, in declaration order: the same symbols Fields() reports, held here so that a value can name its own fields without resolving its type again.
public ImmutableArray<VBUserDefinedTypeFieldSymbol> Fields { get; init; }
Property Value
this[string]
The value of the field named name, or null when there is no such field.
public VBTypedValue? this[string name] { get; }
Parameters
namestringThe field name, compared case-insensitively as VBA compares identifiers.
Property Value
Layout
Where each of this value's fields sits in memory.
public VBUserDefinedTypeLayout Layout { get; }
Property Value
Remarks
Laid out from the record itself: a fixed-size array field is as wide as its elements, which its value knows and its type does not.
Size
The in-memory size of this UDT, MS-VBA's own padding included: what LenB reports
(MS-VBAL §6.1.2.11).
public override int Size { get; }
Property Value
Remarks
Not the size a Put statement writes, which is the unpadded concatenation of the fields and is
what Len reports of a UDT instead: "Len returns the size as it will be written to the
file". VBUserDefinedTypeLayout holds the padding rule and the reasoning behind it.
Value
Gets the underlying managed value corresponding to this typed value.
public MemoryAddress Value { get; }
Property Value
Methods
DataCopy()
A copy of this record that shares no cell with it: the copy an assignment makes of a user-defined type (DataValues).
public VBUserDefinedTypeValue DataCopy()
Returns
Remarks
Each field is a copy in a cell of its own, deep through a nested record, an array and what a Variant holds, and the copy is bound
to no storage: it is whichever variable it is assigned to that gives it an address.
Equals(IVBTypedValue<VBUserDefinedTypeValue, MemoryAddress>?)
Indicates whether the current object is equal to another object of the same type.
public bool Equals(IVBTypedValue<VBUserDefinedTypeValue, MemoryAddress>? other)
Parameters
otherIVBTypedValue<VBUserDefinedTypeValue, MemoryAddress>An object to compare with this object.
Returns
FieldAt(int)
The value of the field at index in declaration order, or null when there is
no field there.
public VBTypedValue? FieldAt(int index)
Parameters
indexint
Returns
Remarks
Declaration order is what a record is written and read in, so a caller walking the fields to serialize them wants this rather than the name-keyed indexer.
GetFieldHandle(string)
The binding of the field named name, or null when there is no such field.
public IBindingHandle? GetFieldHandle(string name)
Parameters
namestringThe field name, compared case-insensitively.
Returns
Remarks
What a ByRef argument of a UDT field needs, and what an assignment to one writes through:
neither of which constructs a value, so neither goes through the indexer.
StoredFieldAt(int)
The field at index as the record stores it: bound to its own cell, which a write to the field writes to, whether or not
the record is known; null when there is no field there.
public VBTypedValue? StoredFieldAt(int index)
Parameters
indexintThe field's position in declaration order.
Returns
Remarks
FieldAt(int) reads a field of a record that is not known as a value that is not known either, which is another binding. A caller that needs the cell itself - what the object a field holds is held by - reads it here.
TryAllocateIn(ISessionStorage, out VBUserDefinedTypeValue?)
Reserves storage sized for this UDT through storage, and returns a copy of
this value bound to the resulting address. A UDT's identity is its address, so the allocated
copy reports the address it was allocated at.
public bool TryAllocateIn(ISessionStorage storage, out VBUserDefinedTypeValue? allocated)
Parameters
storageISessionStorageThe session storage the record is given an address in.
allocatedVBUserDefinedTypeValueThe copy of this record bound to its address;
nullwhen none was reserved.
Returns
- bool
falseif the underlying memory space is exhausted.
TryLetFieldAt(int, VBTypedValue)
Let-assigns value to the field at index in declaration order, in place (MS-VBAL §5.4.3.8): a ByRef
parameter given the field (GetFieldHandle(string), MS-VBAL §5.3.1.11) reads the value assigned, and the field reads what the parameter is
assigned.
public bool TryLetFieldAt(int index, VBTypedValue value)
Parameters
indexintThe field's position in declaration order.
valueVBTypedValueThe value to assign, of the field's declared type.
Returns
Remarks
A field of a scalar type, and a field that holds an object, is written in its own cell, the cell a ByRef parameter given the field is bound
to. A field declared as a record is let value field by field (TryLetFrom(VBUserDefinedTypeValue)), and a fixed-size array field element by
element (TryLetFrom(VBArrayValue)): the record holds its elements itself.
A field that holds a Variant or a resizable array is replaced by value, as TrySetFieldAt(int, VBTypedValue) replaces it. A
ByRef parameter given a Variant field is bound to the record and the field's position, so it reads the value that replaced it. A field
is replaced the same way when value cannot be written where the field is: a value of another kind than the field holds, a record
that is not known, or a fixed-size array that is not known or has other bounds.
value is of the field's declared type, which the assignment let-coerced it to, and shares no cell with anything else: a record or
an array in it becomes the field's own.
TryLetFrom(VBUserDefinedTypeValue)
Let-assigns source to this record in place (MS-VBAL §5.4.3.8), each field from the same field of source
(TryLetFieldAt(int, VBTypedValue)): a ByRef parameter given a field of this record (MS-VBAL §5.3.1.11) reads the value assigned.
public bool TryLetFrom(VBUserDefinedTypeValue source)
Parameters
sourceVBUserDefinedTypeValueThe record assigned, of this record's type.
Returns
Remarks
source is the copy the assignment made (DataCopy()), which shares no cell with anything else: a value of it that
replaces a field (an object, a Variant or a resizable array) becomes this record's own.
TryResetFieldAt(int)
Resets the field at index in declaration order to the default value of its declared type, as a new record holds it. The field
is written in place wherever TryLetFieldAt(int, VBTypedValue) writes in place.
public bool TryResetFieldAt(int index)
Parameters
indexintThe field's position in declaration order.
Returns
Remarks
A field declared as a record has each of its own fields reset, and a fixed-size array field each of its elements (ResetElements()), which keeps its bounds. Any other field is let a copy of the type's default value, in a cell of its own: the default value of a type is one value every caller shares, and a field that held it would share its cell with every other.
TrySetField(string, VBTypedValue)
Replaces the value of the field named name. Mutates the cell in place: field
storage is mutable, the way array element storage is.
public bool TrySetField(string name, VBTypedValue value)
Parameters
namestringThe field name, compared case-insensitively.
valueVBTypedValueThe value to store.
Returns
- bool
falsewhen there is no such field.
TrySetFieldAt(int, VBTypedValue)
Replaces the value of the field at index in declaration order.
public bool TrySetFieldAt(int index, VBTypedValue value)
Parameters
indexintThe field's position in declaration order.
valueVBTypedValueThe value to store.
Returns
- bool
falsewhen there is no field there.