 

Category: containers   Component type: concept 
Description
A Hashed Associative Container is an AssociativeContainer whose implementation is a hash table. [1] The elements of a Hashed Associative Container are not guaranteed to be in any meaningful order; in particular, they are not sorted. The worst case complexity of most operations on Hashed Associative Containers is linear in the size of the container, but the average case complexity is constant time; this means that for applications where values are simply stored and retrieved, and where ordering is unimportant, Hashed Associative Containers are usually much faster than Sorted Associative Containers.
Refinement of
AssociativeContainer
Associated types
The following new types are introduced, in addition to the types defined in the AssociativeContainer requirements.
Hash function  X::hasher  A type that is a model of HashFunction. X::hasher 's argument type must be X::key_type . 
Key equal  X::key_equal  A BinaryPredicate whose argument type is X::key_type . An object of type key_equal returns true if its arguments are the same key, and false otherwise. X::key_equal must be an equivalence relation. 
Notation
X  A type that is a model of Hashed Associative Container 
a  Object of type X 
t  Object of type X::value_type 
k  Object of type X::key_type 
p , q  Object of type X::iterator 
n  Object of type X::size_type 
h  Object of type X::hasher 
c  Object of type X::key_equal 
Definitions
A hash function for a Hashed Associative Container X
is a UnaryFunction whose argument type is X::key_type
and whose return type is size_t
. A hash function must be deterministic (that is, it must always return the same value whenever it is called with the same argument), but return values of the hash function should be as uniform as possible: ideally, no two keys will hash to the same value. [2]
Elements in a Hashed Associative Container are organized into buckets. A Hashed Associative Container uses the value of the hash function to determine which bucket an element is assigned to.
The number of elements in a Hashed Associative Container divided by the number of buckets is called the load factor. A Hashed Associative Container with a small load factor is faster than one with a large load factor.
Valid expressions
In addition to the expressions defined in AssociativeContainer, the following expressions must be valid.
Name  Expression  Type requirements  Return type 
Default constructor    
Constructor with bucket count    
Constructor with hash function    
Constructor with key equal    
Hash function  a.hash_funct()   X::hasher 
Key equal  a.key_eq()   X::key_equal 
Erase key  a.erase(k)   size_type 
Erase element  a.erase(p)   void 
Erase range  a.erase(p, q)   void 
Find  a.find(k)   iterator if a is mutable, otherwise const_iterator 
Count  a.count(k)   size_type 
Equal range  a.equal_range(k)   pair<iterator, iterator> if a is mutable, otherwise pair<const_iterator, const_iterator> . 
Bucket count  a.bucket_count()   X::size_type 
Resize  a.resize(n)   void 
Expression semantics
Name  Expression  Precondition  Semantics  Postcondition 
Default constructor    Creates an empty container, using hasher() as the hash function and key_equal() as the key equality function.  The size of the container is 0 . The bucket count is an unspecified default value. The hash function is hasher() , and the key equality function is key_equal() . 
Constructor with bucket count    Creates an empty container with at least n buckets, using hasher() as the hash function and key_equal() as the key equality function.  The size of the container is 0 . The bucket count is greater than or equal to n . The hash function is hasher() , and the key equality function is key_equal() . 
Constructor with hash function    Creates an empty container with at least n buckets, using h as the hash function and key_equal() as the key equality function.  The size of the container is 0 . The bucket count is greater than or equal to n . The hash function is h , and the key equality function is key_equal() . 
Constructor with key equal    Creates an empty container with at least n buckets, using h as the hash function and k as the key equality function.  The size of the container is 0 . The bucket count is greater than or equal to n . The hash function is h , and the key equality function is k . 
Hash function  a.hash_funct()   Returns the hash function used by a .  
Key equal  a.key_eq()   Returns the key equal function used by a .  
Erase key  a.erase(k)   Destroys all elements whose key is the same as k , and removes them from a . [2] The return value is the number of elements that were erased, i.e. the old value of a.count(k) .  a.size() is decremented by a.count(k) . a contains no elements with key k . 
Erase element  a.erase(p)  p is a dereferenceable iterator in a .  Destroys the element pointed to by p , and removes it from a .  a.size() is decremented by 1. 
Erase range  a.erase(p, q)  [p, q) is a valid range in a .  Destroys the elements in the range [p,q) and removes them from a .  a.size() is decremented by the distance from i to j . 
Find  a.find(k)   Returns an iterator pointing to an element whose key is the same as k , or a.end() if no such element exists.  Either the return value is a.end() , or else the return value has a key that is the same as k . 
Count  a.count(k)   Returns the number of elements in a whose keys are the same as k .  
Equal range  a.equal_range(k)   Returns a pair P such that [P.first, P.second) is a range containing all elements in a whose keys are the same as k . [3] If no elements have the same key as k , the return value is an empty range.  The distance between P.first and P.second is equal to a.count(k) . If p is a dereferenceable iterator in a , then either a lies in the range [P.first, P.second) , or else *a has a key that is not the same as k . 
Bucket count  a.bucket_count()   Returns the number of buckets in a .  
Resize  a.resize(n)   Increases the bucket count of a .  The bucket count of a will be at least n . All iterators pointing to element in a will remain valid. [3] 
Complexity guarantees
The default constructor, constructor with bucket count, constructor with hash function, and constructor with key equal, are all amortized constant time.
Hash Function and Key Equal are amortized constant time.
Average complexity for Erase Key is O(count(k))
. Worst case is linear in the size of the container.
Erase Element is amortized constant time.
Average complexity for Erase Range is O(N)
, where N
is the length of the range being erased. Worse case is linear in the size of the container.
Average complexity for Find is constant time. Worst case is linear in the size of the container.
Average complexity for Equal Range is O(count(k))
. Worst case is linear in the size of the container.
Average complexity for Count is O(count(k))
. Worst case is linear in the size of the container.
Bucket Count is amortized constant time.
Resize is linear in the size of the container.
Invariants
Models
Notes
[1] There is an extensive literature dealing with hash tables. See, for example, section 6.4 of Knuth. (D. E. Knuth, The Art of Computer Programming. Volume 3: Sorting and Searching. AddisonWesley, 1975.)
[2] If the hash function is poor (that is, if many different keys hash to the same value) then this will hurt performance. The worst case is where every key hashes to the same value; in this case, runtime complexity of most Hashed Associative Container operations will be linear in the size of the container.
[3] Resizing does not invalidate iterators; however, it does not necessarily preserve the ordering relation between iterators. That is, if i
and j
are iterators that point into a Hashed Associative Container such that i
comes immediately before j
, then there is no guarantee that i
will still come immediately before j
after the container is resized. The only guarantee about about the ordering of elements is the contiguous storage invariant: elements with the same key are always adjacent to each other.
See also
AssociativeContainer, SortedAssociativeContainer, UniqueHashedAssociativeContainer, MultipleHashedAssociativeContainer,