System.Collections.Specialized.StringDictionary Class

Summary

Implements a hashtable with the key strongly typed to be a string rather than an object.

C# Syntax:

public class StringDictionary : 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 StringDictionary, but derived classes can create their own synchronized versions of the StringDictionary using the StringDictionary.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 key is handled in a case-insensitive manner; it will be translated to lower case before it is used with the string dictionary.

System.Collections.Specialized Namespace | Hashtable

System.Collections.Specialized.StringDictionary Member List:

Public Constructors

ctor #1

Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the StringDictionary class.

Public Properties

Count	Read-only Gets the number of key-and-value pairs in the StringDictionary.
IsSynchronized	Read-only Gets a value that indicates whether access to the StringDictionary is synchronized (thread-safe).
Item	Read-write Gets or sets the value associated with the specified key.
Keys	Read-only Gets a collection of keys in the StringDictionary.
SyncRoot	Read-only Gets an object that can be used to synchronize access to the StringDictionary.
Values	Read-only Gets a collection of values in the StringDictionary.

Public Methods

Add	Adds an entry with the specified key and value into the StringDictionary.
Clear	Removes all entries from the StringDictionary.
ContainsKey	Determines if the StringDictionary contains a specific key.
ContainsValue	Determines if the StringDictionary contains a specific value.
CopyTo	Copies the string dictionary values 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 enumerator that can iterate through the string dictionary.
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 string dictionary.
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.

Hierarchy:

• System.Object
• System.Collections.Specialized.StringDictionary

System.Collections.Specialized.StringDictionary Member Details

Summary

Initializes a new instance of the StringDictionary class.

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

C# Syntax:

public StringDictionary();

Return to top

Summary

Gets the number of key-and-value pairs in the StringDictionary.

C# Syntax:

public virtual int Count {get;}

Return to top

Summary

Gets a value that indicates whether access to the StringDictionary is synchronized (thread-safe).

C# Syntax:

public virtual bool IsSynchronized {get;}

A StringDictionary instance is not synchronized. Derived classes can provide a synchronized version of the StringDictionary using the StringDictionary.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 StringDictionary.SyncRoot during the entire enumeration:

              StringDictionary myCollection = new StringDictionary();
               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 virtual string this[string key] {get; set;}

key

The key whose value to get or set.

The key is handled in a case-insensitive manner; it will be translated to lower case before it is used.

Return to top

Summary

Gets a collection of keys in the StringDictionary.

C# Syntax:

public virtual ICollection Keys {get;}

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

Changes to the StringDictionary will continue to be reflected in the returned ICollection. It is not a static copy.

Return to top

Summary

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

C# Syntax:

public virtual object SyncRoot {get;}

Derived classes can provide their own synchronized version of the StringDictionary using the StringDictionary.SyncRoot property. The synchronizing code must perform operations on the StringDictionary.SyncRoot of the StringDictionary, not directly on the StringDictionary. 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 StringDictionary 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 StringDictionary.SyncRoot during the entire enumeration:

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

Return to top

Summary

Gets a collection of values in the StringDictionary.

C# Syntax:

public virtual ICollection Values {get;}

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 StringDictionary.Keys method.

Changes to the StringDictionary will continue to be reflected in the returned ICollection. It is not a static copy.

Return to top

Summary

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

C# Syntax:

public virtual void Add(    string key,    string value );

key

The key of the entry to add.

value

The value of the entry to add.

Exceptions

Exception Type	Condition
ArgumentNullException	The key is null.
ArgumentException	An entry with the same key already exists in the StringDictionary.
NotSupportedException	The StringDictionary is read-only.

The key is handled in a case-insensitive manner; it will be translated to lower case before it is added to the string dictionary.

Return to top

Summary

Removes all entries from the StringDictionary.

C# Syntax:

public virtual void Clear();

Exceptions

Exception Type	Condition
NotSupportedException	The StringDictionary is read-only.

Return to top

Summary

Determines if the StringDictionary contains a specific key.

C# Syntax:

public virtual bool ContainsKey(    string key );

key

The key to locate in the StringDictionary.

Return Value:

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

Exceptions

Exception Type	Condition
ArgumentNullException	The key is null.

This implementation is an O(1) operation.

The key is handled in a case-insensitive manner; it will be translated to lower case before it is used.

Return to top

Summary

Determines if the StringDictionary contains a specific value.

C# Syntax:

public virtual bool ContainsValue(    string value );

value

The value to locate in the StringDictionary.

Return Value:

true if the StringDictionary contains an element with the specified value; otherwise, false.

The values of the elements of the StringDictionary are compared to the specified value using the Object.Equals method.

This method uses a linear search; therefore, the average execution time is proportional to the size of the StringDictionary. That is, this implementation is an O(n) operation.

Return to top

Summary

Copies the string dictionary values to a one-dimensional Array instance at the specified index.

C# Syntax:

public virtual void CopyTo(    Array array,    int index );

array

The one-dimensional Array that is the destination of the values copied from the StringDictionary.

index

The index in the array where copying begins.

Exceptions

Exception Type	Condition
ArgumentException	The array is multidimensional, or the number of elements in the Hashtable is greater than the available space between index and the end of array
ArgumentNullException	The array is a null
ArgumentOutOfRangeException	The index is less than the array's lower bound.

StringDictionary.CopyTo only copies the values in the StringDictionary, not the keys.

The elements copied to the Array are sorted in the same order that the enumerator iterates through the StringDictionary.

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:

~StringDictionary();

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

Return to top

Summary

Returns an enumerator that can iterate through the string dictionary.

C# Syntax:

public virtual IEnumerator GetEnumerator();

Return Value:

An IEnumerator that can iterate through the string dictionary.

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.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 string dictionary.

C# Syntax:

public virtual void Remove(    string key );

key

The key of the entry to remove.

Exceptions

Exception Type	Condition
ArgumentNullException	The key is null.
NotSupportedException	The StringDictionary is read-only.

The key is handled in a case-insensitive manner; it will be translated to lower case before it is used to find the entry to remove from the string dictionary.

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