cCollection Methods Reference

📋 Method List

Method	Description
Add	Add element (auto-overwrite duplicate Key)
Remove	Remove element (by Key or Index)
RemoveAll	Clear all elements
Update	Update existing element
Exists	Check if Key exists
Count	Get element count
KeyByIndex	Get Key by Index
Keys	Get all Key array
Items	Get all Value array
RenameKey	Rename a Key
SortByKey	Sort collection by Key
SortByValue	Sort collection by Value
GetSortedKeys	Get sorted Key array (without modifying collection)
GetSortedValuesByKey	Get sorted Value array (without modifying collection)

---

➕ Add Method

Description

Adds an element to the collection. If a Key is provided and already exists, the old element is automatically removed before adding the new one (overwrite update).

Syntax

Public Sub Add(ByVal Item As Variant, Optional ByVal Key As String = "")

Parameters

Parameter	Type	Description
Item	Variant	Element to add (can be any type)
Key	String	Optional, key name for the element

Example

Dim col As New cCollection

' Add element without Key
col.Add "Plain element"

' Add string with Key
col.Add "John", "user1"

' Add number
col.Add 100, "count"

' Add object
Dim obj As New MyClass
col.Add obj, "myObject"

' Overwrite existing Key (auto remove old value)
col.Add "John-Updated", "user1"  ' Auto overwrite

---

➖ Remove Method

Description

Removes a specified element (by Key or Index).

Syntax

Public Sub Remove(ByVal KeyOrIndex As Variant)

Parameters

Parameter	Type	Description
KeyOrIndex	Variant	Key (string) or Index (number, starts from 1)

Example

' Remove by Key
col.Remove "user1"

' Remove by Index (remove first element)
col.Remove 1

---

🧹 RemoveAll Method

Description

Clears the collection, removing all elements.

Syntax

Public Sub RemoveAll()

Example

' Clear the collection
col.RemoveAll
Debug.Print col.Count  ' Output: 0

---

🔄 Update Method

Description

Updates an existing element. Returns False if Key does not exist.

Syntax

Public Function Update(ByVal Item As Variant, ByVal Key As String) As Boolean

Parameters

Parameter	Type	Description
Item	Variant	New element value
Key	String	Key to update

Return Value

Boolean - Returns True on success, False if Key doesn't exist

Example

' Update existing element
If col.Update("New value", "user1") Then
    Debug.Print "Update successful"
Else
    Debug.Print "Key not found"
End If

---

🔍 Exists Method

Description

Checks if the specified Key exists in the collection.

Syntax

Public Function Exists(ByVal Key As String, Optional CompareCase As Boolean) As Boolean

Parameters

Parameter	Type	Description
Key	String	Key to check
CompareCase	Boolean	Optional, case-sensitive comparison (default False)

Example

' Default case-insensitive
col.Add "Value", "Key"
Debug.Print col.Exists("key")      ' True
Debug.Print col.Exists("KEY")      ' True

' Case-sensitive
col.Add "Value", "Key"
Debug.Print col.Exists("key", True)   ' False
Debug.Print col.Exists("Key", True)   ' True

---

🔢 Count Method

Description

Gets the number of elements in the collection.

Syntax

Public Function Count() As Long

Example

Debug.Print "Element count: " & col.Count

' Check if empty
If col.Count = 0 Then
    Debug.Print "Collection is empty"
End If

---

🔑 KeyByIndex Method

Description

Gets the Key corresponding to an index. Returns empty string if index is invalid or element has no Key.

Syntax

Public Function KeyByIndex(ByVal Index As Long) As String

Parameters

Parameter	Type	Description
Index	Long	Index (starts from 1)

Example

' Get Key of first element
Dim key As String
key = col.KeyByIndex(1)
If key <> "" Then
    Debug.Print "Key of first element: " & key
End If

---

📋 Keys Method

Description

Gets a string array containing all Keys. Elements without Key correspond to empty string.

Syntax

Public Function Keys() As String()

Return Value

String() - Key array (0-based)

Example

Dim keyArray() As String
keyArray = col.Keys()

Dim i As Long
For i = LBound(keyArray) To UBound(keyArray)
    Debug.Print "Key[" & i & "] = " & keyArray(i)
Next i

---

📦 Items Method

Description

Gets a Variant array containing all Values.

Syntax

Public Function Items() As Variant()

Return Value

Variant() - Value array (0-based)

Example

Dim itemArray() As Variant
itemArray = col.Items()

Dim i As Long
For i = LBound(itemArray) To UBound(itemArray)
    Debug.Print "Value[" & i & "] = " & itemArray(i)
Next i

---

✏️ RenameKey Method

Description

Renames a specified Key (Dictionary-compatible method).

Syntax

Public Function RenameKey(ByVal OldKey As String, ByVal NewKey As String) As Boolean

Parameters

Parameter	Type	Description
OldKey	String	Original Key name
NewKey	String	New Key name

Return Value

Boolean - Returns True on success, False on failure (original Key doesn't exist or new Key already exists)

Example

' Rename Key
If col.RenameKey("oldName", "newName") Then
    Debug.Print "Rename successful"
Else
    Debug.Print "Rename failed (Key not found or new Key already exists)"
End If

---

🔤 SortByKey Method

Description

Sorts the entire collection in ascending alphabetical order by Key (reorganizes collection order).

Syntax

Public Sub SortByKey()

Example

' Add elements (unordered)
col.Add "Value-C", "Key-C"
col.Add "Value-A", "Key-A"
col.Add "Value-B", "Key-B"

' Sort by Key
col.SortByKey

' Now iteration will be in order: Key-A, Key-B, Key-C
Dim key As Variant
For Each key In col.Keys()
    Debug.Print key
Next

---

🔠 SortByValue Method

Description

Sorts the entire collection in ascending alphabetical order by Value (Value should be string type).

Syntax

Public Sub SortByValue()

Example

' Add elements
col.Add "Charlie", "C"
col.Add "Alpha", "A"
col.Add "Bravo", "B"

' Sort by Value
col.SortByValue

' Now order is: Alpha, Bravo, Charlie

---

📊 GetSortedKeys Method

Description

Gets a Key array sorted by Key (does not modify the original collection).

Syntax

Public Function GetSortedKeys() As String()

Return Value

String() - Sorted Key array

Example

' Get sorted Keys (without changing original collection order)
Dim sortedKeys() As String
sortedKeys = col.GetSortedKeys()

' Iterate using sorted Keys
Dim i As Long
For i = LBound(sortedKeys) To UBound(sortedKeys)
    Debug.Print sortedKeys(i) & " = " & col(sortedKeys(i))
Next i

---

📈 GetSortedValuesByKey Method

Description

Gets a Value array sorted by Key (does not modify the original collection).

Syntax

Public Function GetSortedValuesByKey() As Variant()

Return Value

Variant() - Value array sorted by Key

Example

' Get Values sorted by Key
Dim sortedValues() As Variant
sortedValues = col.GetSortedValuesByKey()

Dim i As Long
For i = LBound(sortedValues) To UBound(sortedValues)
    Debug.Print "Value[" & i & "] = " & sortedValues(i)
Next i

---

📌 Method Usage Scenarios Summary

Basic CRUD Operations

Dim col As New cCollection

' Add
col.Add "Value", "Key"

' Check existence
If col.Exists("Key") Then
    ' Update
    col.Update "NewValue", "Key"
End If

' Delete
col.Remove "Key"

Batch Operations

' Clear
col.RemoveAll

' Get all Keys and Values
Dim keys() As String
Dim values() As Variant
keys = col.Keys()
values = col.Items()

Sorting Scenarios

' Need sorted iteration without modifying original collection
Dim sortedKeys() As String
sortedKeys = col.GetSortedKeys()

Dim i As Long
For i = LBound(sortedKeys) To UBound(sortedKeys)
    ProcessItem sortedKeys(i), col(sortedKeys(i))
Next i

' Directly sort collection (subsequent iterations are sorted)
col.SortByKey

---

Last Updated: 2026-05-17