Test, implement and document 'at'.

[SVN r41125]

doc/ref.xml

@@ -1641,6 +1641,22 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                 <para>Can invalidate iterators, but only if the insert causes the load factor to be greater to or equal to the maximum load factor.</para>
               </notes>
             </method>
+            <overloaded-method name="at">
+              <signature><type>T&amp;</type>
+                <parameter name="k"><paramtype>key_type const&amp;</paramtype></parameter></signature>
+              <signature cv="const"><type>T const&amp;</type>
+                <parameter name="k"><paramtype>key_type const&amp;</paramtype></parameter></signature>
+              <returns>
+                <para>A reference to <code>x.second</code> where <code>x</code> is the (unique) element whose key is equivalent to <code>k</code>.</para>
+              </returns>
+              <throws>
+                <para>An exception object of type <code>out_of_range</code> if no such element is present.</para>
+              </throws>
+              <notes>
+                <para>This is not specified in the draft standard, but that is probably an oversight. The issue has been raised in 
+                  <ulink url="http://groups.google.com/group/comp.std.c++/browse_thread/thread/ab7c22a868fd370b">comp.std.c++</ulink>.</para>
+              </notes>
+            </overloaded-method>
           </method-group>
           <method-group name="bucket interface">
             <method name="bucket_count" cv="const">

include/boost/unordered/detail/hash_table.hpp

@@ -17,6 +17,7 @@
 #include <cmath>
 #include <algorithm>
 #include <utility>
+#include <stdexcept>
 
 #include <boost/iterator.hpp>
 #include <boost/iterator/iterator_categories.hpp>

include/boost/unordered/detail/hash_table_impl.hpp

@@ -1839,6 +1839,17 @@ namespace boost {
                     return this->end();
             }
 
+            value_type& at(key_type const& k) const
+            {
+                bucket_ptr bucket = get_bucket(k);
+                local_iterator_base it = find_iterator(bucket, k);
+
+                if (it.not_finished())
+                    return *it;
+                else
+                    throw std::out_of_range("Unable to find key in unordered_map.");
+            }
+
             // equal_range
             //
             // strong exception safety, no side effects

include/boost/unordered_map.hpp

@@ -211,6 +211,16 @@ namespace boost
             return base[k].second;
         }
 
+        mapped_type& at(const key_type& k)
+        {
+            return base.at(k).second;
+        }
+
+        mapped_type const& at(const key_type& k) const
+        {
+            return base.at(k).second;
+        }
+
         // lookup
 
         iterator find(const key_type& k)

test/objects/minimal.hpp

@@ -18,6 +18,7 @@ namespace test
 namespace minimal
 {
     class copy_constructible;
+    class default_copy_constructible;
     class assignable;
     template <class T> class hash;
     template <class T> class equal_to;
@@ -36,6 +37,17 @@ namespace minimal
         copy_constructible() {}
     };
 
+    class default_copy_constructible
+    {
+    public:
+        static default_copy_constructible create() { return default_copy_constructible(); }
+        default_copy_constructible() {}
+        default_copy_constructible(default_copy_constructible const&) {}
+        ~default_copy_constructible() {}
+    private:
+        default_copy_constructible& operator=(default_copy_constructible const&);
+    };
+
     class assignable
     {
     public:

test/unordered/Jamfile.v2

@@ -25,6 +25,7 @@ test-suite unordered-tests
         [ run erase_tests.cpp ]
         [ run erase_equiv_tests.cpp ]
         [ run find_tests.cpp ]
+        [ run at_tests.cpp ]
         [ run bucket_tests.cpp ]
         [ run load_factor_tests.cpp ]
         [ run rehash_tests.cpp ]

test/unordered/compile_tests.cpp

@@ -58,6 +58,19 @@ void unordered_equivalent_test(X& r, T const& t)
     test::check_return_type<iterator>::equals(r.insert(t));
 }
 
+template <class X, class Key, class T>
+void unordered_map_functions(X&, Key const& k, T const& t)
+{
+    typedef typename X::mapped_type mapped_type;
+
+    X a;
+    test::check_return_type<mapped_type>::equals_ref(a[k]);
+    test::check_return_type<mapped_type>::equals_ref(a.at(k));
+
+    X const b = a;
+    test::check_return_type<mapped_type const>::equals_ref(b.at(k));
+}
+
 template <class X, class Key, class T, class Hash, class Pred>
 void unordered_test(X&, Key& k, T& t, Hash& hf, Pred& eq)
 {
@@ -217,6 +230,7 @@ void test1()
     unordered_unique_test(map, map_value);
     unordered_map_test(map, value, value);
     unordered_test(map, value, map_value, hash, equal_to);
+    unordered_map_functions(map, value, value);
 
     std::cout<<"Test unordered_multimap.\n";
 
@@ -279,6 +293,18 @@ void test2()
     unordered_map_test(map, assignable, copy_constructible);
     unordered_test(map, assignable, map_value, hash, equal_to);
 
+
+    boost::unordered_map<
+        test::minimal::assignable,
+        test::minimal::default_copy_constructible,
+        test::minimal::hash<test::minimal::assignable>,
+        test::minimal::equal_to<test::minimal::assignable>,
+        test::minimal::allocator<map_value_type> > map2;
+
+    test::minimal::default_copy_constructible default_copy_constructible;
+
+    unordered_map_functions(map2, assignable, default_copy_constructible);
+
     std::cout<<"Test unordered_multimap.\n";
 
     boost::unordered_multimap<