Dictionary Object

Object that stores data key, item pairs.

A Dictionary object is the equivalent of a PERL associative array. Items can be any form of data, and are stored in the array. Each item is associated with a unique key. The key is used to retrieve an individual item and is usually an integer or a string, but can be anything except an array.
The following code illustrates how to create a Dictionary object:

Dim d   ' Create a variable.
Set d = CreateObject("Scripting.Dictionary")
d.Add "a", "Athens"   ' Add some keys and items.
d.Add "b", "Belgrade"
d.Add "c", "Cairo"
...

Add Method (Script Runtime):

Adds a key and item pair to a Dictionary object.

object.Add (key, item)

object

    Required. Always the name of a Dictionary object.
key

    Required. The key associated with the item being added.
item

    Required. The item associated with the key being added.

An error occurs if the key already exists.

The following example illustrates the use of the Add method. 

Dim d   ' Create a variable.
Set d = CreateObject("Scripting.Dictionary")
d.Add "a", "Athens"   ' Add some keys and items.
d.Add "b", "Belgrade"
d.Add "c", "Cairo" 

Exists Method (Script Runtime):

Returns true if a specified key exists in the Dictionary object, false if it does not.

  object
                      .Exists(
                      key
                      ) 

Object

    Required. Always the name of a Dictionary object.

Key

    Required. Key value being searched for in the Dictionary object.

The following example illustrates the use of the Exists method. 

Function KeyExists(k)
    Dim d, msg
    Set d = CreateObject("Scripting.Dictionary")
    d.Add "a", "Athens"
    d.Add "b", "Belgrade"
    d.Add "c", "Cairo"
    If d.Exists(k) Then
        msg = "Specified key exists."
    Else
        msg = "Specified key does not exist."
    End If
    KeyExists = msg
End Function

Items Method:

Returns an array containing all the items in a Dictionary object.

object.Items( ) 

The object is always the name of a Dictionary object.

The following code illustrates use of the Items method: 


Function DicDemo
   Dim a, d, i, s   ' Create some variables.
   Set d = CreateObject("Scripting.Dictionary")
   d.Add "a", "Athens"   ' Add some keys and items.
   d.Add "b", "Belgrade"
   d.Add "c", "Cairo"
   a = d.Items   ' Get the items.
   For i = 0 To d.Count -1 ' Iterate the array.
      s = s & a(i) & "
" ' Create return string.
   Next
   DicDemo = s
End Function

Keys Method:

Returns an array containing all existing keys in a Dictionary object.

 object.Keys( ) 

The object is always the name of a Dictionary object.

The following code illustrates use of the Keys method: 

Function DicDemo
   Dim a, d, i   ' Create some variables.
   Set d = CreateObject("Scripting.Dictionary")
   d.Add "a", "Athens"   ' Add some keys and items.
   d.Add "b", "Belgrade"
   d.Add "c", "Cairo"
   a = d.Keys   ' Get the keys.
   For i = 0 To d.Count -1 ' Iterate the array.
      s = s & a(i) & "
" ' Return results.
   Next
   DicDemo = s
End Function

Remove Method (Script Runtime):

Removes a key, item pair from a Dictionary object.

      object
                      .Remove(
                      key
                      )
                    
object

    Required. Always the name of a Dictionary object.
key

    Required. Key associated with the key, item pair you want to remove from the Dictionary object.

An error occurs if the specified key, item pair does not exist.

The following code illustrates use of the Remove method:

Dim a, d   ' Create some variables.
Set d = CreateObject("Scripting.Dictionary")
d.Add "a", "Athens"   ' Add some keys and items.
d.Add "b", "Belgrade"
d.Add "c", "Cairo"
...
d.Remove("b")   ' Remove second pair.

RemoveAll Method:

The RemoveAll method removes all key, item pairs from a Dictionary object.

object.RemoveAll( ) 

The object is always the name of a Dictionary object.

The following code illustrates use of the RemoveAll method: 

Dim a, d, i   ' Create some variables.
Set d = CreateObject("Scripting.Dictionary")
d.Add "a", "Athens"   ' Add some keys and items.
d.Add "b", "Belgrade"
d.Add "c", "Cairo"
...
a = d.RemoveAll   ' Clear the dictionary.

Count Property (Script Runtime):

Returns the number of items in a collection or Dictionary object. Read-only.

                      object
                      .Count 

The object is always the name of one of the items in the Applies To list.

The following code illustrates use of the Count property: 


Function ShowKeys
   Dim a, d, i, s   ' Create some variables.
   Set d = CreateObject("Scripting.Dictionary")
   d.Add "a", "Athens"   ' Add some keys and items.
   d.Add "b", "Belgrade"
   d.Add "c", "Cairo"
   a = d.Keys   ' Get the keys.
   For i = 0 To d.Count -1 ' Iterate the array.
      s = s & a(i) & "
" ' Create return string.
   Next
   ShowKeys = s
End Function

Item Property (Script Runtime):

Sets or returns an item for a specified key in a Dictionary object. For collections, returns an item based on the specified key. Read/write. 

object.Item(key)[ = newitem]

object

    Required. Always the name of a collection or Dictionary object.
key

    Required. Key associated with the item being retrieved or added.
newitem

    Optional. Used for Dictionary object only; no application for collections. If provided, newitem is the new value associated with the specified key.

If key is not found when changing an item, a new key is created with the specified newitem. If key is not found when attempting to return an existing item, a new key is created and its corresponding item is left empty.

The following example illustrates the use of the Item property. 

Function ItemDemo
   Dim d   ' Create some variables.
   Set d = CreateObject("Scripting.Dictionary")
   d.Add "a", "Athens"   ' Add some keys and items.
   d.Add "b", "Belgrade"
   d.Add "c", "Cairo"
   ItemDemo = d.Item("c")   ' Get the item.
End Function

Key Property:

Sets a key in a Dictionary object.

object.Key(key) = newkey

object

    Required. Always the name of a Dictionary object.
key

    Required. Key value being changed.
newkey

    Required. New value that replaces the specified key.

If key is not found when changing a key, a new key is created and its associated item is left empty.

The following example illustrates the use of the Key property:

Function DicDemo
   Dim d   ' Create some variables.
   Set d = CreateObject("Scripting.Dictionary")
   d.Add "a", "Athens"   ' Add some keys and items.
   d.Add "b", "Belgrade"
   d.Add "c", "Cairo"
   d.Key("c") = "d"   ' Set key for "c" to "d".
   DicDemo = d.Item("d")   ' Return associate item.
End Function

CompareMode Property:

Sets and returns the comparison mode for comparing string keys in a Dictionary object.

object
                      .CompareMode[ = compare]

object

    Required. Always the name of a Dictionary object.
compare

    Optional. If provided, compare is a value representing the comparison mode. Acceptable values are 0 (Binary), 1 (Text), 2 (Database). Values greater than 2 can be used to refer to comparisons using specific Locale IDs (LCID).

An error occurs if you try to change the comparison mode of a Dictionary object that already contains data.

The following example illustrates the use of the CompareMode property: 

Dim d
Set d = CreateObject("Scripting.Dictionary")

d.CompareMode = vbTextCompare
d.Add "a", "Athens"   ' Add some keys and items.
d.Add "b", "Belgrade"
d.Add "c", "Cairo"
' An error occurs on the next line because the key already exists.
' The comparison mode is Text, so the keys are case-insensitive.
d.Add "B", "Baltimore"