boost_unordered/doc/rationale.qbk

[def __wang__
    [@http://www.concentric.net/~Ttwang/tech/inthash.htm
    Thomas Wang's article on integer hash functions]]

[section:rationale Implementation Rationale]

From the start the intent of this library was to implement the unordered
containers in the draft standard, so the interface was fixed. But there are
still some implementation desicions to make. The priorities for the library are
conformance to the standard and portability.

[h2 Number of Buckets]

There are two popular methods for choosing the number of buckets in a hash
table. One is to have a prime number of buckets. This allows .... (TODO)

The other is to always use a power of two. This has a potential efficiency
advantage, since it avoids the costly modulus calculation. It also allows for ... (TODO)

For a power of two hash table to work the hash values need to be
evenly distributed for the subset of the bits it is going to use - and since
the container can take an arbitrary hash function it must do this itself.
For some methods for doing this see __wang__ (TODO: Other references?).
Unfortunately, the most effective methods require the input to be an integer
with a certain number of bits, while ``std::size_t`` can have an arbitrary
range. This leaves the more expensive methods, such as Knuth's Multiplicative
Method which don't tend to work as well as taking the modulous of a prime,
have little efficiency advantage and don't work well for (TODO: what are they called?).

[h2 Active Issues]

[h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#258
    258. Missing allocator requirement]]

Need to look into this one.

[h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#431
    431. Swapping containers with unequal allocators]]

In a fit of probably unwise enthusiasm, I implemented all the three versions
with a macro (BOOST_UNORDERED_SWAP_METHOD) to pick which one is used. As
suggested by Howard Hinnant, I set option 3 as the default. I'll probably remove
the alternative implementations before review.

[h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#518
    518. Are insert and erase stable for unordered_multiset and unordered_multimap?]]

In this implementation, erase is stable but insert is not. As long as a rehash
can change the order of the elements, insert can't be.

[h3 [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-active.html#528
    528. TR1: issue 6.19 vs 6.3.4.3/2 (and 6.3.4.5/2)]]

In the current implementation, for `unordered_set` and
`unordered_multiset`, `iterator` and `const_iterator` have the same type and
`local_iterator` and `const_local_iterator` also have the same type. This makes
it impossible to implement the header exactly as described in the synopsis, as
some member functions are overloaded by the same type.

The proposed resolution is to add a new subsection to 17.4.4:
[:An implementation shall not supply an overloaded function signature specified in any library clause if such a signature would be inherently ambiguous during overload resolution due to two library types referring to the same type.]
So I don't supply the `iterator` overloads - although this means that the
header and documentation are currently inconsistent.
This will be fixed before review submission.

[endsect]