diff --git a/docs/Reference/Modules/Collection/Add.md b/docs/Reference/Modules/Collection/Add.md new file mode 100644 index 0000000..2522502 --- /dev/null +++ b/docs/Reference/Modules/Collection/Add.md @@ -0,0 +1,71 @@ +--- +title: Add +parent: Collection Module +permalink: /tB/Modules/Collection/Add +--- +# Add +{: .no_toc } + +Adds a member to a **Collection** object. + +Syntax: *object*.**Add** *item* [ **,** *key* ] [ **,** *before* ] [ **,** *after* ] + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +*item* +: *required* An expression of any type that specifies the member to add to the collection. + +*key* +: *optional* A unique string expression that specifies a key string that can be used, instead of a positional index, to access a member of the collection. + +*before* +: *optional* An expression that specifies a relative position in the collection. The member to be added is placed in the collection before the member identified by the *before* argument. If a numeric expression, *before* must be a number from 1 to the value of the collection's [**Count**](Count) property. If a string expression, *before* must correspond to the *key* specified when the member being referred to was added to the collection. You can specify a *before* position or an *after* position, but not both. + +*after* +: *optional* An expression that specifies a relative position in the collection. The member to be added is placed in the collection after the member identified by the *after* argument. The same numeric and string-key constraints as *before* apply. You can specify a *before* position or an *after* position, but not both. + +If neither *before* nor *after* is specified, the new item is added at the end of the collection. + +Whether *before* or *after* is a string expression or a numeric expression, it must refer to an existing member of the collection, or an error occurs. + +An error also occurs if a specified *key* duplicates the *key* for an existing member of the collection. Key comparison is governed by the [**KeyCompareMode**](KeyCompareMode) property. + +### Example + +This example uses the **Add** method to add `Inst` objects (instances of a class called `Class1` containing a **Public** variable `InstanceName`) to a collection called `MyClasses`. To run this code, insert a class module and declare a public variable called `InstanceName` at module level of `Class1` (type `Public InstanceName`) to hold the names of each instance. Leave the default name as `Class1`. + +```tb +Dim MyClasses As New Collection ' Create a Collection object. +Dim Num As Integer ' Counter for individualizing keys. +Dim Msg As String +Dim TheName As Variant ' Holder for names user enters. +Do + Dim Inst As New Class1 ' Create a new instance of Class1. + Num = Num + 1 ' Increment Num, then get a name. + Msg = "Please enter a name for this object." & vbNewLine _ + & "Press Cancel to see names in collection." + TheName = InputBox(Msg, "Name the Collection Items") + Inst.InstanceName = TheName ' Put name in object instance. + ' If user entered name, add it to the collection. + If Inst.InstanceName <> "" Then + ' Add the named object to the collection. + MyClasses.Add Item := Inst, Key := CStr(Num) + End If + ' Clear the current reference in preparation for next one. + Set Inst = Nothing +Loop Until TheName = "" +Dim x As Variant +For Each x In MyClasses + MsgBox x.InstanceName, , "Instance Name" +Next +``` + +### See Also + +- [Count](Count) property +- [Item](Item) method +- [Remove](Remove) method +- [Exists](Exists) method + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/Clear.md b/docs/Reference/Modules/Collection/Clear.md new file mode 100644 index 0000000..94dff65 --- /dev/null +++ b/docs/Reference/Modules/Collection/Clear.md @@ -0,0 +1,40 @@ +--- +title: Clear +parent: Collection Module +permalink: /tB/Modules/Collection/Clear +--- +# Clear +{: .no_toc } + +Removes all elements from a **Collection** object. After **Clear** returns, the collection's [**Count**](Count) is zero. + +Syntax: *object*.**Clear** + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +> [!NOTE] +> +> **Clear** is a twinBASIC extension; the classic VBA **Collection** object has no **Clear** method. The same effect in VBA requires repeatedly removing the first item until the collection is empty. + +Use **Clear** to reset a **Collection** to its initial, empty state when you want to reuse the object without creating a new instance. + +### Example + +```tb +Dim MyClasses As New Collection +MyClasses.Add "first" +MyClasses.Add "second" +MyClasses.Add "third" +Debug.Print MyClasses.Count ' Prints 3. + +MyClasses.Clear +Debug.Print MyClasses.Count ' Prints 0. +``` + +### See Also + +- [Count](Count) property +- [Remove](Remove) method + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/Count.md b/docs/Reference/Modules/Collection/Count.md new file mode 100644 index 0000000..fe733fb --- /dev/null +++ b/docs/Reference/Modules/Collection/Count.md @@ -0,0 +1,37 @@ +--- +title: Count +parent: Collection Module +permalink: /tB/Modules/Collection/Count +--- +# Count +{: .no_toc } + +Returns a **Long** containing the number of items in a **Collection** object. Read-only. + +Syntax: *object*.**Count** + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +### Example + +This example uses the **Collection** object's **Count** property to specify how many iterations are required to remove all the elements of the collection called `MyClasses`. Collection numeric indexes start at 1 by default. Because collections are reindexed automatically when a removal is made, the following code removes the first member on each iteration. + +```tb +Dim Num As Long, MyClasses As Collection +Set MyClasses = New Collection +' ... assume MyClasses has been populated ... + +For Num = 1 To MyClasses.Count ' Default collection numeric indexes + MyClasses.Remove 1 ' begin at 1. +Next +``` + +### See Also + +- [Add](Add) method +- [Item](Item) method +- [Remove](Remove) method +- [Clear](Clear) method + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/Exists.md b/docs/Reference/Modules/Collection/Exists.md new file mode 100644 index 0000000..68c1c47 --- /dev/null +++ b/docs/Reference/Modules/Collection/Exists.md @@ -0,0 +1,48 @@ +--- +title: Exists +parent: Collection Module +permalink: /tB/Modules/Collection/Exists +--- +# Exists +{: .no_toc } + +Returns **True** if a specified key exists in a **Collection** object; **False** if it does not. + +Syntax: *object*.**Exists(** *key* **)** + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +*key* +: *required* A **String** value identifying the item to locate in the collection. + +> [!NOTE] +> +> **Exists** is a twinBASIC extension; the classic VBA **Collection** object has no **Exists** method. The same effect in VBA requires calling [**Item**](Item) inside an error-handling block. + +Key comparison is governed by the [**KeyCompareMode**](KeyCompareMode) property. + +### Example + +```tb +Dim MyCollection As New Collection +MyCollection.Add "alpha", Key:="a" +MyCollection.Add "beta", Key:="b" + +If MyCollection.Exists("a") Then + Debug.Print "Key 'a' is in the collection." +End If + +If Not MyCollection.Exists("z") Then + Debug.Print "Key 'z' is not in the collection." +End If +``` + +### See Also + +- [Add](Add) method +- [Item](Item) method +- [Keys](Keys) method +- [KeyCompareMode](KeyCompareMode) property + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/Item.md b/docs/Reference/Modules/Collection/Item.md new file mode 100644 index 0000000..5948222 --- /dev/null +++ b/docs/Reference/Modules/Collection/Item.md @@ -0,0 +1,53 @@ +--- +title: Item +parent: Collection Module +permalink: /tB/Modules/Collection/Item +--- +# Item +{: .no_toc } + +Returns a specific member of a **Collection** object, either by position or by key. + +Syntax: *object*.**Item(** *index* **)** + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +*index* +: *required* An expression that specifies the position of a member of the collection. If a numeric expression, *index* must be a number from 1 to the value of the collection's [**Count**](Count) property. If a string expression, *index* must correspond to the *key* argument specified when the member referred to was added to the collection. + +If *index* doesn't match any existing member of the collection, an error occurs. If *index* is neither a number nor a string, an error also occurs. + +**Item** is the default member of a **Collection** object. Therefore, the following lines of code are equivalent: + +```tb +Debug.Print MyCollection(1) +Debug.Print MyCollection.Item(1) +``` + +Key comparison is governed by the [**KeyCompareMode**](KeyCompareMode) property. + +### Example + +This example uses the **Item** method to retrieve a reference to an object in a collection. Assuming `Birthdays` is a **Collection** object, the following code retrieves references to the objects representing Bill Smith's birthday and Adam Smith's birthday, using the keys `"SmithBill"` and `"SmithAdam"` as the *index* arguments. + +The first call explicitly specifies the **Item** method; the second does not. Both calls work because **Item** is the default member of a **Collection** object. + +```tb +Dim SmithBillBD As Object +Dim SmithAdamBD As Object +Dim Birthdays As Collection +' ... assume Birthdays has been populated ... +Set SmithBillBD = Birthdays.Item("SmithBill") +Set SmithAdamBD = Birthdays("SmithAdam") +``` + +### See Also + +- [Add](Add) method +- [Count](Count) property +- [Exists](Exists) method +- [Items](Items) method +- [Remove](Remove) method + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/Items.md b/docs/Reference/Modules/Collection/Items.md new file mode 100644 index 0000000..9684c70 --- /dev/null +++ b/docs/Reference/Modules/Collection/Items.md @@ -0,0 +1,48 @@ +--- +title: Items +parent: Collection Module +permalink: /tB/Modules/Collection/Items +--- +# Items +{: .no_toc } + +Returns a **Variant** array containing all the items in a **Collection** object. The lower bound of the returned array is zero. + +Syntax: *object*.**Items()** + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +> [!NOTE] +> +> **Items** is a twinBASIC extension; the classic VBA **Collection** object has no **Items** method. The same effect in VBA requires iterating the collection with **For Each** and copying each item into an array. + +If the collection is empty, **Items** returns an empty array. + +The **Items** method is useful when you need to pass the collection's contents to a procedure expecting an array, or to iterate without holding a reference to the collection. + +### Example + +```tb +Dim col As New Collection +col.Add "Athens" +col.Add "Belgrade" +col.Add "Cairo" + +Dim a As Variant +a = col.Items ' Get all items as a Variant array. + +Dim i As Long +For i = LBound(a) To UBound(a) + Debug.Print a(i) +Next i +``` + +### See Also + +- [Item](Item) method +- [Keys](Keys) method +- [Count](Count) property +- [Add](Add) method + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/KeyCompareMode.md b/docs/Reference/Modules/Collection/KeyCompareMode.md new file mode 100644 index 0000000..067de2a --- /dev/null +++ b/docs/Reference/Modules/Collection/KeyCompareMode.md @@ -0,0 +1,57 @@ +--- +title: KeyCompareMode +parent: Collection Module +permalink: /tB/Modules/Collection/KeyCompareMode +--- +# KeyCompareMode +{: .no_toc } + +Returns or sets the comparison mode used when matching string keys in a **Collection** object. Read/write. + +Syntax: +- *object*.**KeyCompareMode** +- *object*.**KeyCompareMode** **=** *compare* + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +*compare* +: A **VbCompareMethod** value specifying the comparison mode used by [**Add**](Add), [**Item**](Item), [**Remove**](Remove) and [**Exists**](Exists) when looking up keys. + +The *compare* argument settings are: + +| Constant | Value | Description | +|---------------------|-------|--------------------------------------| +| **vbBinaryCompare** | 0 | Performs a case-sensitive binary comparison. | +| **vbTextCompare** | 1 | Performs a case-insensitive textual comparison. | + +> [!NOTE] +> +> **KeyCompareMode** is a twinBASIC extension; the classic VBA **Collection** object always uses case-insensitive comparison and does not expose this property. + +The default comparison mode is **vbBinaryCompare**. Changing the comparison mode rehashes the existing keys, so for large collections it is most efficient to set **KeyCompareMode** before adding items. + +### Example + +```tb +Dim col As New Collection + +' Default mode is binary (case-sensitive). +col.Add "first", Key:="A" +col.Add "second", Key:="a" ' Distinct from "A" — succeeds. + +Dim col2 As New Collection +col2.KeyCompareMode = vbTextCompare +col2.Add "first", Key:="A" +' col2.Add "second", Key:="a" ' Would raise an error — same key as "A". +``` + +### See Also + +- [Add](Add) method +- [Exists](Exists) method +- [KeyCountHint](KeyCountHint) property +- [StrComp](../Strings/StrComp) function +- [Option Compare](../../Core/Option) statement + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/KeyCountHint.md b/docs/Reference/Modules/Collection/KeyCountHint.md new file mode 100644 index 0000000..59473e2 --- /dev/null +++ b/docs/Reference/Modules/Collection/KeyCountHint.md @@ -0,0 +1,47 @@ +--- +title: KeyCountHint +parent: Collection Module +permalink: /tB/Modules/Collection/KeyCountHint +--- +# KeyCountHint +{: .no_toc } + +Returns or sets a hint to a **Collection** object about the number of keyed items it is expected to hold, allowing the underlying hash table to be sized accordingly. Read/write. + +Syntax: +- *object*.**KeyCountHint** +- *object*.**KeyCountHint** **=** *hint* + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +*hint* +: A **Long** value giving the estimated number of keyed items that will be added to the collection. + +> [!NOTE] +> +> **KeyCountHint** is a twinBASIC extension and has no equivalent in the classic VBA **Collection** object. + +Setting **KeyCountHint** is optional. It is most effective when set before any items are added to the collection: the hint is used to pre-allocate the hash table and avoid repeated resizing as items are inserted. If the actual number of keyed items exceeds the hint, the collection still functions correctly, but performance may be reduced while the hash table grows. + +The hint affects only keyed items (those added with a **Key** argument); items added without a key are unaffected. + +### Example + +```tb +Dim Big As New Collection +Big.KeyCountHint = 100000 ' We expect about 100k keyed items. + +Dim i As Long +For i = 1 To 100000 + Big.Add i, Key:=CStr(i) +Next +``` + +### See Also + +- [Add](Add) method +- [Exists](Exists) method +- [KeyCompareMode](KeyCompareMode) property + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/Keys.md b/docs/Reference/Modules/Collection/Keys.md new file mode 100644 index 0000000..1fced1f --- /dev/null +++ b/docs/Reference/Modules/Collection/Keys.md @@ -0,0 +1,47 @@ +--- +title: Keys +parent: Collection Module +permalink: /tB/Modules/Collection/Keys +--- +# Keys +{: .no_toc } + +Returns a **String** array containing all the keys associated with items in a **Collection** object. + +Syntax: *object*.**Keys()** + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +> [!NOTE] +> +> **Keys** is a twinBASIC extension; the classic VBA **Collection** object has no **Keys** method. + +Only items that were added with a **Key** argument appear in the returned array. If no items have keys, the array is empty. + +### Example + +```tb +Dim col As New Collection +col.Add "Athens", Key:="a" +col.Add "Belgrade", Key:="b" +col.Add "Cairo", Key:="c" + +Dim k() As String +k = col.Keys + +Dim i As Long +For i = LBound(k) To UBound(k) + Debug.Print k(i), col(k(i)) +Next i +``` + +### See Also + +- [Add](Add) method +- [Exists](Exists) method +- [Item](Item) method +- [Items](Items) method +- [Count](Count) property + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/Remove.md b/docs/Reference/Modules/Collection/Remove.md new file mode 100644 index 0000000..93fe5be --- /dev/null +++ b/docs/Reference/Modules/Collection/Remove.md @@ -0,0 +1,49 @@ +--- +title: Remove +parent: Collection Module +permalink: /tB/Modules/Collection/Remove +--- +# Remove +{: .no_toc } + +Removes a member from a **Collection** object. + +Syntax: *object*.**Remove(** *index* **)** + +*object* +: *required* An object expression that evaluates to a **Collection** object. + +*index* +: *required* An expression that specifies the member of the collection to remove. If a numeric expression, *index* must be a number from 1 to the value of the collection's [**Count**](Count) property. If a string expression, *index* must correspond to the *key* argument specified when the member was added to the collection. + +If *index* doesn't match an existing member of the collection, an error occurs. + +When an item is removed, the indexes of subsequent items decrease by one. Take this into account when iterating over a collection while removing items — see the example below. + +Key comparison is governed by the [**KeyCompareMode**](KeyCompareMode) property. + +### Example + +This example uses the **Remove** method to remove every object from a **Collection** named `MyClasses`. Because items are reindexed automatically, the first item is removed on each iteration of the loop. + +```tb +Dim Num As Long, MyClasses As Collection +Set MyClasses = New Collection +' ... assume MyClasses has been populated ... + +For Num = 1 To MyClasses.Count + MyClasses.Remove 1 ' Remove the first object each time + ' through the loop until there are +Next Num ' no objects left in the collection. +``` + +To clear a collection in a single call, use the [**Clear**](Clear) method instead. + +### See Also + +- [Add](Add) method +- [Clear](Clear) method +- [Count](Count) property +- [Item](Item) method + +{% include VBA-Attribution.md %} diff --git a/docs/Reference/Modules/Collection/index.md b/docs/Reference/Modules/Collection/index.md new file mode 100644 index 0000000..83f89af --- /dev/null +++ b/docs/Reference/Modules/Collection/index.md @@ -0,0 +1,63 @@ +--- +title: Collection Module +parent: Modules +permalink: /tB/Modules/Collection/ +has_toc: false +--- + +# Collection module + +A **Collection** is an ordered set of items that can be referred to as a unit. The members of a collection do not have to share a data type — any value or object reference is acceptable. Items are accessed by their one-based numeric position in the collection or, if they were added with a key, by that key. + +## Creating, populating, and disposing of a collection + +A collection is created with **New**, populated with [**Add**](Add), and reduced with [**Remove**](Remove) (one item at a time) or [**Clear**](Clear) (every item at once). When the variable referring to the collection goes out of scope, or is set to **Nothing**, the collection — together with any object references it holds — is released. + +```tb +Sub Demo() + Dim Cars As Collection + Set Cars = New Collection + + Cars.Add "Polestar 2", Key:="EV" ' Add with a key. + Cars.Add "Volvo XC40", Key:="ICE" + Cars.Add "Toyota Mirai" ' Add without a key. + + Debug.Print Cars.Count ' 3 + Debug.Print Cars("EV") ' "Polestar 2" — Item is the default member. + Debug.Print Cars(3) ' "Toyota Mirai" — indexes are 1-based. + + Cars.Remove "ICE" ' Remove the Volvo XC40 by key. + Cars.Remove 1 ' Remove the Polestar 2 by index. + + Set Cars = Nothing ' Release the collection. +End Sub +``` + +## Iterating over a collection + +A **Collection** can be iterated with the [**For Each...Next**](../../Core/For-Each-Next) statement, which yields each item in turn in insertion order, regardless of whether the item was added with a key. To iterate over the keys instead, fetch them with [**Keys**](Keys); to take a snapshot of the values as an array (for example, when the collection may be modified during iteration), use [**Items**](Items). + +```tb +Dim Numbers As New Collection +Numbers.Add 10 +Numbers.Add 20 +Numbers.Add 30 + +Dim n As Variant +For Each n In Numbers + Debug.Print n ' Prints 10, then 20, then 30. +Next n +``` + +## Members + +- [Add](Add) -- adds an element to the collection +- [Clear](Clear) -- removes all elements from the collection +- [Count](Count) -- returns the number of elements in the collection +- [Exists](Exists) -- returns whether an element with a specific key exists in the collection +- [Item](Item) -- returns an element from the collection by index or key (default member) +- [Items](Items) -- returns a **Variant** array of all elements in the collection +- [KeyCompareMode](KeyCompareMode) -- returns or sets the text comparison mode used for keys +- [KeyCountHint](KeyCountHint) -- returns or sets a hint for the expected number of keyed items +- [Keys](Keys) -- returns a **String** array of all keys in the collection +- [Remove](Remove) -- removes an element from the collection by index or key diff --git a/docs/Reference/Modules/todo.md b/docs/Reference/Modules/todo.md index c0df7de..cfdde0b 100644 --- a/docs/Reference/Modules/todo.md +++ b/docs/Reference/Modules/todo.md @@ -2,7 +2,6 @@ title: General TODO List for /tB/Modules/ nav_exclude: true redirect_from: - - /tB/Modules/Collection - /tB/Modules/Compilation - /tB/Modules/Constants - /tB/Modules/Conversion