Introduction to Dictionaries

Description

In some cases, in addition to these two rules, the items should - in some cases must - be ordered. To order the items, the keys are used. Because in most cases a dictionary is made of words, the keys are ordered in alphabetical order. A dictionary can also be made of items whose keys are date values. In this case, the items would be ordered in chronological order.

There are various kinds of dictionary types of list used in daily life. The word "dictionary" here does not imply the traditional dictionary that holds the words and their meanings in the English language. The concept is applied in various scenarios.

To support dictionary-based lists, the .NET Framework provides various interfaces and classes. The interfaces allow you to create your own dictionary type of collection class. The classes allow you to directly create a dictionary-based list with an already built-in functionality. The NET Framework provides support for dictionary-based collections through two classes: Hashtable and SortedList. Both classes implement:

• The IDictionary: This makes it possible to use the DictionaryEntry class to access a key/value item
• The ICollection: This makes it possible to know the number of items in the list
• The IEnumerable: This makes it possible to use the foreach loop to enumerate the members of the list
• And the ICloneable interfaces.

The Hashtable class implements the ISerializable interface, which makes it possible for the list to be serialized. Still, the SortedList class is marked with the Serializable attribute, which makes it possible to file process its list.

The .NET Framework also provides dictionary-types through generic classes. From the System.Collections.Generic namespace, to create a dictionary type of collection, you can use either the Dictionary, the SortedDictionary, or the SortedList class. The System.Collections.Generic.Dictionary class is equivalent to the System.Collections.Hashtable class. The System.Collections.Generic.SortedList class is equivalent to the System.Collections.SortedList class. The System.Collections.Generic.SortedDictionary class is equivalent to the System.Collections.Generic.SortedList class with some differences in the way both classes deal with memory management.

If you decide to use either the System.Collections.Generic.Dictionary or the System.Collections.Generic.SortedList class, when declaring the variable, you must remember to specify the name of the class whose collection is being created.

Before using a dictionary-type of list, you can declare a variable using one of the constructors of the class. Here is an example:

Public Class Exercise

    Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Dim Students As Hashtable = new Hashtable
    End Sub
End Class

In this case, the primary list would be empty.

To add an item to the list, you can call the Add() method. The syntax of the System.Collections.Hashtable.Add() and the System.Collections.SortedList.Add() methods is:

Public Overridable Sub Add(key As Object, value As Object)

The syntax of the System.Collections.Generic.Dictionary.Add(), the System.Collections.Generic.SortedDictionary.Add(), and the System.Collections.Generic.SortedList.Add() method is:

Public Sub Add(key As TKey, value As TValue)

As you can see, you must provide the key and the value as the first and second arguments to the method respectively. Here are examples of calling the Add() method:

Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Dim Students As Hashtable = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
End Sub

When calling the Add() method, you must provide a valid Key argument: it cannot be Nothing. For example, the following code would produce an error:

Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Dim Students As Hashtable = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
        Students.Add(Nothing, "Hannovers")
End Sub

This would produce:

When adding the items to the list, as mentioned in our introduction, each key must be unique: you cannot have two exact keys. If you try adding a key that exists already in the list, the compiler would throw an ArgumentException exception. Based on this, the following code would not work because, on the third call, a "Patrick" key exists already:

Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Dim Students As Hashtable = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
        Students.Add("Chrissie", "Hannovers")
        Students.Add("Patrick", "Herzog")
End Sub

This would produce:

This means that, when creating a dictionary type of list, you must define a scheme that would make sure that each key is unique among the other keys in the list.

Besides the Add() method, you can use the Item property to add an item to the collection. To do this, enter the Key in the parentheses of the property and assign it the desired Value. Here is an example:

Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Dim Students As Hashtable = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
        Students.Add("Chrissie", "Hannovers")
        Students.Add("Patricia", "Herzog")
        Students("Michael") = "Herlander"
End Sub

Although, or because, the key and value are distinct, to consider their combination as a single object, if you are using either the System.Collections.Hasthtable or the System.Collections.SortedList class, the .NET Framework provides the DictionaryEntry structure. To access an item, you can use the foreach loop to visit each item.

To support the foreach loop, the System.Collections.Hashtable and the System.Collections.SortedList classes implement the IEnumerable.GetEnumerator() method. In this case, the item is of type DictionaryEntry: it contains a Key and a Value in combination.

The DictionaryEntry structure contains two properties named Key and Value to identify the components of a combination. Here is an example:

Private Sub Exercise_Load(ByVal sender As System.Object, _
                          ByVal e As System.EventArgs) _
                          Handles MyBase.Load
        Dim Students As Hashtable = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
        Students.Add("Chrissie", "Hannovers")
        Students.Add("Patricia", "Herzog")
        Students("Michael") = "Herlander"

        For Each Entry As DictionaryEntry In Students
            lbxStudents.Items.Add(Entry.Key & " " & Entry.Value)
        Next
End Sub

This would produce:

If you are using a generic class, the .NET Framework provides the KeyValuePair structure that follows the same functionality as the System.Collections.DictionaryEntry structure, except that you must apply the rules of generic classes.

If you use the System.Collections.Hashtable or the System.Collections.Generic.Dictionary class to create your list, the items are cumulatively added to the collection every time you call the Add() method or when you use the Item property to add an item. In our introduction, we saw that the optional third rule of a dictionary type of list is that the list be sorted based on the key. To spare you the hassle of manually taking care of this, the alternative is to use the SortedList class.

Whenever a new item is added to a System.Collections.SortedList variable, a System.Collections.Generic.SortedDictionary variable, or a System.Collections.Generic.SortedList variable, the list is rearranged so the collection can be sorted in either alphabetical or chronological order based on the keys. This means that, if you want your list to be logically arranged by the keys, use one of these Sorted classes to create the collection.

After adding one or more items to the list, they are stored in two collections. The keys are stored in a collection represented by a property named Keys. The values are stored in the Values property. In the System.Collections classes, the Keys and the Values properties are of type ICollection.

To assist you with managing the keys of their collections, the System.Collections.Generic.Dictionary, the System.Collections.Generic.SortedDictionary, and the System.Collections.Generic.SortedList classes are equipped with a nested class named KeyCollection. KeyCollection is a serializable generic class that implements the ICollection interface. The only real functionalities of the nested KeyCollection class are its ability to know the current number of items in the list and the ability to enumerate the members of the collection through a For Each loop.

To assist you with the values of their lists, the System.Collections.Generic.Dictionary, the System.Collections.Generic.SortedDictionary, and the System.Collections.Generic.SortedList classes are equipped with the nested ValueCollection. The ValueCollection serializable class implements the ICollection and the IEnumerable interfaces. The functionality of the ValueCollection class is the same as its counterpart of the System.Collections namespace.

Locating an item in a dictionary type of list consists of looking for either a key, a value, or a combination of Key=Value. The Hashtable, the Dictionary, and the SortedList classes are equipped to handle these operations with little effort on your part. If you know the key of an item but want to find a value, you can use the Item property because it produces it. Here is an example:

Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Dim Students As Hashtable = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
        Students.Add("Chrissie", "Hannovers")
        Students.Add("Patricia", "Herzog")
        Students("Michael") = "Herlander"

        For Each Entry As DictionaryEntry In Students
            lbxStudents.Items.Add(Entry.Key & " " & Entry.Value)
        Next

        Dim Value As String = CType(Students("Chrissie"), String)
        MsgBox("The value of the Chrissie key is " & Value)
End Sub

This would produce:

To find out whether a Key/Value item exists in the list, if you are using one of the classes from the System.Collections namespace, you can call the System.Collections.Hashtable.Contains() or the System.Collections.SortedList.Contains() method. Its syntax is:

Public Overridable Function Contains(key As Object) As Boolean

To look for an item, you pass its key as argument to this method. Here is an example:

Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Dim Students As Hashtable = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
        Students.Add("Chrissie", "Hannovers")
        Students.Add("Patricia", "Herzog")
        Students("Michael") = "Herlander"

        For Each Entry As DictionaryEntry In Students
            lbxStudents.Items.Add(Entry.Key & " " & Entry.Value)
        Next

        Dim Found As Boolean = Students.Contains("Chrissie")

        If Found = True Then
            MsgBox("The list contains an item " & _
                            "whose key is Chrissie")
        Else
            MsgBox("The list doesn't contain an " & _
                            "item whose key is Chrissie")
        End If

        Found = Students.Contains("James")

        If Found = True Then
            MsgBox("The list contains an item " & _
                        "whose key is James")
        Else
            MsgBox("The list doesn't contain an " & _
                        "item whose key is James")
        End If
End Sub

This would produce:

We have seen that the System.Collections.Hashtable.Contains() and the System.Collections.SortedList.Contains() methods allow you to find out whether a collection contains a certain specific key. An alternative is to call a method named ContainsKey.

The syntax of the System.Collections.Hashtable.ContainsKey() and the System.Collections.SortedList.ContainsKey() method is:

Public Overridable Function ContainsKey(key As Object) As Boolean

The syntax of the System.Collections.Generic.Dictionary.ContainsKey() and the System.Collections.Generic.SortedList.ContainsKey() method is:

Public Function ContainsKey(key As TKey) As Boolean

To find out whether a particular value exists in the list, you can call the ContainsValue() method. The syntax of the System.Collections.Hashtable.ContainsValue() and the System.Collections.SortedList.ContainsValue() method is::

Public Overridable Function ContainsValue(value As Object) As Boolean

The syntax of the System.Collections.Generic.Dictionary.ContainsValue() and the System.Collections.Generic.SortedList.ContainsValue() method is:

Public Function ContainsValue(value As TValue) As Boolean

The ContainsKey() method allows you to only find out whether a dictionary-based collection contains a certain key. It does not identify that key and it does not give any significant information about that key, except its existence. In some operations, first you may want to find out if the collection contains a certain key. Second, if that key exists, you may want to get its corresponding value.

To assist you with both checking the existence of a key and getting its corresponding value, the generic Dictionary, SortedDictionary, and SortedList classes are equipped with a method named TryGetValue. Its syntax is:

Public Function TryGetValue(key As TKey, _
	<OutAttribute> ByRef value As TValue) As Boolean

When calling this method, the first argument must be the key to look for. If that key is found, the method returns its corresponding value as the second argument passed by reference.

To delete one item from the list, you can call the Remove() method. Its syntax is:

Public Overridable Sub Remove(key As Object)

Here is an example:

Public Class Exercise
    Private Students As Hashtable

    Private Sub Exercise_Load(ByVal sender As System.Object, _
                              ByVal e As System.EventArgs) _
                              Handles MyBase.Load
        Students = New Hashtable

        Students.Add("Hermine", "Tolston")
        Students.Add("Patrick", "Donley")
        Students.Add("Chrissie", "Hannovers")
        Students.Add("Patricia", "Herzog")
        Students("Michael") = "Herlander"
        Students("Philemon") = "Jacobs"
        Students("Antoinette") = "Malhoun"

        For Each Entry As DictionaryEntry In Students
            lbxStudents.Items.Add(Entry.Key & " " & Entry.Value)
        Next
    End Sub

    Private Sub btnDelete_Click(ByVal sender As System.Object, _
                                ByVal e As System.EventArgs) _
                                Handles btnDelete.Click
        Students.Remove("Chrissie")

        lbxStudents.Items.Clear()

        For Each Entry As DictionaryEntry In Students
            lbxStudents.Items.Add(Entry.Key & " " & Entry.Value)
        Next
    End Sub
End Class

This would produce:

To delete all items from the list, you can call the Clear() method. Its syntax is:

Public Overridable Sub Clear