System.Collections.Specialized.ListDictionary Class

Summary

Implements IDictionary using a singly linked list. Recommended for collections that typically contain 10 items or less.

C# Syntax:

[Serializable] public class ListDictionary : IDictionary, ICollection, IEnumerable

Public static (non-instance) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

This implementation does not provide a synchronized (thread-safe) wrapper for a ListDictionary, but derived classes can create their own synchronized versions of the ListDictionary using the ListDictionary.SyncRoot property.

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.

This is a simple implementation of IDictionary using a singly linked list. It is smaller and faster than a Hashtable if the number of elements is 10 or less. This should not be used if performance is important for large numbers of elements.

Members, such as ListDictionary.Item, ListDictionary.Add, ListDictionary.Remove, and ListDictionary.Contains are O(n) operations, where n is ListDictionary.Count.

System.Collections.Specialized Namespace | IDictionary | Hashtable

System.Collections.Specialized.ListDictionary Member List:

Public Constructors

ctor #1	Overloaded: .ctor() Default constructor. This constructor is called by derived class constructors to initialize state in this type. Creates an empty ListDictionary using the default comparer.
ctor #2	Overloaded: .ctor(IComparer comparer) Creates an empty ListDictionary using the specified comparer.

Public Properties

Count	Read-only Gets the number of key-and-value pairs contained in the ListDictionary.
IsFixedSize	Read-only Gets a value indicating whether the ListDictionary has a fixed size.
IsReadOnly	Read-only Gets a value indicating whether the ListDictionary is read-only.
IsSynchronized	Read-only Gets a value indicating whether the ListDictionary is synchronized (thread-safe).
Item	Read-write Gets or sets the value associated with the specified key.
Keys	Read-only Gets an ICollection containing the keys in the ListDictionary.
SyncRoot	Read-only Gets an object that can be used to synchronize access to the ListDictionary.
Values	Read-only Gets an ICollection containing the values in the ListDictionary.

Public Methods

Add	Adds an entry with the specified key and value into the ListDictionary.
Clear	Removes all entries from the ListDictionary.
Contains	Determines whether the ListDictionary contains a specific key.
CopyTo	Copies the ListDictionary entries to a one-dimensional Array instance at the specified index.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetEnumerator	Returns an IDictionaryEnumerator that can iterate through the ListDictionary.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
Remove	Removes the entry with the specified key from the ListDictionary.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Explicit Interface Implementations 

IEnumerable.GetEnumerator

Returns an IEnumerator that can iterate through the ListDictionary.

Hierarchy:

• System.Object
• System.Collections.Specialized.ListDictionary

System.Collections.Specialized.ListDictionary Member Details

Summary

Creates an empty ListDictionary using the default comparer.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:

public ListDictionary();

The comparer determines whether two keys are equal. Every key in a ListDictionary must be unique. The default comparer is the key's implementation of Object.Equals.

Return to top

Summary

Creates an empty ListDictionary using the specified comparer.

C# Syntax:

public ListDictionary(    IComparer comparer );

comparer

The IComparer to use to determine whether two keys are equal.

-or-

null to use the default comparer, which is each key's implementation of Object.Equals.

The IComparer to use to determine whether two keys are equal.

-or-

null to use the default comparer, which is each key's implementation of Object.Equals.

The comparer determines whether two keys are equal. Every key in a ListDictionary must be unique. The default comparer is the key's implementation of Object.Equals.

The custom comparer enables such scenarios as doing lookups with case-insensitive strings.

Return to top

Summary

Gets the number of key-and-value pairs contained in the ListDictionary.

C# Syntax:

public int Count {get;}

Implements:

ICollection.Count

This is an O(1) operation.

Return to top

Summary

Gets a value indicating whether the ListDictionary has a fixed size.

C# Syntax:

public bool IsFixedSize {get;}

Implements:

IDictionary.IsFixedSize

ListDictionary implements the ListDictionary.IsFixedSize property because it is required by the IDictionary interface.

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

Gets a value indicating whether the ListDictionary is read-only.

C# Syntax:

public bool IsReadOnly {get;}

Implements:

IDictionary.IsReadOnly

ListDictionary implements the ListDictionary.IsReadOnly property because it is required by the IDictionary interface.

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

Gets a value indicating whether the ListDictionary is synchronized (thread-safe).

C# Syntax:

public bool IsSynchronized {get;}

Implements:

ICollection.IsSynchronized

ListDictionary implements the ListDictionary.IsSynchronized property because it is required by the ICollection interface.

Derived classes can provide a synchronized version of the ListDictionary using the ListDictionary.SyncRoot property.

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.

The following code example shows how to lock the collection using the ListDictionary.SyncRoot during the entire enumeration:

              ListDictionary myCollection = new ListDictionary();
               lock( myCollection.SyncRoot ) {
               foreach ( Object item in myCollection ) {
               // Insert your code here.
               }
              }
            

Return to top

Summary

Gets or sets the value associated with the specified key.

C# Syntax:

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

key

The key whose value to get or set.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.

Implements:

IDictionary.Item

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 ListDictionary, the value is replaced; otherwise, a new element is created. In contrast, the ListDictionary.Add method does not modify existing elements.

This is an O(n) operation, where n is ListDictionary.Count.

Return to top

Summary

Gets an ICollection containing the keys in the ListDictionary.

C# Syntax:

public ICollection Keys {get;}

Implements:

IDictionary.Keys

The order of the values in the ICollection is unspecified, but it is the same order as the associated values in the ICollection returned by the ListDictionary.Values method.

The returned ICollection is a reference to the original ListDictionary, not a static copy. Therefore, changes to the ListDictionary continue to be reflected in the ICollection.

Return to top

Summary

Gets an object that can be used to synchronize access to the ListDictionary.

C# Syntax:

public object SyncRoot {get;}

Implements:

ICollection.SyncRoot

Derived classes can provide their own synchronized version of the ListDictionary using the ListDictionary.SyncRoot property. The synchronizing code must perform operations on the ListDictionary.SyncRoot of the ListDictionary, not directly on the ListDictionary. This ensures proper operation of collections that are derived from other objects. Specifically, it maintains proper synchronization with other threads that might be simultaneously modifying the ListDictionary object.

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.

The following code example shows how to lock the collection using the ListDictionary.SyncRoot during the entire enumeration:

              ListDictionary myCollection = new ListDictionary();
               lock( myCollection.SyncRoot ) {
               foreach ( Object item in myCollection ) {
               // Insert your code here.
               }
              }
            

Return to top

Summary

Gets an ICollection containing the values in the ListDictionary.

C# Syntax:

public ICollection Values {get;}

Implements:

IDictionary.Values

The order of the values in the ICollection is unspecified, but it is the same order as the associated keys in the ICollection returned by the ListDictionary.Keys method.

The returned ICollection is a reference to the original ListDictionary, not a static copy. Therefore, changes to the ListDictionary continue to be reflected in the ICollection.

Return to top

Summary

Adds an entry with the specified key and value into the ListDictionary.

C# Syntax:

public void Add(    object key,    object value );

key

The key of the entry to add.

value

The value of the entry to add.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.
ArgumentException	An entry with the same key already exists in the ListDictionary.

Implements:

IDictionary.Add

An object that has no correlation between its state and its hash code value should typically not be used as the key. For example, String objects are better than StringBuilder objects for use as keys.

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

This is an O(n) operation, where n is ListDictionary.Count.

Return to top

Summary

Removes all entries from the ListDictionary.

C# Syntax:

public void Clear();

Implements:

IDictionary.Clear

ListDictionary.Count is set to zero.

This is an O(1) operation.

Return to top

Summary

Determines whether the ListDictionary contains a specific key.

C# Syntax:

public bool Contains(    object key );

key

The key to locate in the ListDictionary.

Return Value:

true if the ListDictionary contains an entry with the specified key; otherwise, false.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.

Implements:

IDictionary.Contains

This is an O(n) operation, where n is ListDictionary.Count.

Return to top

Summary

Copies the ListDictionary entries to a one-dimensional Array instance at the specified index.

C# Syntax:

public void CopyTo(    Array array,    int index );

array

The one-dimensional Array that is the destination of the DictionaryEntry objects copied from ListDictionary. The Array must have zero-based indexing.

index

The zero-based index in array at which copying begins.

Exceptions

Exception Type	Condition
ArgumentNullException	array is null.
ArgumentOutOfRangeException	index is less than zero.
ArgumentException	array is multidimensional. -or- arrayIndex is equal to or greater than the length of array. -or- The number of elements in the source ListDictionary is greater than the available space from arrayIndex to the end of the destination array.
InvalidCastException	The type of the source ListDictionary cannot be cast automatically to the type of the destination array.

Implements:

ICollection.CopyTo

The elements are copied to the Array in the same order in which the enumerator iterates through the ListDictionary.

To copy only the keys in the ListDictionary, use ListDictionary.Keys.CopyTo .

To copy only the values in the ListDictionary, use ListDictionary.Values.CopyTo .

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~ListDictionary();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Returns an IDictionaryEnumerator that can iterate through the ListDictionary.

C# Syntax:

public IDictionaryEnumerator GetEnumerator();

Return Value:

An IDictionaryEnumerator for the ListDictionary.

Implements:

IDictionary.GetEnumerator

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

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Removes the entry with the specified key from the ListDictionary.

C# Syntax:

public void Remove(    object key );

key

The key of the entry to remove.

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.

Implements:

IDictionary.Remove

If the ListDictionary does not contain an element with the specified key, the ListDictionary remains unchanged. No exception is thrown.

This is an O(n) operation, where n is ListDictionary.Count.

Return to top

Summary

Returns an IEnumerator that can iterate through the ListDictionary.

C# Syntax:

IEnumerator IEnumerable.GetEnumerator();

Return Value:

An IEnumerator for the ListDictionary.

Implements:

IEnumerable.GetEnumerator

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

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Top of page