Document the Collection class and module.

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}

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 %}