Add quick_erase to the unordered containers. Refs #3966.

[SVN r60754]

doc/changes.qbk

@@ -117,4 +117,15 @@ First official release.
   Add missing `std` qualifier to `ptrdiff_t`.
 * Some code formatting changes to fit almost all lines into 80 characters.
 
+
+[h2 Boost 1.43.0]
+
+* [@http://svn.boost.org/trac/boost/ticket/3966 Ticket 3966]:
+  `erase_return_void` is now `quick_erase`, which is the
+  [@http://home.roadrunner.com/~hinnant/issue_review/lwg-active.html#579
+  current forerunner for resolving the slow erase by iterator], although
+  there's a strong possibility that this may change in the future. The old
+  method name remains for backwards compatibility but is considered deprecated
+  and will be removed in a future release.
+
 [endsect]

doc/ref.xml

@@ -464,8 +464,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                   When the number of elements is a lot smaller than the number of buckets
                   this function can be very inefficient as it has to search through empty
                   buckets for the next element, in order to return the iterator.
-                  As a temporary workaround, the container has the method
+                  The method <methodname>quick_erase</methodname> is faster, but has yet
-                  <methodname>erase_return_void</methodname> which will be faster.
+                  to be standardized.
                 </para>
               </notes>
             </method>
@@ -503,6 +503,30 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                 <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
               </throws>
             </method>
+            <method name="quick_erase">
+              <parameter name="position">
+                <paramtype>const_iterator</paramtype>
+              </parameter>
+              <type>void</type>
+              <description>
+                <para>Erase the element pointed to by <code>position</code>.</para>
+              </description>
+              <throws>
+                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
+                <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
+              </throws>
+              <notes>
+                <para>
+                  This method is faster than <methodname>erase</methodname> as
+                  it doesn't have to find the next element in the container -
+                  a potentially costly operation.
+                </para>
+                <para>
+                  As it hasn't been standardized, it's likely that this may
+                  change in the future.
+                </para>
+              </notes>
+            </method>
             <method name="erase_return_void">
               <parameter name="position">
                 <paramtype>const_iterator</paramtype>
@@ -517,10 +541,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               </throws>
               <notes>
                 <para>
-                  This is a temporary workaround for the inefficient
+                  This method is now deprecated, use
-                  <methodname>erase</methodname> method. Hopefully, in a future
+                  <methodname>quick_return</methodname> instead. Although be
-                  version the signature of <methodname>erase</methodname> will
+                  warned that as that isn't standardized yet, it could also
-                  be changed and this will be deprecated.
+                  change.
                 </para>
               </notes>
             </method>
@@ -1327,8 +1351,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                   When the number of elements is a lot smaller than the number of buckets
                   this function can be very inefficient as it has to search through empty
                   buckets for the next element, in order to return the iterator.
-                  As a temporary workaround, the container has the method
+                  The method <methodname>quick_erase</methodname> is faster, but has yet
-                  <methodname>erase_return_void</methodname> which will be faster.
+                  to be standardized.
                 </para>
               </notes>
             </method>
@@ -1366,6 +1390,30 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                 <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
               </throws>
             </method>
+            <method name="quick_erase">
+              <parameter name="position">
+                <paramtype>const_iterator</paramtype>
+              </parameter>
+              <type>void</type>
+              <description>
+                <para>Erase the element pointed to by <code>position</code>.</para>
+              </description>
+              <throws>
+                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
+                <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
+              </throws>
+              <notes>
+                <para>
+                  This method is faster than <methodname>erase</methodname> as
+                  it doesn't have to find the next element in the container -
+                  a potentially costly operation.
+                </para>
+                <para>
+                  As it hasn't been standardized, it's likely that this may
+                  change in the future.
+                </para>
+              </notes>
+            </method>
             <method name="erase_return_void">
               <parameter name="position">
                 <paramtype>const_iterator</paramtype>
@@ -1380,10 +1428,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               </throws>
               <notes>
                 <para>
-                  This is a temporary workaround for the inefficient
+                  This method is now deprecated, use
-                  <methodname>erase</methodname> method. Hopefully, in a future
+                  <methodname>quick_return</methodname> instead. Although be
-                  version the signature of <methodname>erase</methodname> will
+                  warned that as that isn't standardized yet, it could also
-                  be changed and this will be deprecated.
+                  change.
                 </para>
               </notes>
             </method>
@@ -2204,8 +2252,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                   When the number of elements is a lot smaller than the number of buckets
                   this function can be very inefficient as it has to search through empty
                   buckets for the next element, in order to return the iterator.
-                  As a temporary workaround, the container has the method
+                  The method <methodname>quick_erase</methodname> is faster, but has yet
-                  <methodname>erase_return_void</methodname> which will be faster.
+                  to be standardized.
                 </para>
               </notes>
             </method>
@@ -2243,6 +2291,30 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                 <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
               </throws>
             </method>
+            <method name="quick_erase">
+              <parameter name="position">
+                <paramtype>const_iterator</paramtype>
+              </parameter>
+              <type>void</type>
+              <description>
+                <para>Erase the element pointed to by <code>position</code>.</para>
+              </description>
+              <throws>
+                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
+                <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
+              </throws>
+              <notes>
+                <para>
+                  This method is faster than <methodname>erase</methodname> as
+                  it doesn't have to find the next element in the container -
+                  a potentially costly operation.
+                </para>
+                <para>
+                  As it hasn't been standardized, it's likely that this may
+                  change in the future.
+                </para>
+              </notes>
+            </method>
             <method name="erase_return_void">
               <parameter name="position">
                 <paramtype>const_iterator</paramtype>
@@ -2257,10 +2329,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               </throws>
               <notes>
                 <para>
-                  This is a temporary workaround for the inefficient
+                  This method is now deprecated, use
-                  <methodname>erase</methodname> method. Hopefully, in a future
+                  <methodname>quick_return</methodname> instead. Although be
-                  version the signature of <methodname>erase</methodname> will
+                  warned that as that isn't standardized yet, it could also
-                  be changed and this will be deprecated.
+                  change.
                 </para>
               </notes>
             </method>
@@ -3116,8 +3188,8 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                   When the number of elements is a lot smaller than the number of buckets
                   this function can be very inefficient as it has to search through empty
                   buckets for the next element, in order to return the iterator.
-                  As a temporary workaround, the container has the method
+                  The method <methodname>quick_erase</methodname> is faster, but has yet
-                  <methodname>erase_return_void</methodname> which will be faster.
+                  to be standardized.
                 </para>
               </notes>
             </method>
@@ -3155,6 +3227,30 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
                 <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
               </throws>
             </method>
+            <method name="quick_erase">
+              <parameter name="position">
+                <paramtype>const_iterator</paramtype>
+              </parameter>
+              <type>void</type>
+              <description>
+                <para>Erase the element pointed to by <code>position</code>.</para>
+              </description>
+              <throws>
+                <para>Only throws an exception if it is thrown by <code>hasher</code> or <code>key_equal</code>.</para>
+                <para>In this implementation, this overload doesn't call either function object's methods so it is no throw, but this might not be true in other implementations.</para>
+              </throws>
+              <notes>
+                <para>
+                  This method is faster than <methodname>erase</methodname> as
+                  it doesn't have to find the next element in the container -
+                  a potentially costly operation.
+                </para>
+                <para>
+                  As it hasn't been standardized, it's likely that this may
+                  change in the future.
+                </para>
+              </notes>
+            </method>
             <method name="erase_return_void">
               <parameter name="position">
                 <paramtype>const_iterator</paramtype>
@@ -3169,10 +3265,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
               </throws>
               <notes>
                 <para>
-                  This is a temporary workaround for the inefficient
+                  This method is now deprecated, use
-                  <methodname>erase</methodname> method. Hopefully, in a future
+                  <methodname>quick_return</methodname> instead. Although be
-                  version the signature of <methodname>erase</methodname> will
+                  warned that as that isn't standardized yet, it could also
-                  be changed and this will be deprecated.
+                  change.
                 </para>
               </notes>
             </method>

include/boost/unordered/unordered_map.hpp

@@ -369,6 +369,11 @@ namespace boost
             return iterator(table_.erase_range(get(first), get(last)));
         }
 
+        void quick_erase(const_iterator position)
+        {
+            table_.erase(get(position));
+        }
+
         void erase_return_void(const_iterator position)
         {
             table_.erase(get(position));
@@ -907,6 +912,11 @@ namespace boost
             return iterator(table_.erase_range(get(first), get(last)));
         }
 
+        void quick_erase(const_iterator position)
+        {
+            table_.erase(get(position));
+        }
+
         void erase_return_void(const_iterator position)
         {
             table_.erase(get(position));

include/boost/unordered/unordered_set.hpp

@@ -361,6 +361,11 @@ namespace boost
             return iterator(table_.erase_range(get(first), get(last)));
         }
 
+        void quick_erase(const_iterator position)
+        {
+            table_.erase(get(position));
+        }
+
         void erase_return_void(const_iterator position)
         {
             table_.erase(get(position));
@@ -849,6 +854,11 @@ namespace boost
             return iterator(table_.erase_range(get(first), get(last)));
         }
 
+        void quick_erase(const_iterator position)
+        {
+            table_.erase(get(position));
+        }
+
         void erase_return_void(const_iterator position)
         {
             table_.erase(get(position));

test/unordered/erase_tests.cpp

@@ -116,7 +116,7 @@ void erase_tests1(Container*,
         BOOST_TEST(x.erase(x.begin(), x.end()) == x.begin());
     }
 
-    std::cerr<<"erase_return_void(begin()).\n";
+    std::cerr<<"quick_erase(begin()).\n";
     {
         test::random_values<Container> v(1000, generator);
         Container x(v.begin(), v.end());
@@ -126,7 +126,7 @@ void erase_tests1(Container*,
             BOOST_DEDUCED_TYPENAME Container::key_type
                 key = test::get_key<Container>(*x.begin());
             std::size_t count = x.count(key);
-            x.erase_return_void(x.begin());
+            x.quick_erase(x.begin());
             --size;
             BOOST_TEST(x.count(key) == count - 1);
             BOOST_TEST(x.size() == size);
@@ -134,7 +134,7 @@ void erase_tests1(Container*,
         BOOST_TEST(x.empty());
     }
 
-    std::cerr<<"erase_return_void(random position).\n";
+    std::cerr<<"quick_erase(random position).\n";
     {
         test::random_values<Container> v(1000, generator);
         Container x(v.begin(), v.end());
@@ -155,7 +155,7 @@ void erase_tests1(Container*,
             BOOST_DEDUCED_TYPENAME Container::key_type
                 key = test::get_key<Container>(*pos);
             std::size_t count = x.count(key);
-            x.erase_return_void(pos);
+            x.quick_erase(pos);
             --size;
             if(size > 0)
                 BOOST_TEST(index == 0 ? next == x.begin() :