Add documentation chapter and example code for string options.

Author: igaztanaga

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]

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 <boost/container/string.hpp>
+
+//Make sure assertions are active
+#ifdef NDEBUG
+#undef NDEBUG
+#endif
+#include <cassert>
+
+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<unsigned char> >::type size_option_t;
+
+   //Size-optimized string is smaller than the default one.
+   typedef basic_string<char, std::char_traits<char>, void, size_option_t > size_optimized_string_t;
+   assert(( sizeof(size_optimized_string_t) < sizeof(basic_string<char>) ));
+
+   //The internal small string optimization buffer is also smaller
+   assert(( size_optimized_string_t().capacity() < basic_string<char>().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<growth_factor_50> >::type growth_50_option_t;
+
+   //Fill the string until full capacity is reached
+   basic_string<char, std::char_traits<char>, 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;
+}
+//]