System.Collections.Hashtable Class

public class Hashtable : ICloneable, ICollection, IDictionary, IEnumerable

Base Types

Object
  Hashtable

This type implements IDictionary, ICollection, IEnumerable, and ICloneable.

Assembly

mscorlib

Library

BCL

Summary

Represents a hash table.

Description

A Hashtable represents a dictionary with a constant lookup time that contains entries of associated keys and values. The type of each entry in a Hashtable is DictionaryEntry. A statement that exposes each element in the collection is required to iterate over this type. [Note: See example.]

Objects used as keys in a Hashtable are required to either implement both System.Object.GetHashCode and System.Object.Equals(System.Object) or neither. Furthermore, for a particular key, these methods are required to produce the same results when called with the same parameters while that key exists in a particular Hashtable . Keys cannot be mutated while they are used in the table.

Every key in a Hashtable is required to be unique compared to every other key in the table. An object that implements IComparer can determine whether two keys are unequal. The default comparer for a key is the key's implementation of System.Object.Equals(System.Object).

Each value in a Hashtable is required to provide its own hash function, which can be accessed by calling System.Collections.Hashtable.GetHash(System.Object). Alternatively, if an object that implements IHashCodeProvider is passed to a Hashtable constructor, the custom hash function provided by that object is used for every value in the table.

[Note: The default capacity (i.e. the default number of entries that can be contained) of a Hashtable is zero.

When an entry is added to the Hashtable, the entry is placed into a bucket based on the hash code obtained from the IHashCodeProvider implementation of the table, or the System.Object.GetHashCode if no specific IHashCodeProvider was provided. Subsequent lookups of the key use the hash code of the key to search in only one particular bucket, substantially reducing the number of key comparisons required to find an entry.

As entries are added to a Hashtable, and the maximum capacity of the table is reached, the number of buckets in the table is automatically increased to the smallest prime number that is larger than twice the current number of buckets.

A Hashtable can safely support one writer and multiple readers concurrently. To support multiple writers, all operations are required to be done through the wrapper returned by the System.Collections.Hashtable.Synchronized(System.Collections.Hashtable) method.

]

Example

The following example shows how to iterate over the elements of a Hashtable.

[C#]

foreach (DictionaryEntry myEntry in myHashtable)

Attributes

DefaultMemberAttribute("Item")

See Also

System.Collections Namespace

Members

Hashtable Constructors

Hashtable(System.Collections.IDictionary, System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor
Hashtable(System.Collections.IDictionary) Constructor
Hashtable(int, System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor
Hashtable(System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor
Hashtable(int) Constructor
Hashtable() Constructor

Hashtable Methods

Hashtable.Add Method
Hashtable.Clear Method
Hashtable.Clone Method
Hashtable.Contains Method
Hashtable.ContainsKey Method
Hashtable.ContainsValue Method
Hashtable.CopyTo Method
Hashtable.GetEnumerator Method
Hashtable.GetHash Method
Hashtable.KeyEquals Method
Hashtable.Remove Method
Hashtable.Synchronized Method
Hashtable.System.Collections.IEnumerable.GetEnumerator Method

Hashtable Properties

Hashtable.Count() Property
Hashtable.Count() Property
Hashtable.IsFixedSize() Property
Hashtable.IsFixedSize() Property
Hashtable.IsReadOnly() Property
Hashtable.IsReadOnly() Property
Hashtable.IsSynchronized() Property
Hashtable.IsSynchronized() Property
Hashtable.Item Property
Hashtable.Keys() Property
Hashtable.Keys() Property
Hashtable.SyncRoot() Property
Hashtable.SyncRoot() Property
Hashtable.Values() Property
Hashtable.Values() Property


Hashtable(System.Collections.IDictionary, System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor

public Hashtable(IDictionary d, IHashCodeProvider hcp, IComparer comparer);

Summary

Constructs and initializes a new instance of the Hashtable class using the values of the specified IDictionary, the specified IHashCodeProvider, and the specified IComparer.

Parameters

d
The IDictionary used to initialize the elements of the new instance.
hcp
The IHashCodeProvider that supplies the hash codes for all keys in the new instance; or, null to use the default hash code provider.

comparer
The IComparer to use to determine whether two keys are equal in the new instance, or null to use the default comparer.

Exceptions

Exception TypeCondition
ArgumentNullExceptiond is null .

Description

The initial capacity of the new instance is set to the number of entries in d.

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable(System.Collections.IDictionary) Constructor

public Hashtable(IDictionary d);

Summary

Constructs and initializes a new instance of the Hashtable class using the values of the specified IDictionary.

Parameters

d
The IDictionary used to initialize the elements of the new instance.

Exceptions

Exception TypeCondition
ArgumentNullExceptiond is null .

Description

The initial capacity of the new instance is set to the number of entries in d. The new instance is initialized with the default IHashCodeProvider and IComparer.

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable(int, System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor

public Hashtable(int capacity, IHashCodeProvider hcp, IComparer comparer);

Summary

Constructs and initializes a new instance of the Hashtable class with the specified initial capacity, the specified IHashCodeProvider, and the specified IComparer.

Parameters

capacity
A Int32 that specifies the minimum number of entries that the new Hashtable instance can initially contain.
hcp
The IHashCodeProvider that supplies the hash codes for all keys in the Hashtable; or, null to use the default hash code provider.

comparer
The IComparer to use to determine whether two keys are equal, or null to use the default comparer.

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable(System.Collections.IHashCodeProvider, System.Collections.IComparer) Constructor

public Hashtable(IHashCodeProvider hcp, IComparer comparer);

Summary

Constructs and initializes a new instance of the Hashtable class with the specified IHashCodeProvider and the specified IComparer.

Parameters

hcp
The IHashCodeProvider that supplies the hash codes for all keys in the Hashtable; or, null to use the default hash code provider.

comparer
The IComparer to use to determine whether two keys are equal; or, null to use the default comparer.

Description

The new instance is initialized with the default capacity.

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable(int) Constructor

public Hashtable(int capacity);

Summary

Constructs and initializes a new instance of the Hashtable class with the specified initial capacity.

Parameters

capacity
A Int32 that specifies the minimum number of entries that the new Hashtable instance can initially contain.

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptioncapacity < 0.

Description

The new instance is initialized with the default IHashCodeProvider and IComparer.

The number of entries that the new instance can contain can be greater than capacity.

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable() Constructor

public Hashtable();

Summary

Constructs and initializes a new instance of the Hashtable class.

Description

The new instance is initialized with the default capacity, IHashCodeProvider, and IComparer.

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Add Method

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

Summary

Adds an entry with the specified key and value into the current instance.

Parameters

key
The key of the entry to add.
value
The value of the entry to add.

Exceptions

Exception TypeCondition
ArgumentNullExceptionkey is null .

ArgumentExceptionAn entry with the same key already exists in the current instance.

NotSupportedExceptionThe current instance is read-only or has a fixed size.

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Clear Method

public virtual void Clear();

Summary

Removes all entries from the current instance.

Exceptions

Exception TypeCondition
NotSupportedExceptionThe current instance is read-only.

Description

[Note: This method is implemented to support the IDictionary interface.]

[Behaviors: As described above.]

[Default: The value of each key and value in the current instance is set to null . The System.Collections.Hashtable.Count property of the current instance is set to zero. The capacity of the current instance remains unchanged.

If the current instance is empty, it remains unchanged and no exception is thrown.

]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Clone Method

public virtual object Clone();

Summary

Creates a Object that is a copy of the current instance.

Return Value

A Object that is a copy of the current instance.

Description

[Note: This method is implemented to support the ICloneable interface.]

[Behaviors: As described above.]

[Default: This method creates a new Hashtable instance is initialized with the same count, IHashCodeProvider implementation, and IComparer implementation as the current instance. The references to the objects contained by the current instance are copied to the new instance.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Contains Method

public virtual bool Contains(object key);

Summary

Determines whether the current instance contains the specified key.

Parameters

key
The key to locate in the current instance.

Return Value

true if the current instance contains key; otherwise, false .

Exceptions

Exception TypeCondition
ArgumentNullExceptionkey is null .

Description

[Note: This method is implemented to support the IDictionary interface.]

[Behaviors: As described above.]

[Default: This method is equivalent to System.Collections.Hashtable.ContainsKey(System.Object).]

[Note: For the default implementation, this method has a constant (O(1)) lookup time.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.ContainsKey Method

public virtual bool ContainsKey(object key);

Summary

Determines whether the current instance contains an entry with the specified key.

Parameters

key
The key of the entry to locate in the current instance.

Return Value

true if the current instance contains an entry with key; otherwise, false .

Exceptions

Exception TypeCondition
ArgumentNullExceptionkey is null .

Description

[Behaviors: As described above.]

[Default: This method uses System.Collections.Hashtable.KeyEquals(System.Object,System.Object) to compare key to the keys in the current instance. ]

[Note: For the default implementation, this method has a constant (O(1)) lookup time.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.ContainsValue Method

public virtual bool ContainsValue(object value);

Summary

Determines whether the current instance contains an entry with the specified value.

Parameters

value
The value to locate in the current instance.

Return Value

true if the current instance contains an entry with value; otherwise, false .

Description

[Note: This method is implemented to support the IDictionary interface.]

[Behaviors: As described above.]

[Default: This method is equivalent to System.Collections.Hashtable.ContainsKey(System.Object).]

[Note: For the default implementation, this method has a constant (O(1)) lookup time.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.CopyTo Method

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

Summary

Copies the entries of the current instance to a one-dimensional Array starting at the specified index.

Parameters

array
The one-dimensional, zero-indexed Array that is the destination of the objects copied from the current instance.
arrayIndex
A Int32 that specifies the zero-based index in array at which copying begins. This value is between 0 and array.Length minus the System.Collections.Hashtable.Count of the current instance, inclusive.

Exceptions

Exception TypeCondition
ArgumentNullExceptionarray is null .
ArgumentOutOfRangeExceptionarrayIndex < 0.
ArgumentExceptionarray has more than one dimension.

-or-

arrayIndex > array.Length - The System.Collections.Hashtable.Count of the current instance.

InvalidCastExceptionThe type of the current instance is not assignment-compatible with the type of array.

Description

[Behaviors: As described above.]

[Default: The DictionaryEntry elements in the current instance are copied to the Array in the same order in which they are contained the current instance. If DictionaryEntry is not assignment-compatible with the type of array, a InvalidCastException is thrown. If an exception is thrown while copying, the state of the current instance is undefined.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.GetEnumerator Method

public virtual IDictionaryEnumerator GetEnumerator();

Summary

Returns a IDictionaryEnumerator for the current instance.

Return Value

A IDictionaryEnumerator for the current instance.

Description

If the current instance is modified while an enumeration is in progress, a call to System.Collections.IEnumerator.MoveNext or System.Collections.IEnumerator.Reset throws InvalidOperationException.

[Note: For detailed information regarding the use of an enumerator, see IEnumerator.

This property is implemented to support the IList interface.

]

[Behaviors: As described above.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.GetHash Method

protected virtual int GetHash(object key);

Summary

Generates a hash code for the specified key in the current instance.

Parameters

key
The Object whose hash code is to be generated.

Return Value

A Int32 containing the hash code for key.

Exceptions

Exception TypeCondition
ArgumentNullExceptionkey is null .

Description

This method is accessible only through this class or a derived class.

[Behaviors: As described above.]

[Default: If the current instance was instantiated with a specific IHashCodeProvider implementation, this method uses that hash code provider; otherwise, it uses the System.Object.GetHashCode implementation of key .]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.KeyEquals Method

protected virtual bool KeyEquals(object item, object key);

Summary

Determines whether the specified Object and the specified key in the current instance represent the same value.

Parameters

item
The Object to compare with key.
key
The key in the current instance to compare with item.

Return Value

true if item and key represent the same value; otherwise, false .

Exceptions

Exception TypeCondition
ArgumentNullExceptionitem is null .

-or-

key is null .

Description

This method is accessible only through this class or a derived class.

[Behaviors: As described above.]

[Default: If the current instance was initialized with a specified IComparer implementation, this method uses that implementation to perform the comparison; otherwise, the System.Object.Equals(System.Object) implementation of item is used.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Remove Method

public virtual void Remove(object key);

Summary

Removes the entry with the specified key from the current instance.

Parameters

key
The key of the entry to remove.

Exceptions

Exception TypeCondition
ArgumentNullExceptionkey is null .
NotSupportedExceptionThe current instance is read-only or has a fixed size.

Description

[Note: This method is implemented to support the IDictionary interface.]

[Behaviors: As described above.]

[Default: This method uses the System.Object.Equals(System.Object) implementation of key to locate it in the current instance. If key is found in the current instance, the values of both key and its associated value are set to null . If key is not found in the current instance, no exception is thrown and the current instance remains unchanged.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Synchronized Method

public static Hashtable Synchronized(Hashtable table);

Summary

Returns a synchronized (thread-safe) wrapper for the specified Hashtable.

Parameters

table
The Hashtable to synchronize.

Return Value

A synchronized (thread-safe) wrapper for table.

Exceptions

Exception TypeCondition
ArgumentNullExceptiontable is null .

Description

This method returns a new Hashtable instance that contains values equal to the values of table , and provides synchronized access to those values.

If more than one thread is to write to a Hashtable concurrently, all write operations are required to be done through this wrapper.

[Note: A Hashtable can safely support one writer and multiple readers concurrently.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.System.Collections.IEnumerable.GetEnumerator Method

IEnumerator IEnumerable.GetEnumerator();

Summary

Implemented to support the IEnumerable interface. [Note: For more information, see System.Collections.IEnumerable.GetEnumerator.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Count() Property

public virtual int Count { get; }

Summary

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

Property Value

A Int32 that specifies the number of key-and-value pairs contained in the current instance.

Description

This property is read-only.

[Behaviors: As described above.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Count() Property

int ICollection.Count { get; }

Summary

Implemented to support the ICollection interface. [Note: For more information, see System.Collections.ICollection.Count.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.IsFixedSize() Property

bool IDictionary.IsFixedSize { get; }

Summary

Implemented to support the IDictionary interface. [Note: For more information, see System.Collections.IDictionary.IsFixedSize.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.IsFixedSize() Property

public virtual bool IsFixedSize { get; }

Summary

Gets a Boolean indicating whether the current instance has a fixed size.

Property Value

true if the current instance has a fixed size; otherwise, false .

Description

This property is read-only.

[Note: Elements can be modified in, but not added to or removed from a Hashtable with a fixed size.]

[Behaviors: As described above.]

[Default: The default value of this property is false .]

[Overrides: Override this property, setting it to true , to prevent addition or removal of entries in the current instance.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.IsReadOnly() Property

bool IDictionary.IsReadOnly { get; }

Summary

Implemented to support the IDictionary interface. [Note: For more information, see System.Collections.IDictionary.IsReadOnly.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.IsReadOnly() Property

public virtual bool IsReadOnly { get; }

Summary

Gets a Boolean value indicating whether the current instance is read-only.

Property Value

true if the current instance is read-only; otherwise, false .

Description

This property is read-only.

[Note: Elements cannot be modified in, added to, or removed from a Hashtable that is read-only.]

[Behaviors: As described above.]

[Default: The default value of this property is false .]

[Overrides: Override this property, setting it to true , in order to prevent the addition, removal, or modification of entries in the current instance.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.IsSynchronized() Property

bool ICollection.IsSynchronized { get; }

Summary

Implemented to support the ICollection interface. [Note: For more information, see System.Collections.ICollection.IsSynchronized.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.IsSynchronized() Property

public virtual bool IsSynchronized { get; }

Summary

Gets a Boolean value indicating whether access to the current instance is synchronized (thread-safe).

Property Value

true if access to the current instance is synchronized (thread-safe); otherwise, false .

Description

This property is read-only.

[Note: This property is implemented to support the ICollection interface.

For more information regarding synchronization of access to a Hashtable , see System.Collections.Hashtable.Synchronized(System.Collections.Hashtable) .

]

[Behaviors: As described above.]

[Default: The default value of this property is false .]

[Overrides: Override this property, setting it to true , if thread-safety can be guaranteed for the current instance. In order to obtain this safety, use System.Collections.Hashtable.SyncRoot or System.Collections.Hashtable.Synchronized(System.Collections.Hashtable) .]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Item Property

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

Summary

Gets or sets the value in the current instance that is associated with the specified key.

Parameters

key
The key whose value to get or set.

Property Value

The value in the current instance that is associated with key. If key is not contained in the current instance, attempting to get it returns null , and attempting to set it creates a new entry using key .

Exceptions

Exception TypeCondition
ArgumentNullExceptionkey is null .
NotSupportedExceptionThe property is being set and the current instance is read-only.

The property is being set, key is not contained in the current instance, and the current instance has a fixed size.

Description

[Note: This property provides the ability to access a specific element in the current instance using the following notation: myCollection[key] .]

[Behaviors: As described above.]

[Default: If this property is being set and key is already contained in the current instance, the value associated with the old key is replaced.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Keys() Property

ICollection IDictionary.Keys { get; }

Summary

Implemented to support the IDictionary interface. [Note: For more information, see System.Collections.IDictionary.Keys.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Keys() Property

public virtual ICollection Keys { get; }

Summary

Gets a ICollection containing the keys of the current instance.

Property Value

A ICollection containing the keys of the current instance.

Description

This property is read-only.

[Behaviors: As described above.]

[Default: 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 System.Collections.Hashtable.Values method.

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

]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.SyncRoot() Property

public virtual object SyncRoot { get; }

Summary

Gets a Object that can be used to synchronize access to the current instance.

Property Value

A Object that can be used to synchronize access to the current instance.

Description

This property is read-only.

A thread is required to perform synchronized operations only on the System.Collections.Hashtable.SyncRoot of a Hashtable, not directly on the table itself. This maintains proper synchronization with any other threads concurrently modifying the table.

[Note: This property is implemented to support the ICollection interface.]

[Behaviors: As described above.]

[Default: This method returns a reference to the current instance.]

[Overrides: Override this property to return an object on which to lock when implementing a collection that wraps another collection (using a subset of it, for example). This is useful when providing synchronized access through two or more wrapper collections to the same underlying collection. Typically, this property returns a reference to the current instance.]

[Usage: Use this property to obtain a Object that can be used to synchronize access to the current instance.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.SyncRoot() Property

object ICollection.SyncRoot { get; }

Summary

Implemented to support the ICollection interface. [Note: For more information, see System.Collections.ICollection.SyncRoot.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Values() Property

public virtual ICollection Values { get; }

Summary

Gets a ICollection containing the values of the current instance.

Property Value

A ICollection containing the values of the current instance.

Description

This property is read-only.

[Behaviors: As described above.]

[Default: 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 System.Collections.Hashtable.Keys method.

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

]

See Also

System.Collections.Hashtable Class, System.Collections Namespace

Hashtable.Values() Property

ICollection IDictionary.Values { get; }

Summary

Implemented to support the IDictionary interface. [Note: For more information, see System.Collections.IDictionary.Values.]

See Also

System.Collections.Hashtable Class, System.Collections Namespace