Interface IStdCollectionClass

Namespace

RDCore.SDK.Runtime.Abstract.StdLib

Assembly

RDCore.SDK.dll

MS-VBAL 6.1.3.1 Collection Object

[StdLibClass(null)]
public interface IStdCollectionClass

Remarks

Formalizes the public interface of the Collection class: a sequence of values, each reachable by its position and, when it was added with a key, by that.

👉 A collection has state of its own - its members - so unlike the error object it is one of many: each New Collection is an instance, and an implementation keeps what is in it by the object it is called on.

Item(VBVariantValue) is the default member of the class (Value), so c(1) is c.Item(1), and NewEnum() is its enumeration member (NewEnum), which is what makes a For Each over a collection find its members (RD-VBAL §5.4.2.4).

Methods

Add(VBVariantValue, VBVariantValue?, VBVariantValue?, VBVariantValue?)

Adds a member to the collection; the member is appended unless specified otherwise.

RuntimeSemanticsEvaluationResult Add(VBVariantValue item, VBVariantValue? key = null, VBVariantValue? before = null, VBVariantValue? after = null)

Parameters

item VBVariantValue

An expression of any type that specifies the member to be added to the collection.

key VBVariantValue

A VBStringValue that is unique across the keys of the collection, and can be used in place of a positional index to access the member.
💥KeyAlreadyAssociatedWithAnElementOfCollection if the specified key is already in use.

before VBVariantValue

A position or a key: the member to be added is placed before the member it identifies.
💥InvalidProcedureCallOrArgument if both before and after are specified, or if either refers to a member that does not exist.

after VBVariantValue

A position or a key: the member to be added is placed after the member it identifies.
💥InvalidProcedureCallOrArgument if both before and after are specified, or if either refers to a member that does not exist.

Returns

RuntimeSemanticsEvaluationResult

A RuntimeSemanticsEvaluationResult object encapsulating the result of the successful operation, or the error metadata otherwise.

Remarks

👉 Object collections want to be enumerated, not indexed. Indexed access within a loop should raise some performance-related semantic flags.

Count()

Returns the number of members in the collection.

RuntimeSemanticsEvaluationResult<VBLongValue> Count()

Returns

RuntimeSemanticsEvaluationResult<VBLongValue>

A RuntimeSemanticsEvaluationResult object encapsulating the result of the successful operation, or the error metadata otherwise.

Item(VBVariantValue)

Retrieves a specific member either by position (index) or by key.

[StdLibMember(null, UserMemId = 0)]
RuntimeSemanticsEvaluationResult<VBVariantValue> Item(VBVariantValue index)

Parameters

index VBVariantValue

A number from 1 to Count(), or the key the member was added with.
💥InvalidProcedureCallOrArgument if no member is at that position or has that key.

Returns

RuntimeSemanticsEvaluationResult<VBVariantValue>

A RuntimeSemanticsEvaluationResult object encapsulating the result of the successful operation, or the error metadata otherwise.

Remarks

👉 Object collections want to be enumerated, not indexed. Indexed access within a loop should raise some performance-related semantic flags.

NewEnum()

Returns the object that enumerates the collection: what a For Each over it drives.

[StdLibMember("_NewEnum", ReturnType = typeof(IStdEnumVariantClass), IsHidden = true, UserMemId = -4)]
RuntimeSemanticsEvaluationResult<VBObjectValue> NewEnum()

Returns

RuntimeSemanticsEvaluationResult<VBObjectValue>

A RuntimeSemanticsEvaluationResult whose value is an object of the IEnumVARIANT class (IStdEnumVariantClass).

Remarks

The enumerator is a snapshot of the members the collection has when it is asked for: a member added or removed while a For Each runs is not the loop's. It is a hidden member, _NewEnum, which VBA source reaches as [_NewEnum].

Remove(VBVariantValue)

Removes a member from the collection.

RuntimeSemanticsEvaluationResult Remove(VBVariantValue index)

Parameters

index VBVariantValue

The key or positional index of the member to be removed.
💥InvalidProcedureCallOrArgument if no member is at that position or has that key.

Returns

RuntimeSemanticsEvaluationResult

A RuntimeSemanticsEvaluationResult object encapsulating the result of the successful operation, or the error metadata otherwise.