IDictionary Interface

Microsoft Silverlight will reach end of support after October 2021. Learn more.

Represents a nongeneric collection of key/value pairs.

Namespace:  System.Collections
Assembly:  mscorlib (in mscorlib.dll)

Syntax

'Declaration
<ComVisibleAttribute(True)> _
<DefaultMemberAttribute("Item")> _
Public Interface IDictionary _
    Inherits ICollection, IEnumerable

[ComVisibleAttribute(true)]
[DefaultMemberAttribute("Item")]
public interface IDictionary : ICollection, 
    IEnumerable

The IDictionary type exposes the following members.

Properties

	Name	Description
	Count	Gets the number of elements contained in the ICollection. (Inherited from ICollection.)
	IsFixedSize	Gets a value indicating whether the IDictionary object has a fixed size.
	IsReadOnly	Gets a value indicating whether the IDictionary object is read-only.
	IsSynchronized	Gets a value indicating whether access to the ICollection is synchronized (thread safe). (Inherited from ICollection.)
	Item	Gets or sets the element with the specified key.
	Keys	Gets an ICollection object containing the keys of the IDictionary object.
	SyncRoot	Gets an object that can be used to synchronize access to the ICollection. (Inherited from ICollection.)
	Values	Gets an ICollection object containing the values in the IDictionary object.

Top

Methods

	Name	Description
	Add	Adds an element with the provided key and value to the IDictionary object.
	Clear	Removes all elements from the IDictionary object.
	Contains	Determines whether the IDictionary object contains an element with the specified key.
	CopyTo	Copies the elements of the ICollection to an Array, starting at a particular Array index. (Inherited from ICollection.)
	GetEnumerator()	Returns an IDictionaryEnumerator object for the IDictionary object.
	GetEnumerator()	Returns an enumerator that iterates through a collection. (Inherited from IEnumerable.)
	Remove	Removes the element with the specified key from the IDictionary object.

Top

Extension Methods

	Name	Description
	AsQueryable	Converts an IEnumerable to an IQueryable. (Defined by Queryable.)
	Cast<TResult>	Converts the elements of an IEnumerable to the specified type. (Defined by Enumerable.)
	OfType<TResult>	Filters the elements of an IEnumerable based on a specified type. (Defined by Enumerable.)

Top

Remarks

The IDictionary interface is the base interface for nongeneric collections of key/value pairs. For the generic version of this interface, see System.Collections.Generic.IDictionary<TKey, TValue>.

Each element is a key/value pair stored in a DictionaryEntry object.

Each pair must have a unique key. Implementations can vary in whether they allow the key to be nulla null reference (Nothing in Visual Basic). The value can be nulla null reference (Nothing in Visual Basic) and does not have to be unique. The IDictionary interface allows the contained keys and values to be enumerated, but it does not imply any particular sort order.

IDictionary implementations fall into three categories: read-only, fixed-size, variable-size. A read-only IDictionary object cannot be modified. A fixed-size IDictionary object does not allow the addition or removal of elements, but does allow the modification of existing elements. A variable-size IDictionary object allows the addition, removal, and modification of elements.

The foreach statement of the C# language (for each in Visual Basic) requires the type of each element in the collection. Since each element of the IDictionary object is a key/value pair, the element type is not the type of the key or the type of the value. Instead, the element type is DictionaryEntry. For example:

foreach (DictionaryEntry de in CastMembers) {...}

For Each de As DictionaryEntry In CastMembers
  ...
Next myDE

The foreach statement is a wrapper around the enumerator, which allows only reading from but not writing to the collection.

Notes to Implementers

The implementing class must have a means to compare keys.

Examples

The following code example demonstrates how to define a simple dictionary class that implements the IDictionary interface.

Note:
To run this example, see Building Examples That Use a Demo Method and a TextBlock Control.

Imports System.Collections

' This class implements a simple dictionary using an array of DictionaryEntry objects (key/value pairs).
Public Class SimpleDictionary
   Implements IDictionary

   ' The array of items
   Dim items() As DictionaryEntry
   Dim ItemsInUse As Integer = 0

   ' Construct the SimpleDictionary with the desired number of items.
   ' The number of items cannot change for the life time of this SimpleDictionary.
   Public Sub New(ByVal numItems As Integer)
      items = New DictionaryEntry(numItems - 1) {}
   End Sub

   ' IDictionary Members
   Public ReadOnly Property IsReadOnly() As Boolean Implements IDictionary.IsReadOnly
      Get
         Return False
      End Get
   End Property

   Public Function Contains(ByVal key As Object) As Boolean Implements IDictionary.Contains
      Dim index As Integer
      Return TryGetIndexOfKey(key, index)
   End Function

   Public ReadOnly Property IsFixedSize() As Boolean Implements IDictionary.IsFixedSize
      Get
         Return False
      End Get
   End Property

   Public Sub Remove(ByVal key As Object) Implements IDictionary.Remove
      If key = Nothing Then
         Throw New ArgumentNullException("key")
      End If
      ' Try to find the key in the DictionaryEntry array
      Dim index As Integer
      If TryGetIndexOfKey(key, index) Then

         ' If the key is found, slide all the items up.
         Array.Copy(items, index + 1, items, index, (ItemsInUse - index) - 1)
         ItemsInUse = ItemsInUse - 1
      Else

         ' If the key is not in the dictionary, just return. 
      End If
   End Sub

   Public Sub Clear() Implements IDictionary.Clear
      ItemsInUse = 0
   End Sub

   Public Sub Add(ByVal key As Object, ByVal value As Object) Implements IDictionary.Add

      ' Add the new key/value pair even if this key already exists in the dictionary.
      If ItemsInUse = items.Length Then
         Throw New InvalidOperationException("The dictionary cannot hold any more items.")
      End If
      items(ItemsInUse) = New DictionaryEntry(key, value)
      ItemsInUse = ItemsInUse + 1
   End Sub

   Public ReadOnly Property Keys() As ICollection Implements IDictionary.Keys
      Get

         ' Return an array where each item is a key.
         ' Note: Declaring keyArray() to have a size of ItemsInUse - 1
         '       ensures that the array is properly sized, in VB.NET
         '       declaring an array of size N creates an array with
         '       0 through N elements, including N, as opposed to N - 1
         '       which is the default behavior in C# and C++.
         Dim keyArray() As Object = New Object(ItemsInUse - 1) {}
         Dim n As Integer
         For n = 0 To ItemsInUse - 1
            keyArray(n) = items(n).Key
         Next n

         Return keyArray
      End Get
   End Property

   Public ReadOnly Property Values() As ICollection Implements IDictionary.Values
      Get
         ' Return an array where each item is a value.
         Dim valueArray() As Object = New Object(ItemsInUse - 1) {}
         Dim n As Integer
         For n = 0 To ItemsInUse - 1
            valueArray(n) = items(n).Value
         Next n

         Return valueArray
      End Get
   End Property

   Public Property Item(ByVal key As Object) As Object Implements IDictionary.Item
      Get

         ' If this key is in the dictionary, return its value.
         Dim index As Integer
         If TryGetIndexOfKey(key, index) Then

            ' The key was found return its value.
            Return items(index).Value
         Else

            ' The key was not found return null.
            Return Nothing
         End If
      End Get

      Set(ByVal value As Object)
         ' If this key is in the dictionary, change its value. 
         Dim index As Integer
         If TryGetIndexOfKey(key, index) Then

            ' The key was found change its value.
            items(index).Value = value
         Else

            ' This key is not in the dictionary add this key/value pair.
            Add(key, value)
         End If
      End Set
   End Property

   Private Function TryGetIndexOfKey(ByVal key As Object, ByRef index As Integer) As Boolean
      For index = 0 To ItemsInUse - 1
         ' If the key is found, return true (the index is also returned).
         If items(index).Key.Equals(key) Then
            Return True
         End If
      Next index

      ' Key not found, return false (index should be ignored by the caller).
      Return False
   End Function

   Private Class SimpleDictionaryEnumerator
      Implements IDictionaryEnumerator

      ' A copy of the SimpleDictionary object's key/value pairs.
      Dim items() As DictionaryEntry
      Dim index As Integer = -1

      Public Sub New(ByVal sd As SimpleDictionary)
         ' Make a copy of the dictionary entries currently in the SimpleDictionary object.
         items = New DictionaryEntry(sd.Count - 1) {}
         Array.Copy(sd.items, 0, items, 0, sd.Count)
      End Sub

      ' Return the current item.
      Public ReadOnly Property Current() As Object Implements IDictionaryEnumerator.Current
         Get
            ValidateIndex()
            Return items(index)
         End Get
      End Property

      ' Return the current dictionary entry.
      Public ReadOnly Property Entry() As DictionaryEntry Implements IDictionaryEnumerator.Entry
         Get
            Return Current
         End Get
      End Property

      ' Return the key of the current item.
      Public ReadOnly Property Key() As Object Implements IDictionaryEnumerator.Key
         Get
            ValidateIndex()
            Return items(index).Key
         End Get
      End Property

      ' Return the value of the current item.
      Public ReadOnly Property Value() As Object Implements IDictionaryEnumerator.Value
         Get
            ValidateIndex()
            Return items(index).Value
         End Get
      End Property

      ' Advance to the next item.
      Public Function MoveNext() As Boolean Implements IDictionaryEnumerator.MoveNext
         If index < items.Length - 1 Then
            index = index + 1
            Return True
         End If

         Return False
      End Function

      ' Validate the enumeration index and throw an exception if the index is out of range.
      Private Sub ValidateIndex()
         If index < 0 Or index >= items.Length Then
            Throw New InvalidOperationException("Enumerator is before or after the collection.")
         End If
      End Sub

      ' Reset the index to restart the enumeration.
      Public Sub Reset() Implements IDictionaryEnumerator.Reset
         index = -1
      End Sub

   End Class

   Public Function GetEnumerator() As IDictionaryEnumerator Implements IDictionary.GetEnumerator

      'Construct and return an enumerator.
      Return New SimpleDictionaryEnumerator(Me)
   End Function


   ' ICollection Members
   Public ReadOnly Property IsSynchronized() As Boolean Implements IDictionary.IsSynchronized
      Get
         Return False
      End Get
   End Property

   Public ReadOnly Property SyncRoot() As Object Implements IDictionary.SyncRoot
      Get
         Throw New NotImplementedException()
      End Get
   End Property

   Public ReadOnly Property Count() As Integer Implements IDictionary.Count
      Get
         Return ItemsInUse
      End Get
   End Property

   Public Sub CopyTo(ByVal array As Array, ByVal index As Integer) Implements IDictionary.CopyTo
      Throw New NotImplementedException()
   End Sub

   ' IEnumerable Members
   Public Function GetEnumerator1() As IEnumerator Implements IEnumerable.GetEnumerator

      ' Construct and return an enumerator.
      Return Me.GetEnumerator()
   End Function
End Class

Public NotInheritable Class Example
   Public Shared Sub Demo(ByVal outputBlock As System.Windows.Controls.TextBlock)
      ' Create a dictionary that contains no more than three entries.
      Dim d As IDictionary = New SimpleDictionary(3)

      ' Add three people and their ages to the dictionary.
      d.Add("Jeff", 40)
      d.Add("Kristin", 34)
      d.Add("Aidan", 1)

      outputBlock.Text += String.Format("Number of elements in dictionary = {0}", d.Count) & vbCrLf

      outputBlock.Text += String.Format("Does dictionary contain 'Jeff'? {0}", d.Contains("Jeff")) & vbCrLf
      outputBlock.Text += String.Format("Jeff's age is {0}", d("Jeff")) & vbCrLf

      ' Display every entry's key and value.
      Dim de As DictionaryEntry
      For Each de In d
         outputBlock.Text += String.Format("{0} is {1} years old.", de.Key, de.Value) & vbCrLf
      Next

      ' Remove an entry that exists.
      d.Remove("Jeff")

      ' Remove an entry that does not exist, but do not throw an exception.
      d.Remove("Max")

      ' Show the names (keys) of the people in the dictionary.
      Dim s As String

      For Each s In d.Keys
         outputBlock.Text &= s & vbCrLf
      Next

      ' Show the ages (values) of the people in the dictionary.
      Dim age As Integer
      For Each age In d.Values
         outputBlock.Text &= age & vbCrLf
      Next

   End Sub
End Class

' This code produces the following output.
'
' Number of elements in dictionary = 3
' Does dictionary contain 'Jeff'? True
' Jeff's age is 40
' Jeff is 40 years old.
' Kristin is 34 years old.
' Aidan is 1 years old.
' Kristin
' Aidan
' 34
' 1

using System;
using System.Collections;

// This class implements a simple dictionary using an array of DictionaryEntry objects (key/value pairs).
public class SimpleDictionary : IDictionary
{
   // The array of items
   private DictionaryEntry[] items;
   private Int32 ItemsInUse = 0;

   // Construct the SimpleDictionary with the desired number of items.
   // The number of items cannot change for the life time of this SimpleDictionary.
   public SimpleDictionary(Int32 numItems)
   {
      items = new DictionaryEntry[numItems];
   }


   #region IDictionary Members
   public bool IsReadOnly { get { return false; } }
   public bool Contains(object key)
   {
      Int32 index;
      return TryGetIndexOfKey(key, out index);
   }
   public bool IsFixedSize { get { return false; } }
   public void Remove(object key)
   {
      if (key == null) throw new ArgumentNullException("key");
      // Try to find the key in the DictionaryEntry array
      Int32 index;
      if (TryGetIndexOfKey(key, out index))
      {
         // If the key is found, slide all the items up.
         Array.Copy(items, index + 1, items, index, ItemsInUse - index - 1);
         ItemsInUse--;
      }
      else
      {
         // If the key is not in the dictionary, just return. 
      }
   }
   public void Clear() { ItemsInUse = 0; }
   public void Add(object key, object value)
   {
      // Add the new key/value pair even if this key already exists in the dictionary.
      if (ItemsInUse == items.Length)
         throw new InvalidOperationException("The dictionary cannot hold any more items.");
      items[ItemsInUse++] = new DictionaryEntry(key, value);
   }
   public ICollection Keys
   {
      get
      {
         // Return an array where each item is a key.
         Object[] keys = new Object[ItemsInUse];
         for (Int32 n = 0; n < ItemsInUse; n++)
            keys[n] = items[n].Key;
         return keys;
      }
   }
   public ICollection Values
   {
      get
      {
         // Return an array where each item is a value.
         Object[] values = new Object[ItemsInUse];
         for (Int32 n = 0; n < ItemsInUse; n++)
            values[n] = items[n].Value;
         return values;
      }
   }
   public object this[object key]
   {
      get
      {
         // If this key is in the dictionary, return its value.
         Int32 index;
         if (TryGetIndexOfKey(key, out index))
         {
            // The key was found; return its value.
            return items[index].Value;
         }
         else
         {
            // The key was not found; return null.
            return null;
         }
      }

      set
      {
         // If this key is in the dictionary, change its value. 
         Int32 index;
         if (TryGetIndexOfKey(key, out index))
         {
            // The key was found; change its value.
            items[index].Value = value;
         }
         else
         {
            // This key is not in the dictionary; add this key/value pair.
            Add(key, value);
         }
      }
   }
   private Boolean TryGetIndexOfKey(Object key, out Int32 index)
   {
      for (index = 0; index < ItemsInUse; index++)
      {
         // If the key is found, return true (the index is also returned).
         if (items[index].Key.Equals(key)) return true;
      }

      // Key not found, return false (index should be ignored by the caller).
      return false;
   }
   private class SimpleDictionaryEnumerator : IDictionaryEnumerator
   {
      // A copy of the SimpleDictionary object's key/value pairs.
      DictionaryEntry[] items;
      Int32 index = -1;

      public SimpleDictionaryEnumerator(SimpleDictionary sd)
      {
         // Make a copy of the dictionary entries currently in the SimpleDictionary object.
         items = new DictionaryEntry[sd.Count];
         Array.Copy(sd.items, 0, items, 0, sd.Count);
      }

      // Return the current item.
      public Object Current { get { ValidateIndex(); return items[index]; } }

      // Return the current dictionary entry.
      public DictionaryEntry Entry
      {
         get { return (DictionaryEntry)Current; }
      }

      // Return the key of the current item.
      public Object Key { get { ValidateIndex(); return items[index].Key; } }

      // Return the value of the current item.
      public Object Value { get { ValidateIndex(); return items[index].Value; } }

      // Advance to the next item.
      public Boolean MoveNext()
      {
         if (index < items.Length - 1) { index++; return true; }
         return false;
      }

      // Validate the enumeration index and throw an exception if the index is out of range.
      private void ValidateIndex()
      {
         if (index < 0 || index >= items.Length)
            throw new InvalidOperationException("Enumerator is before or after the collection.");
      }

      // Reset the index to restart the enumeration.
      public void Reset()
      {
         index = -1;
      }
   }
   public IDictionaryEnumerator GetEnumerator()
   {
      // Construct and return an enumerator.
      return new SimpleDictionaryEnumerator(this);
   }
   #endregion

   #region ICollection Members
   public bool IsSynchronized { get { return false; } }
   public object SyncRoot { get { throw new NotImplementedException(); } }
   public int Count { get { return ItemsInUse; } }
   public void CopyTo(Array array, int index) { throw new NotImplementedException(); }
   #endregion

   #region IEnumerable Members
   IEnumerator IEnumerable.GetEnumerator()
   {
      // Construct and return an enumerator.
      return ((IDictionary)this).GetEnumerator();
   }
   #endregion
}

public sealed class Example
{
   public static void Demo(System.Windows.Controls.TextBlock outputBlock)
   {
      // Create a dictionary that contains no more than three entries.
      IDictionary d = new SimpleDictionary(3);

      // Add three people and their ages to the dictionary.
      d.Add("Jeff", 40);
      d.Add("Kristin", 34);
      d.Add("Aidan", 1);

      outputBlock.Text += String.Format("Number of elements in dictionary = {0}", d.Count) + "\n";

      outputBlock.Text += String.Format("Does dictionary contain 'Jeff'? {0}", d.Contains("Jeff")) + "\n";
      outputBlock.Text += String.Format("Jeff's age is {0}", d["Jeff"]) + "\n";

      // Display every entry's key and value.
      foreach (DictionaryEntry de in d)
      {
         outputBlock.Text += String.Format("{0} is {1} years old.", de.Key, de.Value) + "\n";
      }

      // Remove an entry that exists.
      d.Remove("Jeff");

      // Remove an entry that does not exist, but do not throw an exception.
      d.Remove("Max");

      // Show the names (keys) of the people in the dictionary.
      foreach (String s in d.Keys)
         outputBlock.Text += s + "\n";

      // Show the ages (values) of the people in the dictionary.
      foreach (Int32 age in d.Values)
         outputBlock.Text += age + "\n";
   }
}

// This code produces the following output.
//
// Number of elements in dictionary = 3
// Does dictionary contain 'Jeff'? True
// Jeff's age is 40
// Jeff is 40 years old.
// Kristin is 34 years old.
// Aidan is 1 years old.
// Kristin
// Aidan
// 34
// 1

Version Information

Silverlight

Supported in: 5, 4, 3

Silverlight for Windows Phone

Supported in: Windows Phone OS 7.1, Windows Phone OS 7.0

XNA Framework

Supported in: Xbox 360, Windows Phone OS 7.0

Platforms

For a list of the operating systems and browsers that are supported by Silverlight, see Supported Operating Systems and Browsers.

See Also

Reference

System.Collections Namespace

ICollection