From 0856f8a32e953569712dc52229091d7ddf09ed8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ion=20Gazta=C3=B1aga?= Date: Wed, 16 Apr 2014 14:42:37 +0200 Subject: [PATCH] Documented vector's weaker exception safety guarantees. --- doc/container.qbk | 45 +++++++++++++++++++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 6 deletions(-) diff --git a/doc/container.qbk b/doc/container.qbk index 302773f..cb6eac0 100644 --- a/doc/container.qbk +++ b/doc/container.qbk @@ -799,15 +799,45 @@ versions. [endsect] +[section:vector_exception_guarantees `vector`'s exception guarantees] + +[classref ::boost::container::vector vector] does not support the strong exception guarantees +given by `std::vector` in functions like `insert`, `push_back`, `emplace`, `emplace_back`, +`resize`, `reserve` or `shrink_to_fit` for either copyable or no-throw moveable classes. +[@http://en.cppreference.com/w/cpp/utility/move_if_noexcept move_if_noexcept] is used to maintain +C++03 exception safety guarantees combined with C++11 move semantics. +This strong exception guarantee degrades the insertion performance of copyable and throw moveable types, +degrading moves to copies when such types are inserted in the vector using the aforementioned +members. + +This strong exception guarantee also precludes the possibility of using some type of +in-place reallocations that can further improve the insertion performance of `vector` See +[link container.extended_functionality.extended_allocators Extended Allocators] to know more +about these optimization. + +[classref ::boost::container::vector ::boost::container::vector] always uses move constructors/assignments +to rearrange elements in the vector and uses memory expansion mechanisms if the allocator supports them, +while offering only basic safety guarantees. It trades off exception guarantees for an improved performance. + +[endsect] + [section:Vector_bool `vector`] `vector` specialization has been quite problematic, and there have been several unsuccessful tries to deprecate or remove it from the standard. [*Boost.Container] does not implement it as there is a superior [@http://www.boost.org/libs/dynamic_bitset/ Boost.DynamicBitset] -solution. For issues with `vector` see papers -[@http://www.gotw.ca/publications/N1211.pdf vector: N1211: More Problems, Better Solutions], -[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2160.html N2160: Library Issue 96: Fixing vector], -[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2204.html N2204 A Specification to deprecate vector]. +solution. For issues with `vector` see the following papers: + +* [@http://home.roadrunner.com/~hinnant/onvectorbool.html On `vector`] +* [@http://www.gotw.ca/publications/N1211.pdf vector: N1211: More Problems, Better Solutions], +* [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2160.html N2160: Library Issue 96: Fixing vector], +* [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2204.html N2204 A Specification to deprecate vector]. + +Quotes: + +* ["['But it is a shame that the C++ committee gave this excellent data structure the name vector and + that it gives no guidance nor encouragement on the critical generic algorithms that need to be optimized for this + data structure. Consequently, few std::lib implementations go to this trouble.]] * ["['In 1998, admitting that the committee made a mistake was controversial. Since then Java has had to deprecate such significant portions of their libraries @@ -823,7 +853,7 @@ has already hurt users who have been forced to implement workarounds to disable (e.g., by using a vector and manually casting to/from bool).]] So `boost::container::vector::iterator` returns real `bool` references and works as a fully compliant container. -If you need a memory optimized version of `boost::container::vector` functionalities, please use +If you need a memory optimized version of `boost::container::vector`, please use [@http://www.boost.org/libs/dynamic_bitset/ Boost.DynamicBitset]. [endsect] @@ -947,7 +977,10 @@ use [*Boost.Container]? There are several reasons for that: [@https://svn.boost.org/trac/boost/ticket/9064 #9064], [@https://svn.boost.org/trac/boost/ticket/9092 #9092], [@https://svn.boost.org/trac/boost/ticket/9108 #9108], - [@https://svn.boost.org/trac/boost/ticket/9166 #9166], + [@https://svn.boost.org/trac/boost/ticket/9166 #9166]. + +* Added `default initialization` insertion functions to vector-like containers + with new overloads taking `default_init_t` as an argument instead of `const value_type &`. [endsect]