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

[section:rationale Implementation Rationale]

The intent of this library is 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 are
conformance to the standard and portability.

[h2 Data Structure]

By specifying an interface for accessing the buckets of the container the
standard pretty much requires that the hash table uses chained addressing.

It would be conceivable to write a hash table that uses another method.
For example, one could use open addressing,
and use the lookup chain to act as a bucket but there are a few problems
with this. Local iterators would be veryinefficient and may not be able to
meet the complexity requirements. Indicating when an entry is the table is
empty or deleted would be impossible without allocating extra storage -
loosing one of the advantages of open addressing. And for containers with
equivalent keys, making sure that they are adjacent would probably require a
chain of some sort anyway.

But most damaging is perhaps the
restrictions on when iterators can be invalidated. Since open addressing
degrades badly when there are a high number of collisions the implemenation
might sometimes be unable to rehash when it is essential. To avoid such
problems an implementation would need to set its maximum load factor to a
fairly low value - but the standard requires that it is initially set to 1.0.

And, of course, since the standard is written with a eye towards chained
addressing, users will be suprised if the performance doesn't reflect that.

So staying with chained addressing is inevitable.

For containers with unique keys I use a single-linked list to store the
buckets. There are other possible data structures which would allow for
some operations to be faster (such as erasing and iteration) but the gains
seem too small for the extra cost (in memory). The most commonly used
operations (insertion and lookup) would not be improved.

But for containers with equivalent keys, a single-linked list can degrade badly
when a large number of elements with equivalent keys are inserted. I think it's
reasonable to assume that users who chose to use `unordered_multiset` or
`unordered_multimap`, did so because they are likely to insert elements with
equivalent keys. So I have used an alternative data structure that doesn't
degrade, at the expense of an extra pointer per node.

[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, another is to use a power
of 2.

Using a prime number of buckets, and choosing a bucket by using the modulous
of the hash functions's result will usually give a good result. The downside
is that the modulous operation is fairly expensive.

Using a power of 2 allows for much quicker selection of the bucket
to use, but at the expense of loosing the upper bits of the hash value.
For some specially designed hash functions it is possible to do this and
still get a good result but as the containers can take arbitrary hash
functions this can't be relied on.

To avoid this a transformation could be applied to the hash function, for an
example see __wang__.  Unfortunately, a transformation like Wang's requires
knowledge of the number of bits in the hash value, so it isn't portable enough.
This leaves more expensive methods, such as Knuth's Multiplicative Method
(mentioned in Wang's article). These don't tend to work as well as taking the
modulous of a prime, and can take enough time to loose the
efficiency advantage of power of 2 hash tables.

So, this implementation uses a prime number for the hash table size.

[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]