diff --git a/doc/rationale.qbk b/doc/rationale.qbk index 6662f13e..19e8945c 100644 --- a/doc/rationale.qbk +++ b/doc/rationale.qbk @@ -92,6 +92,8 @@ So, this implementation uses a prime number for the hash table size. [h2 Equality operators] +/TODO/: This is out of date. + `operator==` and `operator!=` are not included in the standard, but I've added them as I think they could be useful and can be implemented fairly efficiently. They are specified differently to the other standard @@ -115,6 +117,8 @@ that their order can be considered part of the container's value. [h3 C++0x allocators] +/TODO/: This is out of date. + Recent drafts have included an overhaul of the allocators, but this was dependent on concepts which are no longer in the standard. [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2009/n2946.pdf n2946] @@ -124,6 +128,8 @@ a little to accomodate non-C++0x compilers. [h3 Swapping containers with unequal allocators] +/TODO/: This is out of date. + It isn't clear how to swap containers when their allocators aren't equal. This is [@http://www.open-std.org/jtc1/sc22/wg21/docs/lwg-defects.html#431 diff --git a/doc/ref.php b/doc/ref.php index 66f4d930..7094f4d7 100644 --- a/doc/ref.php +++ b/doc/ref.php @@ -60,10 +60,6 @@ EOL; - Based on chapter 23 of - the working draft of the C++ standard [n2960]. - But without the updated rules for allocators. - Template Parameters @@ -236,6 +232,9 @@ EOL; The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + If Allocator::select_on_container_copy_construction + exists and has the right signature, the allocator will be + constructed from its result. value_type is copy constructible @@ -249,12 +248,18 @@ EOL; The move constructor. - This is emulated on compilers without rvalue references. + This is implemented using Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). + + + On compilers without rvalue reference support the + emulation does not support moving without calling + boost::move if value_type is + not copyable. So, for example, you can't return the + container from a function. @@ -289,14 +294,12 @@ EOL; & The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + If Alloc::propagate_on_container_copy_assignment + exists and Alloc::propagate_on_container_copy_assignment::value + is true, the allocator is overwritten, if not the + copied elements are created using the existing + allocator. - - - On compilers without rvalue references, there is a single assignment - operator with the signature operator=() - in order to emulate move semantics. - - value_type is copy constructible @@ -308,18 +311,21 @@ EOL; & The move assignment operator. + If Alloc::propagate_on_container_move_assignment + exists and Alloc::propagate_on_container_move_assignment::value + is true, the allocator is overwritten, if not the + moved elements are created using the existing + allocator. - On compilers without rvalue references, there is a single assignment - operator with the signature operator=() - in order to emulate move semantics. + On compilers without rvalue references, this is emulated using + Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). @@ -406,6 +412,10 @@ EOL; If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. + @@ -444,6 +454,9 @@ EOL; If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. @@ -601,13 +614,10 @@ EOL; - This method is faster than erase as - it doesn't have to find the next element in the container - - a potentially costly operation. - - - As it hasn't been standardized, it's likely that this may - change in the future. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -625,10 +635,10 @@ EOL; - This method is now deprecated, use - quick_return instead. Although be - warned that as that isn't standardized yet, it could also - change. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -653,6 +663,7 @@ EOL; If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of key_equal or hasher. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -1006,6 +1017,7 @@ EOL; If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of Hash or Pred. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. diff --git a/doc/ref.xml b/doc/ref.xml index 7825de2f..a81c96c0 100644 --- a/doc/ref.xml +++ b/doc/ref.xml @@ -23,10 +23,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) An unordered associative container that stores unique values. - Based on chapter 23 of - the working draft of the C++ standard [n2960]. - But without the updated rules for allocators. - Template Parameters @@ -181,6 +177,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + If Allocator::select_on_container_copy_construction + exists and has the right signature, the allocator will be + constructed from its result. value_type is copy constructible @@ -194,12 +193,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The move constructor. - This is emulated on compilers without rvalue references. + This is implemented using Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). + + + On compilers without rvalue reference support the + emulation does not support moving without calling + boost::move if value_type is + not copyable. So, for example, you can't return the + container from a function. @@ -234,14 +239,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_set& The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + If Alloc::propagate_on_container_copy_assignment + exists and Alloc::propagate_on_container_copy_assignment::value + is true, the allocator is overwritten, if not the + copied elements are created using the existing + allocator. - - - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_set) - in order to emulate move semantics. - - value_type is copy constructible @@ -253,18 +256,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_set& The move assignment operator. + If Alloc::propagate_on_container_move_assignment + exists and Alloc::propagate_on_container_move_assignment::value + is true, the allocator is overwritten, if not the + moved elements are created using the existing + allocator. - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_set) - in order to emulate move semantics. + On compilers without rvalue references, this is emulated using + Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). @@ -344,6 +350,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. + @@ -375,6 +385,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. @@ -517,13 +530,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is faster than erase as - it doesn't have to find the next element in the container - - a potentially costly operation. - - - As it hasn't been standardized, it's likely that this may - change in the future. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -541,10 +551,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is now deprecated, use - quick_return instead. Although be - warned that as that isn't standardized yet, it could also - change. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -569,6 +579,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of key_equal or hasher. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -888,6 +899,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of Hash or Pred. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -912,10 +924,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) An unordered associative container that stores values. The same key can be stored multiple times. - Based on chapter 23 of - the working draft of the C++ standard [n2960]. - But without the updated rules for allocators. - Template Parameters @@ -1070,6 +1078,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + If Allocator::select_on_container_copy_construction + exists and has the right signature, the allocator will be + constructed from its result. value_type is copy constructible @@ -1083,12 +1094,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The move constructor. - This is emulated on compilers without rvalue references. + This is implemented using Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). + + + On compilers without rvalue reference support the + emulation does not support moving without calling + boost::move if value_type is + not copyable. So, for example, you can't return the + container from a function. @@ -1123,14 +1140,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_multiset& The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + If Alloc::propagate_on_container_copy_assignment + exists and Alloc::propagate_on_container_copy_assignment::value + is true, the allocator is overwritten, if not the + copied elements are created using the existing + allocator. - - - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_multiset) - in order to emulate move semantics. - - value_type is copy constructible @@ -1142,18 +1157,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_multiset& The move assignment operator. + If Alloc::propagate_on_container_move_assignment + exists and Alloc::propagate_on_container_move_assignment::value + is true, the allocator is overwritten, if not the + moved elements are created using the existing + allocator. - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_multiset) - in order to emulate move semantics. + On compilers without rvalue references, this is emulated using + Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). @@ -1232,6 +1250,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. + @@ -1263,6 +1285,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. @@ -1404,13 +1429,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is faster than erase as - it doesn't have to find the next element in the container - - a potentially costly operation. - - - As it hasn't been standardized, it's likely that this may - change in the future. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -1428,10 +1450,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is now deprecated, use - quick_return instead. Although be - warned that as that isn't standardized yet, it could also - change. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -1456,6 +1478,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of key_equal or hasher. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -1775,6 +1798,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of Hash or Pred. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -1805,10 +1829,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) An unordered associative container that associates unique keys with another value. - Based on chapter 23 of - the working draft of the C++ standard [n2960]. - But without the updated rules for allocators. - Template Parameters @@ -1969,6 +1989,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + If Allocator::select_on_container_copy_construction + exists and has the right signature, the allocator will be + constructed from its result. value_type is copy constructible @@ -1982,12 +2005,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The move constructor. - This is emulated on compilers without rvalue references. + This is implemented using Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). + + + On compilers without rvalue reference support the + emulation does not support moving without calling + boost::move if value_type is + not copyable. So, for example, you can't return the + container from a function. @@ -2022,14 +2051,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_map& The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + If Alloc::propagate_on_container_copy_assignment + exists and Alloc::propagate_on_container_copy_assignment::value + is true, the allocator is overwritten, if not the + copied elements are created using the existing + allocator. - - - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_map) - in order to emulate move semantics. - - value_type is copy constructible @@ -2041,18 +2068,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_map& The move assignment operator. + If Alloc::propagate_on_container_move_assignment + exists and Alloc::propagate_on_container_move_assignment::value + is true, the allocator is overwritten, if not the + moved elements are created using the existing + allocator. - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_map) - in order to emulate move semantics. + On compilers without rvalue references, this is emulated using + Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). @@ -2132,6 +2162,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. + @@ -2163,6 +2197,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. @@ -2305,13 +2342,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is faster than erase as - it doesn't have to find the next element in the container - - a potentially costly operation. - - - As it hasn't been standardized, it's likely that this may - change in the future. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -2329,10 +2363,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is now deprecated, use - quick_return instead. Although be - warned that as that isn't standardized yet, it could also - change. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -2357,6 +2391,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of key_equal or hasher. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -2717,6 +2752,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of Hash or Pred. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -2743,10 +2779,6 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) An unordered associative container that associates keys with another value. The same key can be stored multiple times. - Based on chapter 23 of - the working draft of the C++ standard [n2960]. - But without the updated rules for allocators. - Template Parameters @@ -2907,6 +2939,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The copy constructor. Copies the contained elements, hash function, predicate, maximum load factor and allocator. + If Allocator::select_on_container_copy_construction + exists and has the right signature, the allocator will be + constructed from its result. value_type is copy constructible @@ -2920,12 +2955,18 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) The move constructor. - This is emulated on compilers without rvalue references. + This is implemented using Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). + + + On compilers without rvalue reference support the + emulation does not support moving without calling + boost::move if value_type is + not copyable. So, for example, you can't return the + container from a function. @@ -2960,14 +3001,12 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_multimap& The assignment operator. Copies the contained elements, hash function, predicate and maximum load factor but not the allocator. + If Alloc::propagate_on_container_copy_assignment + exists and Alloc::propagate_on_container_copy_assignment::value + is true, the allocator is overwritten, if not the + copied elements are created using the existing + allocator. - - - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_multimap) - in order to emulate move semantics. - - value_type is copy constructible @@ -2979,18 +3018,21 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) unordered_multimap& The move assignment operator. + If Alloc::propagate_on_container_move_assignment + exists and Alloc::propagate_on_container_move_assignment::value + is true, the allocator is overwritten, if not the + moved elements are created using the existing + allocator. - On compilers without rvalue references, there is a single assignment - operator with the signature operator=(unordered_multimap) - in order to emulate move semantics. + On compilers without rvalue references, this is emulated using + Boost.Move. value_type is move constructible. - (TODO: This is not actually required in this implementation). @@ -3069,6 +3111,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. + @@ -3100,6 +3146,9 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the compiler doesn't support variadic template arguments or rvalue references, this is emulated for up to 10 arguments, with no support for rvalue references or move semantics. + Since existing `std::pair` implementations don't support + std::piecewise_construct this emulates it, + but using boost::unordered::piecewise_construct. @@ -3241,13 +3290,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is faster than erase as - it doesn't have to find the next element in the container - - a potentially costly operation. - - - As it hasn't been standardized, it's likely that this may - change in the future. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -3265,10 +3311,10 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - This method is now deprecated, use - quick_return instead. Although be - warned that as that isn't standardized yet, it could also - change. + This method was implemented because returning an iterator to + the next element from erase was expensive, but + the container has been redesigned so that is no longer the + case. So this method is now deprecated. @@ -3293,6 +3339,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of key_equal or hasher. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details. @@ -3618,6 +3665,7 @@ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) If the allocators are equal, doesn't throw an exception unless it is thrown by the copy constructor or copy assignment operator of Hash or Pred. + TODO: Update swap documentation, no longer correct. For a discussion of the behavior when allocators aren't equal see the implementation details.