System.Collections.Specialized.HybridDictionary Class

Summary

Implements IDictionary by using a ListDictionary while the collection is small, and then switching to a Hashtable when the collection gets large.

C# Syntax:

[Serializable] public class HybridDictionary : 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 HybridDictionary, but derived classes can create their own synchronized versions of the HybridDictionary using the HybridDictionary.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 class is recommended for cases where the number of elements in a dictionary is unknown. It takes advantage of the improved performance of a ListDictionary with small collections, and offers the flexibility of switching to a Hashtable which handles larger collections better than ListDictionary.

If the initial size of the collection is greater than the optimal size for a ListDictionary, the collection is stored in a Hashtable right away to avoid the overhead of copying elements from the ListDictionary to a Hashtable.

The constructor accepts a boolean parameter that allows the user to specify whether the collection ignores the case when comparing strings. If the collection is case-sensitive, it uses the key's implementations of Object.GetHashCode and Object.Equals. If the collection is case-insensitive, it performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. By default, the collection is case-sensitive. For more information on the invariant culture, see CultureInfo.

System.Collections.Specialized Namespace | IDictionary | ListDictionary | Hashtable | CaseInsensitiveHashCodeProvider | Object.GetHashCode | Object.Equals

System.Collections.Specialized.HybridDictionary 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 case-sensitive HybridDictionary.
ctor #2	Overloaded: .ctor(bool caseInsensitive) Creates an empty HybridDictionary with the specified case-sensitivity.
ctor #3	Overloaded: .ctor(int initialSize) Creates a case-sensitive HybridDictionary with the specified initial size.
ctor #4	Overloaded: .ctor(int initialSize, bool caseInsensitive) Creates a HybridDictionary with the specified initial size and case-sensitivity.

Public Properties

Count	Read-only Gets the number of key-and-value pairs contained in the HybridDictionary.
IsFixedSize	Read-only Gets a value indicating whether the HybridDictionary has a fixed size.
IsReadOnly	Read-only Gets a value indicating whether the HybridDictionary is read-only.
IsSynchronized	Read-only Gets a value indicating whether the HybridDictionary 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 HybridDictionary.
SyncRoot	Read-only Gets an object that can be used to synchronize access to the HybridDictionary.
Values	Read-only Gets an ICollection containing the values in the HybridDictionary.

Public Methods

Add	Adds an entry with the specified key and value into the HybridDictionary.
Clear	Removes all entries from the HybridDictionary.
Contains	Determines whether the HybridDictionary contains a specific key.
CopyTo	Copies the HybridDictionary 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 HybridDictionary.
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 HybridDictionary.
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 HybridDictionary.

Hierarchy:

• System.Object
• System.Collections.Specialized.HybridDictionary

System.Collections.Specialized.HybridDictionary Member Details

Summary

Creates an empty case-sensitive HybridDictionary.

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

C# Syntax:

public HybridDictionary();

By default, the collection is case-sensitive and uses the key's implementation of Object.GetHashCode as the hash code provider and the key's implementation of Object.Equals as the comparer.

The comparer determines whether two keys are equal. Every key in a HybridDictionary must be unique.

Return to top

Summary

Creates an empty HybridDictionary with the specified case-sensitivity.

C# Syntax:

public HybridDictionary(    bool caseInsensitive );

caseInsensitive

A Boolean that denotes whether the HybridDictionary is case-insensitive.

If caseInsensitive is false, the collection uses the key's implementations of Object.GetHashCode and Object.Equals. If caseInsensitive is true, the collection performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. For more information on the invariant culture, see CultureInfo.

Return to top

Summary

Creates a case-sensitive HybridDictionary with the specified initial size.

C# Syntax:

public HybridDictionary(    int initialSize );

initialSize

The approximate number of entries that the HybridDictionary can initially contain.

If the initial size of the collection is greater than the optimal size for a ListDictionary, the collection is stored in a Hashtable right away to avoid the overhead of copying elements from the ListDictionary to the Hashtable.

By default, the collection is case-sensitive and uses the key's implementation of Object.GetHashCode as the hash code provider and the key's implementation of Object.Equals as the comparer.

The comparer determines whether two keys are equal. Every key in a HybridDictionary must be unique.

Return to top

Summary

Creates a HybridDictionary with the specified initial size and case-sensitivity.

C# Syntax:

public HybridDictionary(    int initialSize,    bool caseInsensitive );

initialSize

The approximate number of entries that the HybridDictionary can initially contain.

caseInsensitive

A Boolean that denotes whether the HybridDictionary is case-insensitive.

If the initial size of the collection is greater than the optimal size for a ListDictionary, the collection is stored in a Hashtable right away to avoid the overhead of copying elements from the ListDictionary to the Hashtable.

If caseInsensitive is false, the collection uses the key's implementations of Object.GetHashCode and Object.Equals. If caseInsensitive is true, the collection performs a simple ordinal case-insensitive comparison, which obeys the casing rules of the invariant culture only. For more information on the invariant culture, see CultureInfo.

Return to top

Summary

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

C# Syntax:

public int Count {get;}

Implements:

ICollection.Count

Return to top

Summary

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

C# Syntax:

public bool IsFixedSize {get;}

Implements:

IDictionary.IsFixedSize

HybridDictionary implements the HybridDictionary.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 HybridDictionary is read-only.

C# Syntax:

public bool IsReadOnly {get;}

Implements:

IDictionary.IsReadOnly

HybridDictionary implements the HybridDictionary.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 HybridDictionary is synchronized (thread-safe).

C# Syntax:

public bool IsSynchronized {get;}

Implements:

ICollection.IsSynchronized

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

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

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

Return to top

Summary

Gets an ICollection containing the keys in the HybridDictionary.

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 HybridDictionary.Values method.

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

Return to top

Summary

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

C# Syntax:

public object SyncRoot {get;}

Implements:

ICollection.SyncRoot

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

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

Return to top

Summary

Gets an ICollection containing the values in the HybridDictionary.

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

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

Return to top

Summary

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

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 HybridDictionary.

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

When the number of elements becomes greater than the optimal size for a ListDictionary, the elements are copied from the ListDictionary to a Hashtable. However, this only happens once. If the collection is already stored in a Hashtable and the number of elements falls below the optimal size for a ListDictionary, the collection remains in the Hashtable.

Return to top

Summary

Removes all entries from the HybridDictionary.

C# Syntax:

public void Clear();

Implements:

IDictionary.Clear

HybridDictionary.Count is set to zero.

If the collection is already stored in a Hashtable, the collection remains in the Hashtable.

Return to top

Summary

Determines whether the HybridDictionary contains a specific key.

C# Syntax:

public bool Contains(    object key );

key

The key to locate in the HybridDictionary.

Return Value:

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

Exceptions

Exception Type	Condition
ArgumentNullException	key is null.

Implements:

IDictionary.Contains

This implementation is close to O(1) in most cases.

Return to top

Summary

Copies the HybridDictionary 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 HybridDictionary. 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 HybridDictionary is greater than the available space from arrayIndex to the end of the destination array.
InvalidCastException	The type of the source HybridDictionary 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 HybridDictionary.

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

To copy only the values in the HybridDictionary, use HybridDictionary.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:

~HybridDictionary();

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 HybridDictionary.

C# Syntax:

public IDictionaryEnumerator GetEnumerator();

Return Value:

An IDictionaryEnumerator for the HybridDictionary.

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 HybridDictionary.

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 HybridDictionary does not contain an element with the specified key, the HybridDictionary remains unchanged. No exception is thrown.

If the collection is already stored in a Hashtable and the number of elements falls below the optimal size for a ListDictionary, the collection remains in the Hashtable to avoid the overhead of copying elements from the Hashtable back to a ListDictionary.

Return to top

Summary

Returns an IEnumerator that can iterate through the HybridDictionary.

C# Syntax:

IEnumerator IEnumerable.GetEnumerator();

Return Value:

An IEnumerator for the HybridDictionary.

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