Serves as the default hash function.
Assembly: mscorlib (in mscorlib.dll)
A hash code is a numeric value that is used to insert and identify an object in a hash-based collection such as the Dictionary<TKey, TValue> class, the Hashtable class, or a type derived from the DictionaryBase class. The method provides this hash code for algorithms that need quick checks of object equality.
For information about how hash codes are used in hash tables and for some additional hash code algorithms, see the Hash Function entry in Wikipedia.
Two objects that are equal return hash codes that are equal. However, the reverse is not true: equal hash codes do not imply object equality, because different (unequal) objects can have identical hash codes. Furthermore, the .NET Framework does not guarantee the default implementation of the method, and the value this method returns may differ between .NET Framework versions and platforms, such as 32-bit and 64-bit platforms. For these reasons, do not use the default implementation of this method as a unique object identifier for hashing purposes. Two consequences follow from this:
You should not assume that equal hash codes imply object equality.
You should never persist or use a hash code outside the application domain in which it was created, because the same object may hash across application domains, processes, and platforms.
A hash code is intended for efficient insertion and lookup in collections that are based on a hash table. A hash code is not a permanent value. For this reason:
The method can be overridden by a derived type. If is not overridden, hash codes for reference types are computed by calling the method of the base class, which computes a hash code based on an object's reference; for more information, see RuntimeHelpers::GetHashCode. In other words, two objects for which the ReferenceEquals method returns true have identical hash codes. If value types do not override , the ValueType::GetHashCode method of the base class uses reflection to compute the hash code based on the values of the type's fields. In other words, value types whose fields have equal values have equal hash codes. For more information about overriding , see the "Notes to Inheritors" section.
If you override the method, you should also override Equals, and vice versa. If your overridden Equals method returns true when two objects are tested for equality, your overridden method must return the same value for the two objects.
If an object that is used as a key in a hash table does not provide a useful implementation of , you can specify a hash code provider by supplying an IEqualityComparer implementation to one of the overloads of the Hashtable class constructor.
Notes for the Windows Runtime
When you call the method on a class in the Windows Runtime, it provides the default behavior for classes that don’t override . This is part of the support that the .NET Framework provides for the Windows Runtime (see .NET Framework Support for Windows Store Apps and Windows Runtime). Classes in the Windows Runtime don’t inherit Object, and currently don’t implement a . However, they appear to have ToString, Equals(Object), and methods when you use them in your C# or Visual Basic code, and the .NET Framework provides the default behavior for these methods.
Windows Runtime classes that are written in C# or Visual Basic can override the method.
A hash function is used to quickly generate a number (hash code) that corresponds to the value of an object. Hash functions are usually specific to each type and, for uniqueness, must use at least one of the instance fields as input. Hash codes should not be computed by using the values of static fields.
For classes derived from Object, the GetHashCode method can delegate to the base class implementation only if the derived class defines equality to be reference equality. The default implementation of for reference types returns a hash code that is equivalent to the one returned by the RuntimeHelpers::GetHashCode(Object) method. You can override for immutable reference types. In general, for mutable reference types, you should override only if:
You can compute the hash code from fields that are not mutable; or
You can ensure that the hash code of a mutable object does not change while the object is contained in a collection that relies on its hash code.
Otherwise, you might think that the mutable object is lost in the hash table. If you do choose to override for a mutable reference type, your documentation should make it clear that users of your type should not modify object values while the object is stored in a hash table.
For value types, ValueType::GetHashCode provides a default hash code implementation that uses reflection. You should consider overriding it for better performance.
For more information and examples that compute hash codes in a variety of ways, see the Examples section.
A hash function must have the following properties:
If two objects compare as equal, the method for each object must return the same value. However, if two objects do not compare as equal, the methods for the two objects do not have to return different values.
The method for an object must consistently return the same hash code as long as there is no modification to the object state that determines the return value of the object's Equals method. Note that this is true only for the current execution of an application, and that a different hash code can be returned if the application is run again.
For the best performance, a hash function should generate an even distribution for all input, including input that is heavily clustered. An implication is that small modifications to object state should result in large modifications to the resulting hash code for best hash table performance.
Hash functions should be inexpensive to compute.
The method should not throw exceptions.
For example, the implementation of the GetHashCode method provided by the String class returns identical hash codes for identical string values. Therefore, two String objects return the same hash code if they represent the same string value. Also, the method uses all the characters in the string to generate reasonably randomly distributed output, even when the input is clustered in certain ranges (for example, many users might have strings that contain only the lower 128 ASCII characters, even though a string can contain any of the 65,535 Unicode characters).
Providing a good hash function on a class can significantly affect the performance of adding those objects to a hash table. In a hash table with keys that provide a good implementation of a hash function, searching for an element takes constant time (for example, an O(1) operation). In a hash table with a poor implementation of a hash function, the performance of a search depends on the number of items in the hash table (for example, an O(n) operation, where n is the number of items in the hash table). A malicious user can input data that increases the number of collisions, which can significantly degrade the performance of applications that depend on hash tables, under the following conditions:
When hash functions produce frequent collisions.
When a large proportion of objects in a hash table produce hash codes that are equal or approximately equal to one another.
When users input the data from which the hash code is computed.
One of the simplest ways to compute a hash code for a numeric value that has the same or a smaller range than the Int32 type is to simply return that value. The following example shows such an implementation for a Number structure.
Frequently, a type has multiple data fields that can participate in generating the hash code. One way to generate a hash code is to combine these fields using an XOR (eXclusive OR) operation, as shown in the following example.
The previous example returns the same hash code for (n1, n2) and (n2, n1), and so may generate more collisions than are desirable. A number of solutions are available so that hash codes in these cases are not identical. One is to return the hash code of a Tuple object that reflects the order of each field. The following example shows a possible implementation that uses the Tuple<T1, T2> class. Note, though, that the performance overhead of instantiating a Tuple object may significantly impact the overall performance of an application that stores large numbers of objects in hash tables.
A second alternative solution involves weighting the individual hash codes by left-shifting the hash codes of successive fields by two or more bits. Optimally, instead of being discarded, bits shifted beyond bit 31 should wrap around rather than be discarded. Since bits are discarded by the left-shift operators in both C# and Visual Basic, this requires creating a left shift-and-wrap method like the following:
The following example then uses this shift-and-wrap method to compute the hash code of the Point structure used in the previous examples.