Dictionary Object (VB6)

---

Reference

Microsoft Scripting Runtime (../ SYSTEM32/SCRRUN.DLL)

Description

The Dictionary object is another new feature of VB6 that has found its way into wider use from its humble beginnings in Version 2 of the VBScript scripting runtime. The Dictionary object is similar to a Collection object, except that it's loosely based on the Perl associative array. Like an array or a Collection object, the Dictionary object holds elements, which are called items or members, containing data. A Dictionary object can contain any data whatsoever, including objects and other Dictionary objects. You access the value of these dictionary items by using unique keys (or named values) that are stored along with the data, rather than by using an item's ordinal position, as you do with an array. This makes the Dictionary object ideal when you need to access data that is associated with a particular unique named value.

So if you're happily using Collection objects throughout your VB programs, why should you want to change? Here are some of the advantages afforded by the Dictionary object over a Collection object:

• A Dictionary object returns an array of all its keys using one simple method.

• A Dictionary object returns an array of all its members using one simple method.

• A Dictionary object lets you determine if a given key exists in the Dictionary.

• A Dictionary object gives you the ability to overwrite a member value.

• A Dictionary object lets you change a key value.

If that's not enough to convince you, what about performance? In the performance comparisons I've run, very much to my surprise, the Dictionary object ran about twice as fast as a Collection object when adding and reading back objects. But when adding and reading back simple data types, the Dictionary object was up to three times faster than a Collection object. A clue to the excellent performance of the Dictionary object can be found when you interrogate the Dictionary object in the VB object browser and set the "Show Hidden Members" option.^[2]A new hidden property called HashVal appears. It appears, therefore, that the Dictionary object uses a hash table and some advanced sorting and indexing algorithms to achieve this superior performance.

^[2] To do this, click the right mouse button in either pane of the Object Browser. Then check the Show Hidden Members option on the context menu.

Most of the code written for the Collection object appears to work perfectly well with the Dictionary object, with several notable exceptions:

• You have to resort to some workarounds to use For Each...Next with a Dictionary object. Actually, until recently, it was generally believed that For Each...Next didn't work with the Dictionary object. But in fact, it does. However, rather than the _NewEnum function returning a reference to a member of the Dictionary (as it would with a Collection object), it returns a variant containing the key associated with the member. You then have to pass this key to the Item method to retrieve the member, as the following example shows:

  Private Sub Command1_Click()
  
      Dim vKey As Variant
      Dim sItem As String
      Dim oDict As Dictionary
      
      Set oDict = New Dictionary
          oDict.Add "One", "Engine"
          oDict.Add "Two", "Wheel"
          oDict.Add "Three", "Tire"
          oDict.Add "Four", "Spanner"
          
          For Each vKey In oDict
              sItem = oDict.Item(vKey)
              Debug.Print sItem
          Next
      
      Set oDict = Nothing
      
  End Sub

  
  

  Note that even though the key is always a string, a variant must be used in this situation because the For Each variable must be either a variant or an object.

• You can't directly access a Dictionary object item by its ordinal position in the Dictionary. You can work around this easily by assigning the value returned by the Items method to a variant array and iterating through that by ordinal number. (For an example, see the code fragment for the Dictionary.Items entry.) Even with this extra step, the Dictionary object is significantly faster than a Collection object.

• The syntax of the Dictionary object's Add method is:

  Dictionary.Add( Key, Item)

  
  

  The order of Key and Item are the reverse of that in the Collection object. Furthermore, the Key parameter isn't optional, and the Dictionary object doesn't support parameters to place an item Before or After another item, since the object doesn't support ordered access by any means other than a key value.

Note that the Word object model also includes a Dictionary object of rather a different kind. You can still use Dictionary objects in your Word VBA code, but you have to qualify the object library from which you wish to instantiate the Dictionary class. The following code fragment does that:

Dim objDict as New Scripting.Dictionary

Createable

Yes

Dictionary Object Properties

The Dictionary object includes the following four properties:

CompareMode	Item
Count	Key

Dictionary Object Methods

The Dictionary object supports the following six methods:

Add	Items	Remove
Exists	Keys	RemoveAll