feedc0de/boost_unordered
1
0
Fork 0
forked from boostorg/unordered
Code Pull Requests Activity

Starting to write an implementation rationale for the unordered containers, and added a warning about the quality of the documentation (i.e. that you shouldn't read it yet).

Browse Source 
[SVN r2879]
This commit is contained in:
Daniel James
2006-03-07 21:32:20 +00:00
parent 351cd6e8a1
commit d0ff815c45
2 changed files with 38 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
doc/rationale.qbk Normal file
View File

@@ -0,0 +1,32 @@
[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 unordred
containers in TR1, 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.
[section 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?).
[endsect]
[endsect]

6
doc/unordered.qbk
View File

@@ -12,7 +12,13 @@
] ]
] ]
[section Warning]
This documentation is a work in progress, and is often incomplete, incoherent
and, worst of all, incorrect. Don't take anything in it seriously.
[endsect]
[include:unordered intro.qbk] [include:unordered intro.qbk]
[include:unordered comparison.qbk] [include:unordered comparison.qbk]
[include:unordered rationale.qbk]
[xinclude ref.xml] [xinclude ref.xml]