Tools - Dictionary Utilities

cToolsDic - Dictionary Operations

Overview

Provides extended operations for Dictionary objects, including form encoding conversion, nested dictionary operations, dictionary merging, deep copy, etc.

---

Form URL-Encoded Conversion

ToWwwFormUrlencoded

Converts a dictionary to application/x-www-form-urlencoded format string.

Public Function ToWwwFormUrlencoded(Dic As Dictionary) As String

Parameters:

Parameter	Type	Description
Dic	Dictionary	The dictionary to convert

Returns:

URL-encoded format string, such as key1=value1&key2=value2.

Description:

• Simple implementation, directly concatenates key-value pairs
• Currently does not support array-type values

Example:

Dim Dic As New Dictionary
Dic.Add "name", "John"
Dic.Add "age", "25"

Dim FormData As String
FormData = VBMAN.ToolsDic.ToWwwFormUrlencoded(Dic)
Debug.Print FormData  ' Output: name=John&age=25

FromWwwFormUrlencoded

Parses application/x-www-form-urlencoded format string into a dictionary.

Public Function FromWwwFormUrlencoded(Content As String, Dic As Dictionary) As Boolean

Parameters:

Parameter	Type	Description
Content	String	URL-encoded format string
Dic	Dictionary	Dictionary to store results (ByRef)

Returns:

• True - Parsing successful

Example:

Dim Dic As New Dictionary
Dim Success As Boolean

Success = VBMAN.ToolsDic.FromWwwFormUrlencoded("name=John&age=25", Dic)

Debug.Print Dic("name")  ' Output: John
Debug.Print Dic("age")   ' Output: 25

---

Nested Dictionary Operations

TowLevelDicAssign

Two-level nested dictionary assignment helper method.

Public Sub TowLevelDicAssign(Dic As Dictionary, Lv1Name As String, Lv2Name As String, Value As Variant)

Description:

Automatically creates the first-level dictionary (if it doesn't exist), then assigns the value in the second-level dictionary.

Parameters:

Parameter	Type	Description
Dic	Dictionary	Target dictionary
Lv1Name	String	First-level key name
Lv2Name	String	Second-level key name
Value	Variant	Value to assign

Example:

Dim Dic As New Dictionary

' Automatically create "user" sub-dictionary and set "name" value
VBMAN.ToolsDic.TowLevelDicAssign Dic, "user", "name", "John"
VBMAN.ToolsDic.TowLevelDicAssign Dic, "user", "age", 25

' Result: Dic("user")("name") = "John"
'       Dic("user")("age") = 25

Debug.Print Dic("user")("name")  ' Output: John
Debug.Print Dic("user")("age")   ' Output: 25

' Can also operate on deeper dictionaries
VBMAN.ToolsDic.TowLevelDicAssign Dic, "settings", "theme", "dark"
VBMAN.ToolsDic.TowLevelDicAssign Dic, "settings", "lang", "zh-CN"

Debug.Print Dic("settings")("theme")  ' Output: dark

---

Dictionary Merging

OverWrite

Merges source dictionary into target dictionary.

Public Sub OverWrite(DistDic As Dictionary, srcDic As Dictionary, Optional OnlyKey As Boolean = True)

Parameters:

Parameter	Type	Description
DistDic	Dictionary	Target dictionary
srcDic	Dictionary	Source dictionary
OnlyKey	Boolean	Only overwrite existing keys (default True)

Description:

• Supports recursive merging of nested dictionaries
• Object types use recursive merging
• Non-object types are directly assigned

Example:

Dim Target As New Dictionary
Dim Source As New Dictionary

Target.Add "a", "old_a"
Target.Add "b", "old_b"

Source.Add "a", "new_a"
Source.Add "c", "new_c"

' OnlyKey=True: Only overwrite existing keys (a)
VBMAN.ToolsDic.OverWrite Target, Source, True
' Result: Target("a") = "new_a"
'       Target("b") = "old_b"
'       Target("c") = does not exist

' OnlyKey=False: Overwrite all and add new keys
Dim Target2 As New Dictionary
Target2.Add "a", "old_a"
Target2.Add "b", "old_b"

VBMAN.ToolsDic.OverWrite Target2, Source, False
' Result: Target2("a") = "new_a"
'       Target2("b") = "old_b"
'       Target2("c") = "new_c"

' Nested dictionary merge example
Dim NestedTarget As New Dictionary
Dim NestedSource As New Dictionary
Dim UserDic As New Dictionary
Dim SettingsDic As New Dictionary

UserDic.Add "name", "John"
UserDic.Add "age", 20
NestedTarget.Add "user", UserDic

SettingsDic.Add "theme", "light"
NestedSource.Add "user", SettingsDic

VBMAN.ToolsDic.OverWrite NestedTarget, NestedSource, False
' NestedTarget("user") contains name, age, theme

---

Dictionary Copy

DeepCopy

Deep copies a dictionary object.

Public Function DeepCopy(srcDic As Dictionary) As Dictionary

Parameters:

Parameter	Type	Description
srcDic	Dictionary	Source dictionary

Returns:

A new dictionary object containing all key-value pairs from the source dictionary.

Description:

• Currently only implements single-level copy (first-level key-value pairs)
• Object types use Set assignment
• Non-object types use Let assignment
• TODO: Need to change to recursive implementation for deep object assignment

Example:

Dim Original As New Dictionary
Original.Add "name", "John"
Original.Add "age", 25

' Create deep copy
Dim Copy As Dictionary
Set Copy = VBMAN.ToolsDic.DeepCopy(Original)

' Modifying the copy does not affect the original
Copy("name") = "Jane"

Debug.Print Original("name")  ' Output: John
Debug.Print Copy("name")      ' Output: Jane

' Note: For nested dictionaries, currently still shallow copy
Dim Nested As New Dictionary
Dim Inner As New Dictionary
Inner.Add "key", "value"
Nested.Add "inner", Inner

Dim NestedCopy As Dictionary
Set NestedCopy = VBMAN.ToolsDic.DeepCopy(Nested)

' Modifying nested dictionary affects original (because it's a reference)
NestedCopy("inner")("key") = "new_value"
Debug.Print Nested("inner")("key")  ' Output: new_value

---

Complete Example

Private Sub DictionaryDemo()
    ' ===== Form URL-Encoded Operations =====

    Dim Params As New Dictionary
    Params.Add "username", "admin"
    Params.Add "password", "123456"
    Params.Add "remember", "true"

    ' Encode to Form format
    Dim FormData As String
    FormData = VBMAN.ToolsDic.ToWwwFormUrlencoded(Params)
    Debug.Print "Form data: " & FormData

    ' Decode back to dictionary
    Dim Parsed As New Dictionary
    VBMAN.ToolsDic.FromWwwFormUrlencoded FormData, Parsed
    Debug.Print "Username: " & Parsed("username")

    ' ===== Nested Dictionary Operations =====

    Dim Config As New Dictionary

    ' Use TowLevelDicAssign to quickly create nested structure
    VBMAN.ToolsDic.TowLevelDicAssign Config, "database", "host", "localhost"
    VBMAN.ToolsDic.TowLevelDicAssign Config, "database", "port", 3306
    VBMAN.ToolsDic.TowLevelDicAssign Config, "database", "name", "mydb"

    VBMAN.ToolsDic.TowLevelDicAssign Config, "cache", "enabled", True
    VBMAN.ToolsDic.TowLevelDicAssign Config, "cache", "ttl", 3600

    Debug.Print "Database host: " & Config("database")("host")
    Debug.Print "Cache TTL: " & Config("cache")("ttl")

    ' ===== Dictionary Merging =====

    Dim Defaults As New Dictionary
    Defaults.Add "theme", "light"
    Defaults.Add "lang", "en"
    Defaults.Add "notifications", True

    Dim UserSettings As New Dictionary
    UserSettings.Add "theme", "dark"

    ' Merge: User settings override defaults
    VBMAN.ToolsDic.OverWrite Defaults, UserSettings, False

    Debug.Print "Theme: " & Defaults("theme")        ' dark (user setting)
    Debug.Print "Language: " & Defaults("lang")         ' en (default)
    Debug.Print "Notifications: " & Defaults("notifications") ' True (default)

    ' ===== Deep Copy =====

    Dim Original As New Dictionary
    Original.Add "key1", "value1"
    Original.Add "key2", 12345

    Dim Cloned As Dictionary
    Set Cloned = VBMAN.ToolsDic.DeepCopy(Original)

    ' Verify it's an independent copy
    Cloned("key1") = "modified"
    Debug.Print "Original: " & Original("key1")  ' value1
    Debug.Print "Cloned: " & Cloned("key1")      ' modified
End Sub

---

Method Comparison Table

Method	Purpose	Complexity
ToWwwFormUrlencoded	Dictionary to query string	O(n)
FromWwwFormUrlencoded	Query string to dictionary	O(n)
TowLevelDicAssign	Two-level nested assignment	O(1)
OverWrite	Dictionary merging	O(n)
DeepCopy	Dictionary deep copy	O(n)