Description

The class template hashtable is an intrusive hash table container, that is used to construct intrusive unordered_set and unordered_multiset containers. The no-throw guarantee holds only, if the Equal object and Hasher don't throw.

hashtable is a semi-intrusive container: each object to be stored in the container must contain a proper hook, but the container also needs additional auxiliary memory to work: hashtable needs a pointer to an array of type `bucket_type` to be passed in the constructor. This bucket array must have at least the same lifetime as the container. This makes the use of hashtable more complicated than purely intrusive containers. `bucket_type` is default-constructible, copyable and assignable

The template parameter T is the type to be managed by the container. The user can specify additional options and if no options are provided default options are used.

The container supports the following options: base_hook<>/member_hook<>/value_traits<>, constant_time_size<>, size_type<>, hash<> and equal<>bucket_traits<>, power_2_buckets<>, cache_begin<> and incremental<>.

hashtable only provides forward iterators but it provides 4 iterator types: iterator and const_iterator to navigate through the whole container and local_iterator and const_local_iterator to navigate through the values stored in a single bucket. Local iterators are faster and smaller.

It's not recommended to use non constant-time size hashtables because several key functions, like "empty()", become non-constant time functions. Non constant_time size hashtables are mainly provided to support auto-unlink hooks.

hashtables, does not make automatic rehashings nor offers functions related to a load factor. Rehashing can be explicitly requested and the user must provide a new bucket array that will be used from that moment.

Since no automatic rehashing is done, iterators are never invalidated when inserting or erasing elements. Iterators are only invalidated when rehashing.

Requires: Disposer::operator()(pointer) shouldn't throw Cloner should yield to nodes that compare equal and produce the same hash than the original node.

Effects: Erases all the elements from *this calling Disposer::operator()(pointer), clones all the elements from src calling Cloner::operator()(const_reference ) and inserts them on *this. The hash function and the equality predicate are copied from the source.

If store_hash option is true, this method does not use the hash function.

If any operation throws, all cloned elements are unlinked and disposed calling Disposer::operator()(pointer).

Throws: If the internal hasher or the equality functor throws. Basic guarantee.

Note: Does not affect the validity of iterators and references. No copy-constructors are called.

std::pair<iterator,bool>insert_unique(reference value);

Requires: value must be an lvalue

Effects: Tries to inserts value into the unordered_set.

Returns: If the value is not already present inserts it and returns a pair containing the iterator to the new value and true. If there is an equivalent value returns a pair containing an iterator to the already present value and false.

Complexity: Average case O(1), worst case O(this->size()).

Throws: If the internal hasher or the equality functor throws. Strong guarantee.

Note: Does not affect the validity of iterators and references. No copy-constructors are called.

template<typename Iterator>voidinsert_unique(Iterator b,Iterator e);

Requires: Dereferencing iterator must yield an lvalue of type value_type.

Effects: Equivalent to this->insert_unique(t) for each element in [b, e).

Requires: "hash_func" must be a hash function that induces the same hash values as the stored hasher. The difference is that "hash_func" hashes the given key instead of the value_type.

"equal_func" must be a equality function that induces the same equality as key_equal. The difference is that "equal_func" compares an arbitrary key with the contained values.

Effects: Checks if a value can be inserted in the unordered_set, using a user provided key instead of the value itself.

Returns: If there is an equivalent value returns a pair containing an iterator to the already present value and false. If the value can be inserted returns true in the returned pair boolean and fills "commit_data" that is meant to be used with the "insert_commit" function.

Complexity: Average case O(1), worst case O(this->size()).

Throws: If hash_func or equal_func throw. Strong guarantee.

Notes: This function is used to improve performance when constructing a value_type is expensive: if there is an equivalent value the constructed object must be discarded. Many times, the part of the node that is used to impose the hash or the equality is much cheaper to construct than the value_type and this function offers the possibility to use that the part to check if the insertion will be successful.

If the check is successful, the user can construct the value_type and use "insert_commit" to insert the object in constant-time.

"commit_data" remains valid for a subsequent "insert_commit" only if no more objects are inserted or erased from the unordered_set.

Requires: value must be an lvalue of type value_type. commit_data must have been obtained from a previous call to "insert_check". No objects should have been inserted or erased from the unordered_set between the "insert_check" that filled "commit_data" and the call to "insert_commit".

Effects: Inserts the value in the unordered_set using the information obtained from the "commit_data" that a previous "insert_check" filled.

Returns: An iterator to the newly inserted object.

Complexity: Constant time.

Throws: Nothing.

Notes: This function has only sense if a "insert_check" has been previously executed to fill "commit_data". No value should be inserted or erased between the "insert_check" and "insert_commit" calls.

After a successful rehashing insert_commit_data remains valid.

voiderase(const_iterator i);

Effects: Erases the element pointed to by i.

Complexity: Average case O(1), worst case O(this->size()).

Throws: Nothing.

Note: Invalidates the iterators (but not the references) to the erased element. No destructors are called.

Requires: new_buckets must be a pointer to a new bucket array or the same as the old bucket array. new_size is the length of the the array pointed by new_buckets. If new_buckets == this->bucket_pointer() n can be bigger or smaller than this->bucket_count(). 'new_bucket_traits' copy constructor should not throw.

Effects: Updates the internal reference with the new bucket erases the values from the old bucket and inserts then in the new one. Bucket traits hold by *this is assigned from new_bucket_traits. If the container is configured as incremental<>, the split bucket is set to the new bucket_len().

If store_hash option is true, this method does not use the hash function.

Effects: Returns the nearest new bucket count optimized for the container that is bigger or equal than n. This suggestion can be used to create bucket arrays with a size that will usually improve container's performance. If such value does not exist, the higher possible value is returned.

Effects: Returns the nearest new bucket count optimized for the container that is smaller or equal than n. This suggestion can be used to create bucket arrays with a size that will usually improve container's performance. If such value does not exist, the lowest possible value is returned.