Microsoft Office 2000/Visual Basic Programmer's Guide

The Dictionary Object

The Dictionary object is a data structure that can contain sets of pairs, where each pair consists of an item, which can be any data type, and a key, which is a unique String value that identifies the item. The Dictionary object is similar in some ways to the VBA Collection object; however, the Dictionary object offers certain features that the Collection object lacks, including:

• The Exists method. You can use this method to determine whether a particular key, and its corresponding item, exist in a Dictionary object. The Exists method makes it simpler and more efficient to search a Dictionary object than to search a Collection object.
  
  
• The CompareMode property. Setting this property specifies the text-comparison mode for the Dictionary object, so that you can search for a key in either a case-sensitive or case-insensitive manner. By default, it's set to BinaryCompare, which means that the Exists method will return True only if it finds a binary match. There's no way to specify a text-comparison mode for a key that retrieves an item from a Collection object.
  
  
• The Key property. This property enables you to return the key for a particular item in the dictionary. An item in a Collection object also has a key, which you can use to retrieve that item; however, there's no way to retrieve the key itself.
  
  
• The RemoveAll method. This method removes all items in the Dictionary object. A Collection object, on the other hand, has no method for removing all items at once, although setting the Collection object to Nothing has the same effect.

The primary advantage of the Dictionary object over the Collection object is the fact that it's easier to search a Dictionary object for a given item. Despite this advantage, the Dictionary object does not entirely replace the Collection object. The Collection object is useful in some situations where the Dictionary object is not. For example, if you're creating a custom object model, you can use a Collection object to store a reference to a custom collection, but you can't use a Dictionary object to do this. For more information about creating custom object models, see Chapter 9, "Custom Classes and Objects."

The modDictionary module, which is available in the VBA.mdb sample file in the Samples\CH07 subfolder on the companion CD-ROM, contains code examples that compare the Dictionary and Collection objects. The GetFiles procedure and TestGetFiles procedure in "Returning Files from the File System" earlier in this chapter also demonstrate uses of the Dictionary object. For information about searching a dictionary for an item, see "Searching a Dictionary" later in this chapter.

For more information about the Dictionary object, see the VBScript documentation on the Microsoft Scripting Technologies Web site at http://msdn.microsoft.com/scripting/default.htm.