</section>
-<!-- Sect1 03 : Interacting with C -->
+<!-- Sect1 03 : Unordered Associative -->
+<section xml:id="std.containers.unordered" xreflabel="Unordered">
+ <info><title>Unordered Associative</title></info>
+ <?dbhtml filename="unordered_associative.html"?>
+
+ <section xml:id="containers.unordered.hash" xreflabel="Hash">
+ <info><title>Hash Code</title></info>
+
+ <section xml:id="containers.unordered.cache" xreflabel="Cache">
+ <info><title>Hash Code Caching Policy</title></info>
+
+ <para>
+ The unordered containers in libstdc++ may cache the hash code for each
+ element alongside the element itself. In some cases not recalculating
+ the hash code every time it's needed can improve performance, but the
+ additional memory overhead can also reduce performance, so whether an
+ unordered associative container caches the hash code or not depends on
+ a number of factors. The caching policy for GCC 4.8 is described below.
+ </para>
+ <para>
+ The C++ standard requires that <code>erase</code> and <code>swap</code>
+ operations must not throw exceptions. Those operations might need an
+ element's hash code, but cannot use the hash function if it could
+ throw.
+ This means the hash codes will be cached unless the hash function
+ has a non-throwing exception specification such as <code>noexcept</code>
+ or <code>throw()</code>.
+ </para>
+ <para>
+ Secondly, libstdc++ also needs the hash code in the implementation of
+ <code>local_iterator</code> and <code>const_local_iterator</code> in
+ order to know when the iterator has reached the end of the bucket.
+ This means that the local iterator types will embed a copy of the hash
+ function when possible.
+ Because the local iterator types must be DefaultConstructible and
+ CopyAssignable, if the hash function type does not model those concepts
+ then it cannot be embedded and so the hash code must be cached.
+ Note that a hash function might not be safe to use when
+ default-constructed (e.g if it a function pointer) so a hash
+ function that is contained in a local iterator won't be used until
+ the iterator is valid, so the hash function has been copied from a
+ correctly-initialized object.
+ </para>
+ <para>
+ If the hash function is non-throwing, DefaultConstructible and
+ CopyAssignable then libstdc++ doesn't need to cache the hash code for
+ correctness, but might still do so for performance if computing a
+ hash code is an expensive operation, as it may be for arbitrarily
+ long strings.
+ As an extension libstdc++ provides a trait type to describe whether
+ a hash function is fast. By default hash functions are assumed to be
+ fast unless the trait is specialized for the hash function and the
+ trait's value is false, in which case the hash code will always be
+ cached.
+ The trait can be specialized for user-defined hash functions like so:
+ </para>
+ <programlisting>
+ #include <unordered_set>
+
+ struct hasher
+ {
+ std::size_t operator()(int val) const noexcept
+ {
+ // Some very slow computation of a hash code from an int !
+ ...
+ }
+ }
+
+ namespace std
+ {
+ template<>
+ struct __is_fast_hash<hasher> : std::false_type
+ { };
+ }
+ </programlisting>
+ </section>
+</section>
+
+</section>
+
+<!-- Sect1 04 : Interacting with C -->
<section xml:id="std.containers.c" xreflabel="Interacting with C"><info><title>Interacting with C</title></info>
<?dbhtml filename="containers_and_c.html"?>
projects / gcc.git / commitdiff