Hashtable Class

2013-01-16

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

Represents a collection of key/value pairs that are organized based on the hash code of the key.

Inheritance Hierarchy

System. . :: . .Object
System.Collections..::..Hashtable

Namespace: System.Collections
Assembly: mscorlib (in mscorlib.dll)

Syntax

'Declaration
Public Class Hashtable _
    Implements ICloneable, IDictionary, ICollection, IEnumerable

public class Hashtable : ICloneable, IDictionary, 
    ICollection, IEnumerable

public ref class Hashtable : ICloneable, 
    IDictionary, ICollection, IEnumerable

type Hashtable =  
    class
        interface ICloneable
        interface IDictionary
        interface ICollection
        interface IEnumerable
    end

public class Hashtable implements ICloneable, IDictionary, ICollection, IEnumerable

The Hashtable type exposes the following members.

Constructors

	Name	Description
	Hashtable() () () ()	Initializes a new, empty instance of the Hashtable class using the default initial capacity, load factor, hash code provider, and comparer.
	Hashtable(Int32)	Initializes a new, empty instance of the Hashtable class using the specified initial capacity, and the default load factor, hash code provider, and comparer.
	Hashtable(Int32, Int32)	Initializes a new, empty instance of the Hashtable class using the specified initial capacity and maximum load factor.

Top

Properties

	Name	Description
	Count	Gets the number of key/value pairs contained in the Hashtable.
	GrowthFactor	Gets or sets the multiplier to use to increase the Hashtable size during a rehash.
	IsFixedSize	Gets a value indicating whether the Hashtable has a fixed size.
	IsReadOnly	Gets a value indicating whether the Hashtable is read-only.
	IsSynchronized	Gets a value indicating whether access to the Hashtable is synchronized (thread safe).
	Item	Gets or sets the value associated with the specified key.
	Keys	Gets an ICollection containing the keys in the Hashtable.
	MaxLoadFactor	Gets or sets the load factor that results in a rehash with a greater number of buckets.
	SyncRoot	Gets an object that can be used to synchronize access to the Hashtable.
	Values	Gets an ICollection containing the values in the Hashtable.

Top

Methods

	Name	Description
	Add	Adds an element with the specified key and value into the Hashtable.
	Clear	Removes all elements from the Hashtable.
	Clone	Creates a shallow copy of the Hashtable.
	Contains	Determines whether the Hashtable contains a specific key.
	CopyTo	Copies the Hashtable elements to a one-dimensional Array instance at the specified index.
	Equals(Object)	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetEnumerator	Returns an IDictionaryEnumerator that iterates through the Hashtable.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	Remove	Removes the element with the specified key from the Hashtable.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Remarks

Each element is a key/value pair stored in a DictionaryEntry object. A key cannot be null Nothing nullptr unit a null reference (Nothing in Visual Basic) , but a value can be.

The objects used as keys by a Hashtable are required to override the Object..::..GetHashCode method (or the IHashCodeProvider interface) and the Object..::..Equals method (or the IComparer interface). The implementation of both methods and interfaces must handle case sensitivity the same way; otherwise, the Hashtable might behave incorrectly. For example, when creating a Hashtable, you must use the CaseInsensitiveHashCodeProvider class (or any case-insensitive IHashCodeProvider implementation) with the CaseInsensitiveComparer class (or any case-insensitive IComparer implementation).

Furthermore, these methods must produce the same results when called with the same parameters while the key exists in the Hashtable. An alternative is to use a Hashtable constructor with an IEqualityComparer parameter. If key equality were simply reference equality, the inherited implementation of Object..::..GetHashCode and Object..::..Equals would suffice.

Key objects must be immutable as long as they are used as keys in the Hashtable.

When an element is added to the Hashtable, the element is placed into a bucket based on the hash code of the key. Subsequent lookups of the key use the hash code of the key to search in only one particular bucket, thus substantially reducing the number of key comparisons required to find an element.

The load factor of a Hashtable determines the maximum ratio of elements to buckets. Smaller load factors cause faster average lookup times at the cost of increased memory consumption. The default load factor of 1.0 generally provides the best balance between speed and size. A different load factor can also be specified when the Hashtable is created.

As elements are added to a Hashtable, the actual load factor of the Hashtable increases. When the actual load factor reaches the specified load factor, the number of buckets in the Hashtable is automatically increased to the smallest prime number that is larger than twice the current number of Hashtable buckets.

Each key object in the Hashtable must provide its own hash function, which can be accessed by calling GetHash. However, any object implementing IHashCodeProvider can be passed to a Hashtable constructor, and that hash function is used for all objects in the table.

The capacity of a Hashtable is the number of elements the Hashtable can hold. As elements are added to a Hashtable, the capacity is automatically increased as required through reallocation.

Thread Safety

Hashtable is thread safe for use by multiple reader threads and a single writing thread. It is thread safe for multi-thread use when only one of the threads perform write (update) operations, which allows for lock-free reads provided that the writers are serialized to the Hashtable. To support multiple writers all operations on the Hashtable must be done through the wrapper returned by the Synchronized method, provided that there are no threads reading the Hashtable object.

Enumerating through a collection is intrinsically not a thread safe procedure. Even when a collection is synchronized, other threads can 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.

Share via