Section 9.9. Dictionaries

9.9. Dictionaries

A dictionary is a collection that associates a key to a value. A language dictionary, such as Webster's, associates a word (the key) with its definition (the value).

To see the value of dictionaries, start by imagining that you want to keep a list of the state capitals. One approach might be to put them in an array:

string[] stateCapitals = new string[50];

The stateCapitals array will hold 50 state capitals. Each capital is accessed as an offset into the array. For example, to access the capital for Arkansas, you need to know that Arkansas is the fourth state in alphabetical order:

string capitalOfArkansas = stateCapitals[3];

It is inconvenient, however, to access state capitals using array notation. After all, if I need the capital for Massachusetts, there is no easy way for me to determine that Massachusetts is the 21st state alphabetically.

It would be far more convenient to store the capital with the state name. A dictionary allows you to store a value (in this case, the capital) with a key (in this case, the name of the state).

A .NET Framework dictionary can associate any kind of key (string, integer, object, etc.) with any kind of value (string, integer, object, etc.). Typically, of course, the key is fairly short, the value fairly complex.

The most important attributes of a good dictionary are that it is easy to add and quick to retrieve values (see Table 9-6).

Table 9-6. Dictionary methods and properties

Method or property	Purpose
Count	Public property that gets the number of elements in the Dictionary.
Item( )	The indexer for the Dictionary.
Keys	Public property that gets a collection containing the keys in the Dictionary (see also Values).
Values	Public property that gets a collection containing the values in the Dictionary (see also Keys).
Add( )	Adds an entry with a specified Key and Value.
Clear( )	Removes all objects from the Dictionary.
ContainsKey()	Determines whether the Dictionary has a specified key.
ContainsValue( )	Determines whether the Dictionary has a specified value.
GetEnumerator( )	Returns an enumerator for the Dictionary.
GetObjectData()	Implements ISerializable and returns the data needed to serialize the Dictionary.
Remove( )	Removes the entry with the specified Key.

The key in a Dictionary can be a primitive type, or it can be an instance of a user-defined type (an object). Objects used as keys for a Dictionary must implement GetHashCode() as well as Equals. In most cases, you can simply use the inherited implementation from Object.

9.9.1. IDictionary<K,V>

Dictionaries implement the IDictionary<K,V> interface (where K is the key type and V is the value type). IDictionary provides a public property Item. The Item property retrieves a value with the specified key. In C#, the declaration for the Item property is:

V[K key] {get; set;}

The Item property is implemented in C# with the index operator ([]). Thus, you access items in any Dictionary object using the offset syntax, as you would with an array.

Example 9-18 demonstrates adding items to a Dictionary and then retrieving them with the Item property.

Example 9-18. The Item property as offset operators

namespace Dictionary {    public class Tester    {       static void Main( )       {          // Create and initialize a new Dictionary.          Dictionary<string,string> Dictionary =             new Dictionary<string,string>( );          Dictionary.Add("000440312", "Jesse Liberty");          Dictionary.Add("000123933", "Stacey Liberty");          Dictionary.Add("000145938", "John Galt");          Dictionary.Add("000773394", "Ayn Rand");          // access a particular item          Console.WriteLine("myDictionary[\"000145938\"]: {0}",             Dictionary["000145938"]);       }    } } Output: Dictionary["000145938"]: John Galt

Example 9-18 begins by instantiating a new Dictionary. The type of the key and of the value is declared to be string.

Add four key/value pairs. In this example, the Social Security number is tied to the person's full name. (Note that the Social Security numbers here are intentionally bogus.)

Once the items are added, you access a specific entry in the dictionary using the Social Security number as key.

If you use a reference type as a key, and the type is mutable (strings are immutable), you must not change the value of the key object once you are using it in a dictionary.

If, for example, you use the Employee object as a key, changing the employee ID creates problems if that property is used by the Equals or GetHashCode methods because the dictionary consults these methods.