Add the work in progress documentation for the unordered associative containers.

[SVN r2876]

doc/Jamfile.v2

@@ -0,0 +1,9 @@
+
+#  Copyright Daniel James 2005. Use, modification, and distribution are
+#  subject to the Boost Software License, Version 1.0. (See accompanying
+#  file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+using quickbook ;
+
+xml unordered : unordered.qbk ;
+boostbook standalone : unordered ;

doc/comparison.qbk

@@ -0,0 +1,67 @@
+[section:comparison Comparison to Associative Containers]
+
+The unordered associative containers have a very similar interface to the
+associative containers. For example:
+
+    #include <boost/unordered_map.hpp>
+
+    ...
+
+    typedef ``[classref boost::unordered_map]``<std::string, int> map;
+    map x;
+    x["one"] = 1;
+    x["two"] = 2;
+    x["three"] = 3;
+
+    std::cout<<x["one"]<<"\n"; // Outputs '1'
+    std::cout<<x["missing"]<<"\n"; // Outputs '0' - the default value
+
+But a major difference is that the elements aren't ordered, so:
+
+    BOOST_FOREACH(map::value_type i, x) {
+        std::cout<<i.first<<","<<i.second<<"\n";
+    }
+
+might output:
+
+    two,2
+    one,1
+    three,3
+
+while if `std::set` was used it would be ordered lexicographically.
+
+The containers automatically grow as more elements are inserted, this can cause
+the order to change and iterators to be invalidated (unlike associative
+containers whose iterators are only invalidated when their elements are
+erased).
+
+So containers containing identical elements aren't guaranteed to
+contain them in the same order. For this reason equality and inequality
+operators (which in the STL are defined in terms of sequence equality)
+aren't available.
+
+[section Equality Predicate and Hash Functions]
+
+[/TODO: A better introduction to hash functions?]
+
+While the associative containers use an ordering relation to specify how the
+elements are stored, the unordered associative containers use an equality
+predicate and a hash function. For example [classref boost::unordered_set]
+is declared as:
+
+    template<typename Value,
+           typename Hash = ``[classref boost::hash]``<Value>, 
+           typename Pred = std::equal_to<Value>, 
+           typename Alloc = std::allocator<Value> > 
+    class ``[classref boost::unordered_set unordered_set]``;
+
+The hash function comes first as you might want to change the hash function
+but not the equality predicate, while if you were to change the behaviour
+of the equality predicate you would have to change the hash function to match
+it.
+
+For example, if you wanted to use
+
+[endsect]
+
+[endsect]

doc/intro.qbk

@@ -0,0 +1,34 @@
+[def __tr1__ [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1745.pdf
+    C++ Standard Library Technical Report]]
+[def __hash-function__ [@http://en.wikipedia.org/wiki/Hash_function
+    hash function]]
+
+[section:intro Introduction]
+
+For accessing data based on keys, the C++ standard library offers `std::set`,
+`std::map`, `std::multiset` and `std::multimap`. These are generally
+implemented using balanced binary trees so accessing data by key is
+consistently of logarithmic complexity. Which is generally okay, but not great.
+
+Also, they require their elements to be ordered, and to supply a 'less than'
+comparison object. For some data types this is impractacle, It might be slow
+to calculate, or even impossible.
+
+So the __tr1__ provides unordered associative containers. These will store data
+with no ordering, and typically allow for fast constant time access. Their
+worst case complexity is linear, but this is generally rare, and with
+care can be avoided. There are four containers to match the existing
+associate containers:
+[classref boost::unordered_set unordered_set],
+[classref boost::unordered_map unordered_map],
+[classref boost::unordered_multiset unordered_multiset] and
+[classref boost::unordered_multimap unordered_multimap].
+
+The fast lookup speeds are acheived using a __hash-function__. The basic idea
+is that a function is called for the key value, which is used to index the
+data. If this hash function is carefully chosen the different keys will usually
+get different indicies, so there will only be a very small number of keys for
+each index, so a key lookup won't have to look at many keys to find the correct
+one.
+
+[endsect]

doc/unordered.qbk

@@ -0,0 +1,18 @@
+[library Unordered Associative Containers
+    [quickbook 1.3]
+    [authors [Maitin-Shepard, Jeremy B.], [James, Daniel]]
+    [copyright 2005 Daniel James]
+    [purpose std::tr1 compliant hash containers]
+    [id unordered]
+    [dirname unordered]
+    [license
+        Distributed under the Boost Software License, Version 1.0.
+        (See accompanying file LICENSE_1_0.txt or copy at
+        [@http://www.boost.org/LICENSE_1_0.txt]
+    ]
+]
+
+[include:unordered intro.qbk]
+[include:unordered comparison.qbk]
+
+[xinclude ref.xml]