diff --git a/doc/container.qbk b/doc/container.qbk index f4e5824..dee04d1 100644 --- a/doc/container.qbk +++ b/doc/container.qbk @@ -8,7 +8,7 @@ [library Boost.Container [quickbook 1.7] [authors [Gaztanaga, Ion]] - [copyright 2009-2018 Ion Gaztanaga] + [copyright 2009-2026 Ion Gaztanaga] [id container] [dirname container] [purpose Containers library] @@ -172,7 +172,7 @@ Finally C++17 added support for incomplete types in `std::vector`, `std::list` a for details), but no other containers like `std::set/map/unordered_set/unordered_map`, Fortunately all [*Boost.Container] containers except -[classref boost::container::static_vector static_vector] and +[classref boost::container::static_vector static_vector], [classref boost::container::small_vector small_vector] and [classref boost::container::basic_string basic_string] are designed to support incomplete types. [classref boost::container::static_vector static_vector] and @@ -734,19 +734,21 @@ the last template parameter and defined using the utility class [classref boost::container::vector_options vector_options]. The following parameters can be configured: * [classref boost::container::growth_factor growth_factor]: the growth policy of the vector. - The rate at which the capacity of a vector grows is implementation dependent and - implementations choose exponential growth in order to meet the amortized constant time requirement for push_back. + The rate at which the capacity grows is implementation dependent and + implementations choose exponential growth in order to meet the amortized constant time requirements. A higher growth factor will make it faster as it will require less data movement, but it will have a greater memory impact (on average, more memory will be unused). A user can provide a custom implementation of the growth factor and some predefined policies are available: [classref boost::container::growth_factor_50 growth_factor_50], - [classref boost::container::growth_factor_60 growth_factor_60] (usually the default) and + [classref boost::container::growth_factor_60 growth_factor_60] (usually the default in Boost.Container) and [classref boost::container::growth_factor_100 growth_factor_100]. * [classref boost::container::stored_size stored_size]: the type that will be used to store size-related parameters inside the vector. Sometimes, when the maximum vector capacity to be used is much less than `std::size_t` capacity, it may be beneficial to use a smaller unsigned integer type to represent `size()` and `capacity()` values inside the vector, so that the size of an empty vector object is minimized and cache - performance is possibly improved. See [classref boost::container::stored_size stored_size] for more details. + performance is possibly improved. See [classref boost::container::stored_size stored_size] for more details. Note + that due to alignment issues, using a unsigned type smaller than std::size_t to store size-related parameters might + not bring any size gains and will severely limit the maximum size of the container. See the following example to see how [classref boost::container::vector_options vector_options] can be used to customize `vector`: @@ -771,10 +773,8 @@ the last template parameter and defined using the utility class does not throw or abort, undefined behavior is triggered. * [classref boost::container::stored_size stored_size]: the type that will be used to store size-related - parameters inside the vector. Sometimes, when the static size to be used is much less than `std::size_t` capacity, - it may be beneficial to use a smaller unsigned integer type to represent the `size()` value inside `static_vector`, - so that the object size of an empty vector is minimized and cache - performance is possibly improved. See [classref boost::container::stored_size stored_size] for more details. + parameters inside the vector. See `stored_size` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::stored_size stored_size] for more details. See the following example to see how [classref boost::container::static_vector_options static_vector_options] can be used to customize `static_vector`: @@ -795,19 +795,12 @@ the last template parameter and defined using the utility class and it is not affected by this option]. * [classref boost::container::growth_factor growth_factor]: the growth policy of the vector. - The rate at which the capacity of a vector grows is implementation dependent and - implementations choose exponential growth in order to meet the amortized constant time requirement for push_back. - A higher growth factor will make it faster as it will require less data movement, but it will have a greater memory - impact (on average, more memory will be unused). A user can provide a custom implementation of the growth factor and some - predefined policies are available: [classref boost::container::growth_factor_50 growth_factor_50], - [classref boost::container::growth_factor_60 growth_factor_60] and - [classref boost::container::growth_factor_50 growth_factor_100]. + See `growth_factor` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::growth_factor growth_factor] for more details. * [classref boost::container::stored_size stored_size]: the type that will be used to store size-related - parameters inside the vector. Sometimes, when the maximum vector capacity to be used is much less than - `std::size_t` capacity, it may be beneficial to use a smaller unsigned integer type to represent - `size()` and `capacity()` values inside the vector, so that the size of an empty vector object is minimized and cache - performance is possibly improved. See [classref boost::container::stored_size stored_size] for more details. + parameters inside the vector. See `stored_size` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::stored_size stored_size] for more details. See the following example to see how [classref boost::container::small_vector_options small_vector_options] can be used to customize `small_vector`: @@ -835,10 +828,8 @@ Only one of these paratemers can be specified: A value of zero means the default value. * [classref boost::container::stored_size stored_size]: the type that will be used to store size-related - parameters inside the deque. Sometimes, when the maximum deque capacity to be used is much less than - `std::size_t` capacity, it may be beneficial to use a smaller unsigned integer type to represent - positions and offsets inside the deque, so that the size of an empty deque object is minimized and cache - performance is possibly improved. See [classref boost::container::stored_size stored_size] for more details. + parameters inside the vector. See `stored_size` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::stored_size stored_size] for more details. See the following example to see how [classref boost::container::deque_options deque_options] can be @@ -855,20 +846,13 @@ The configuration for [classref boost::container::devector devector] is passed a the last template parameter and defined using the utility class [classref boost::container::devector_options devector_options]. The following parameters can be configured: -* [classref boost::container::growth_factor growth_factor]: the growth policy of the devector. - The rate at which the capacity of a devector grows is implementation dependent and - implementations choose exponential growth in order to meet the amortized constant time requirement for push_back. - A higher growth factor will make it faster as it will require less data movement, but it will have a greater memory - impact (on average, more memory will be unused). A user can provide a custom implementation of the growth factor and some - predefined policies are available: [classref boost::container::growth_factor_50 growth_factor_50], - [classref boost::container::growth_factor_60 growth_factor_60] (usually the default) and - [classref boost::container::growth_factor_100 growth_factor_100]. +* [classref boost::container::growth_factor growth_factor]: the growth policy of the vector. + See `growth_factor` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::growth_factor growth_factor] for more details. * [classref boost::container::stored_size stored_size]: the type that will be used to store size-related - parameters inside of the devector. Sometimes, when the maximum devector capacity to be used is much less than - `std::size_t` capacity, it may be beneficial to use a smaller unsigned integer type to represent - `size()` and `capacity()` values inside the devector, so that the size of an empty devector object is minimized and cache - performance is possibly improved. See [classref boost::container::stored_size stored_size] for more details. + parameters inside the vector. See `stored_size` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::stored_size stored_size] for more details. * [classref boost::container::relocate_on_66 relocate_on_XX]: load factor limit that will determine if new memory should be allocated or elements should relocated inside existing memory, when the free space @@ -882,6 +866,30 @@ used to customize `devector`: [endsect] +[section:configurable_string Configurable basic_string] + +The configuration for [classref boost::container::basic_string basic_string] is passed as +the last template parameter and defined using the utility class +[classref boost::container::string_options string_options]. The following parameters can be configured: + +* [classref boost::container::growth_factor growth_factor]: the growth policy of the vector. + See `growth_factor` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::growth_factor growth_factor] for more details. + +* [classref boost::container::stored_size stored_size]: the type that will be used to store size-related + parameters inside the vector. See `stored_size` option in [link container.configurable_containers.configurable_vector Configurable vector] + chapter and [classref boost::container::stored_size stored_size] for more details. Note that the internal + small string optimization buffer might be reduced in size if a smaller than `std::size_t` `stored_size` unsigned + type is used. + +See the following example to see how [classref boost::container::string_options string_options] can be +used to customize `string_options`: + +[import ../example/doc_custom_string.cpp] +[doc_custom_string] + +[endsect] + [endsect] [section:extended_allocators Extended functionality: Extended allocators] diff --git a/example/doc_custom_string.cpp b/example/doc_custom_string.cpp new file mode 100644 index 0000000..152fa77 --- /dev/null +++ b/example/doc_custom_string.cpp @@ -0,0 +1,66 @@ +////////////////////////////////////////////////////////////////////////////// +// +// (C) Copyright Ion Gaztanaga 2013-2013. 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) +// +// See http://www.boost.org/libs/container for documentation. +// +////////////////////////////////////////////////////////////////////////////// +//[doc_custom_string +#include + +//Make sure assertions are active +#ifdef NDEBUG +#undef NDEBUG +#endif +#include + +int main () +{ + using namespace boost::container; + + //This option specifies that a string that will use "unsigned char" as + //the type to store capacity or size internally. + typedef string_options< stored_size >::type size_option_t; + + //Size-optimized string is smaller than the default one. + typedef basic_string, void, size_option_t > size_optimized_string_t; + assert(( sizeof(size_optimized_string_t) < sizeof(basic_string) )); + + //The internal small string optimization buffer is also smaller + assert(( size_optimized_string_t().capacity() < basic_string().capacity() )); + + //Requesting capacity for more elements than representable by half of the + //"unsigned char" max (due to the need to a bit to indicate short/long representation) + //minus 1 (due to the terminating null) is an error in the size optimized string. + bool exception_thrown = false; + /*<-*/ + #ifndef BOOST_NO_EXCEPTIONS + BOOST_CONTAINER_TRY{ size_optimized_string_t v(127, '\0');} BOOST_CONTAINER_CATCH(...) { exception_thrown = true; } BOOST_CONTAINER_CATCH_END + #else + exception_thrown = true; + #endif //BOOST_NO_EXCEPTIONS + /*->*/ + //=try { size_optimized_string_t v(127, '\0'); } + //=catch(...){ exception_thrown = true; } + + assert(exception_thrown == true); + + //This option specifies that a string will increase its capacity 50% + //each time the previous capacity was exhausted. + typedef string_options< growth_factor >::type growth_50_option_t; + + //Fill the string until full capacity is reached + basic_string, void, growth_50_option_t > growth_50_string(5, 0); + const std::size_t old_cap = growth_50_string.capacity(); + growth_50_string.resize(old_cap); + + //Now insert an additional item and check the new buffer is aproximately + //50% bigger (rounding due to the null terminator might round down) + growth_50_string.push_back(1); + assert(growth_50_string.capacity() == old_cap*3/2); + + return 0; +} +//]