System.Collections.IDictionary Interface

Summary

Represents a collection of key-and-value pairs.

C# Syntax:

public interface IDictionary : ICollection, IEnumerable

The IDictionary class is the base interface for collections of key-and-value pairs.

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

Each association must have a unique key that is not null, but the value of an association can be any object reference, including a null reference. 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 cannot be modified. A fixed-size IDictionary does not allow the addition or removal of elements, but it allows the modification of existing elements. A variable-size IDictionary allows the addition, removal and modification of elements.

The foreach statement of the C# language requires the type of each element in the collection. Since each element of the Hashtable is a key-and-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 myEntry in myHashtable) {...}

System.Collections Namespace | Hashtable

System.Collections.IDictionary Member List:

Public Properties

IsFixedSize	Read-only When implemented by a class, gets a value indicating whether the IDictionary has a fixed size.
IsReadOnly	Read-only When implemented by a class, gets a value indicating whether the IDictionary is read-only.
Item	Read-write When implemented by a class, gets or sets the element with the specified key.
Keys	Read-only When implemented by a class, gets an ICollection containing the keys of the IDictionary.
Values	Read-only When implemented by a class, gets an ICollection containing the values in the IDictionary.

Public Methods

Add	When implemented by a class, adds an element with the provided key and value to the IDictionary.
Clear	When implemented by a class, removes all elements from the IDictionary.
Contains	When implemented by a class, determines whether the IDictionary contains an element with the specified key.
GetEnumerator	When implemented by a class, returns an IDictionaryEnumerator for the IDictionary.
Remove	When implemented by a class, removes the element with the specified key from the IDictionary.

Hierarchy:

• System.Collections.ICollection
• System.Collections.IEnumerable
• System.Collections.IDictionary

System.Collections.IDictionary Member Details

Summary

When implemented by a class, gets a value indicating whether the IDictionary has a fixed size.

C# Syntax:

bool IsFixedSize {get;}

A collection with a fixed size does not allow the addition or removal of elements after the collection is created, but it allows the modification of existing elements.

Return to top

Summary

When implemented by a class, gets a value indicating whether the IDictionary is read-only.

C# Syntax:

bool IsReadOnly {get;}

A collection that is read-only does not allow the addition, removal, or modification of elements after the collection is created.

Return to top

Summary

When implemented by a class, gets or sets the element with the specified key.

C# Syntax:

object this[object key] {get; set;}

key

The key of the element to get or set.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.
NotSupportedException	The property is set and the IDictionary is read-only. -or- The property is set, key does not exist in the collection, and the IDictionary has a fixed size.

This property provides the ability to access a specific element in the collection by using the following syntax: myCollection[key] .

When setting this property, if the specified key already exists in the dictionary, the value is replaced; otherwise, a new element is created. In contrast, the IDictionary.Add method does not modify existing elements.

Return to top

Summary

When implemented by a class, gets an ICollection containing the keys of the IDictionary.

C# Syntax:

ICollection Keys {get;}

The order of the keys in the returned ICollection is unspecified, but it is guaranteed to be the same order as the corresponding values in the ICollection returned by the IDictionary.Values method.

Return to top

Summary

When implemented by a class, gets an ICollection containing the values in the IDictionary.

C# Syntax:

ICollection Values {get;}

The order of the values in the returned ICollection is unspecified, but it is guaranteed to be the same order as the corresponding keys in the ICollection returned by the IDictionary.Keys method.

Return to top

Summary

When implemented by a class, adds an element with the provided key and value to the IDictionary.

C# Syntax:

void Add(    object key,    object value );

key

The Object to use as the key of the element to add.

value

The Object to use as the value of the element to add.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.
ArgumentException	An element with the same key already exists in the IDictionary.
NotSupportedException	The IDictionary is read-only. -or- The IDictionary has a fixed size.

The IDictionary.Item property can also be used to add new elements by setting the value of a key that does not exist in the dictionary. For example: myCollection["myNonexistentKey"] = myValue . However, if the specified key already exists in the dictionary, setting the IDictionary.Item property overwrites the old value. In contrast, the IDictionary.Add method does not modify existing elements.

Return to top

Summary

When implemented by a class, removes all elements from the IDictionary.

C# Syntax:

void Clear();

Exceptions

Exception Type	Condition
NotSupportedException	The IDictionary is read-only.

Return to top

Summary

When implemented by a class, determines whether the IDictionary contains an element with the specified key.

C# Syntax:

bool Contains(    object key );

key

The key to locate in the IDictionary.

Return Value:

true if the IDictionary contains an element with the key; otherwise, false.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.

Return to top

Summary

When implemented by a class, returns an IDictionaryEnumerator for the IDictionary.

C# Syntax:

IDictionaryEnumerator GetEnumerator();

Return Value:

An IDictionaryEnumerator for the IDictionary.

Enumerators only allow reading the data in the collection. Enumerators cannot be used to modify the underlying collection.

Initially, the enumerator is positioned before the first element in the collection. IEnumerator.Reset also brings the enumerator back to this position. At this position, calling IEnumerator.Current throws an exception. Therefore, you must call IEnumerator.MoveNext to advance the enumerator to the first element of the collection before reading the value of IEnumerator.Current.

IEnumerator.Current returns the same object until either IEnumerator.MoveNext or IEnumerator.Reset is called. IEnumerator.MoveNext sets IEnumerator.Current to the next element.

After the end of the collection is passed, the enumerator is positioned after the last element in the collection, and calling IEnumerator.MoveNext returns false. If the last call to IEnumerator.MoveNext returned false, calling IEnumerator.Current throws an exception. To set IEnumerator.Current to the first element of the collection again, you can call IEnumerator.Reset followed by IEnumerator.MoveNext.

An enumerator remains valid as long as the collection remains unchanged. If changes are made to the collection, such as adding, modifying or deleting elements, the enumerator is irrecoverably invalidated and the next call to IEnumerator.MoveNext or IEnumerator.Reset throws an InvalidOperationException. If the collection is modified between IEnumerator.MoveNext and IEnumerator.Current, IEnumerator.Current will return the element that it is set to, even if the enumerator is already invalidated.

The enumerator does not have exclusive access to the collection; therefore, enumerating through a collection is intrinsically not a thread-safe procedure. Even when a collection is synchronized, other threads could still modify the collection, which causes the enumerator to throw an exception. To guarantee thread safety during enumeration, you can either lock the collection during the entire enumeration or catch the exceptions resulting from changes made by other threads.

Return to top

Summary

When implemented by a class, removes the element with the specified key from the IDictionary.

C# Syntax:

void Remove(    object key );

key

The key of the element to remove.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.
NotSupportedException	The IDictionary is read-only. -or- The IDictionary has a fixed size.

In collections of contiguous elements, such as lists, the elements that follow the removed element move up to occupy the vacated spot. If the collection is indexed, the indexes of the elements that are moved are also updated. This behavior does not apply to collections where elements are conceptually grouped into buckets, such as a hashtable.

Return to top

Top of page