forked from boostorg/container
- Add configuration options to vector
- Cleanup tree configuration options
This commit is contained in:
Ion Gaztañaga committed
1 parent
82abe673fc
commit
2802a1f50d
26 files changed
+1122
-511
No files matched your search
+2
-1
@@ -40,7 +40,8 @@ doxygen autodoc
|
||||
\"BOOST_RV_REF_END_IF_CXX11=&&\" \\
|
||||
\"BOOST_COPY_ASSIGN_REF(T)=const T &\" \\
|
||||
\"BOOST_FWD_REF(a)=a &&\" \\
|
||||
\"BOOST_INTRUSIVE_OPTION_CONSTANT(OPTION_NAME, TYPE, VALUE, CONSTANT_NAME) = template<TYPE VALUE> struct OPTION_NAME{};\" \\
|
||||
\"BOOST_INTRUSIVE_OPTION_CONSTANT(OPTION_NAME, TYPE, VALUE, CONSTANT_NAME) = template<TYPE VALUE> struct OPTION_NAME{};\" \\
|
||||
\"BOOST_INTRUSIVE_OPTION_TYPE(OPTION_NAME, TYPE, TYPEDEF_EXPR, TYPEDEF_NAME) = template<class TYPE> struct OPTION_NAME{};\" \\
|
||||
\"BOOST_CONTAINER_DOC1ST(T1, T2)=T1\" \\
|
||||
\"BOOST_CONTAINER_DOCIGN(T) \"\\
|
||||
\"BOOST_CONTAINER_DOCONLY(T)=T\"\\
|
||||
|
||||
+101
-74
@@ -8,7 +8,7 @@
|
||||
[library Boost.Container
|
||||
[quickbook 1.5]
|
||||
[authors [Gaztanaga, Ion]]
|
||||
[copyright 2009-2015 Ion Gaztanaga]
|
||||
[copyright 2009-2017 Ion Gaztanaga]
|
||||
[id container]
|
||||
[dirname container]
|
||||
[purpose Containers library]
|
||||
@@ -31,10 +31,13 @@ that don't comply with the latest C++ standard.
|
||||
|
||||
In short, what does [*Boost.Container] offer?
|
||||
|
||||
* Move semantics are implemented, including move emulation for pre-C++11 compilers.
|
||||
* New advanced features (e.g. placement insertion, recursive containers) are present.
|
||||
* Emplacement and move semantics are implemented, including emulation for pre-C++11 compilers.
|
||||
* Polymorphic allocators and memory resources, including implementation and emulation for pre-C++17 compilers
|
||||
* New advanced features (e.g. recursive containers, configuration options for containers) are present.
|
||||
* Containers support stateful allocators and are compatible with [*Boost.Interprocess]
|
||||
(they can be safely placed in shared memory).
|
||||
* Users obtain a more uniform performance across all plataforms,
|
||||
including [link container.main_features.scary_iterators SCARY iterators].
|
||||
* The library offers new useful containers:
|
||||
* [classref boost::container::flat_map flat_map],
|
||||
[classref boost::container::flat_set flat_set],
|
||||
@@ -44,6 +47,12 @@ In short, what does [*Boost.Container] offer?
|
||||
searches.
|
||||
* [classref boost::container::stable_vector stable_vector]: a std::list and std::vector hybrid
|
||||
container: vector-like random-access iterators and list-like iterator stability in insertions and erasures.
|
||||
* [classref boost::container::static_vector static_vector ]: a vector-like container that internally embeds
|
||||
(statically allocates) all needed memory up to the maximum capacity. Maximum capacity can't be increased and
|
||||
it's specified at compile time.
|
||||
* [classref boost::container::small_vector small_vector ]: a vector-like container that internally embeds
|
||||
(statically allocates) a minimum amount of memory, but dynamically allocates elements when capacity
|
||||
has to be increased. This minimum capacity is specified at compile time.
|
||||
* [classref boost::container::slist slist]: the classic pre-standard singly linked list implementation
|
||||
offering constant-time `size()`. Note that C++11 `forward_list` has no `size()`.
|
||||
|
||||
@@ -159,9 +168,11 @@ unless specifically allowed for that component]].
|
||||
|
||||
Fortunately all [*Boost.Container] containers except
|
||||
[classref boost::container::static_vector static_vector] and
|
||||
[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] is special because
|
||||
it statically allocates memory for `value_type` and this requires complete types and
|
||||
[classref boost::container::static_vector static_vector] and
|
||||
[classref boost::container::small_vector small_vector] are special because
|
||||
they statically allocates memory for `value_type` and this requires complete types.
|
||||
[classref boost::container::basic_string basic_string] implements Small String Optimization which
|
||||
also requires complete types.
|
||||
|
||||
@@ -533,7 +544,7 @@ stateful allocators, etc.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:extended_functionality Extended functionality]
|
||||
[section:extended_functionality Extended functionality: Basic extensions]
|
||||
|
||||
[section:default_initialialization Default initialization for vector-like containers]
|
||||
|
||||
@@ -569,46 +580,6 @@ times.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:configurable_tree_based_associative_containers Configurable tree-based associative ordered containers]
|
||||
|
||||
[classref boost::container::set set], [classref boost::container::multiset multiset],
|
||||
[classref boost::container::map map] and [classref boost::container::multimap multimap] associative containers
|
||||
are implemented as binary search trees which offer the needed complexity and stability guarantees required by the
|
||||
C++ standard for associative containers.
|
||||
|
||||
[*Boost.Container] offers the possibility to configure at compile time some parameters of the binary search tree
|
||||
implementation. This configuration is passed as the last template parameter and defined using the utility class
|
||||
[classref boost::container::tree_assoc_options tree_assoc_options].
|
||||
|
||||
The following parameters can be configured:
|
||||
|
||||
* The underlying [*tree implementation] type ([classref boost::container::tree_type tree_type]).
|
||||
By default these containers use a red-black tree but the user can use other tree types:
|
||||
* [@http://en.wikipedia.org/wiki/Red%E2%80%93black_tree Red-Black Tree]
|
||||
* [@http://en.wikipedia.org/wiki/Avl_trees AVL tree]
|
||||
* [@http://en.wikipedia.org/wiki/Scapegoat_tree Scapegoat tree]. In this case Insertion and Deletion
|
||||
are amortized O(log n) instead of O(log n).
|
||||
* [@http://en.wikipedia.org/wiki/Splay_tree Splay tree]. In this case Searches, Insertions and Deletions
|
||||
are amortized O(log n) instead of O(log n).
|
||||
|
||||
* Whether the [*size saving] mechanisms are used to implement the tree nodes
|
||||
([classref boost::container::optimize_size optimize_size]). By default this option is activated and is only
|
||||
meaningful to red-black and avl trees (in other cases, this option will be ignored).
|
||||
This option will try to put rebalancing metadata inside the "parent" pointer of the node if the pointer
|
||||
type has enough alignment. Usually, due to alignment issues, the metadata uses the size of a pointer yielding
|
||||
to four pointer size overhead per node, whereas activating this option usually leads to 3 pointer size overhead.
|
||||
Although some mask operations must be performed to extract
|
||||
data from this special "parent" pointer, in several systems this option also improves performance due to the
|
||||
improved cache usage produced by the node size reduction.
|
||||
|
||||
See the following example to see how [classref boost::container::tree_assoc_options tree_assoc_options] can be
|
||||
used to customize these containers:
|
||||
|
||||
[import ../example/doc_custom_tree.cpp]
|
||||
[doc_custom_tree]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:constant_time_range_splice Constant-time range splice for `(s)list`]
|
||||
|
||||
In the first C++ standard `list::size()` was not required to be constant-time,
|
||||
@@ -647,7 +618,81 @@ then the operation is constant time, even with an O(1) size.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:extended_allocators Extended allocators]
|
||||
[endsect]
|
||||
|
||||
[section:configurable_containers Extended functionality: Configurable containers]
|
||||
|
||||
[section:configurable_tree_based_associative_containers Configurable tree-based associative ordered containers]
|
||||
|
||||
[classref boost::container::set set], [classref boost::container::multiset multiset],
|
||||
[classref boost::container::map map] and [classref boost::container::multimap multimap] associative containers
|
||||
are implemented as binary search trees which offer the needed complexity and stability guarantees required by the
|
||||
C++ standard for associative containers.
|
||||
|
||||
[*Boost.Container] offers the possibility to configure at compile time some parameters of the binary search tree
|
||||
implementation. This configuration is passed as the last template parameter and defined using the utility class
|
||||
[classref boost::container::tree_assoc_options tree_assoc_options]. The following parameters can be configured:
|
||||
|
||||
* The underlying [*tree implementation] type ([classref boost::container::tree_type tree_type]).
|
||||
By default these containers use a red-black tree but the user can use other tree types:
|
||||
* [@http://en.wikipedia.org/wiki/Red%E2%80%93black_tree Red-Black Tree]
|
||||
* [@http://en.wikipedia.org/wiki/Avl_trees AVL tree]
|
||||
* [@http://en.wikipedia.org/wiki/Scapegoat_tree Scapegoat tree]. In this case Insertion and Deletion
|
||||
are amortized O(log n) instead of O(log n).
|
||||
* [@http://en.wikipedia.org/wiki/Splay_tree Splay tree]. In this case Searches, Insertions and Deletions
|
||||
are amortized O(log n) instead of O(log n).
|
||||
|
||||
* Whether the [*size saving] mechanisms are used to implement the tree nodes
|
||||
([classref boost::container::optimize_size optimize_size]). By default this option is activated and is only
|
||||
meaningful to red-black and avl trees (in other cases, this option will be ignored).
|
||||
This option will try to put rebalancing metadata inside the "parent" pointer of the node if the pointer
|
||||
type has enough alignment. Usually, due to alignment issues, the metadata uses the size of a pointer yielding
|
||||
to four pointer size overhead per node, whereas activating this option usually leads to 3 pointer size overhead.
|
||||
Although some mask operations must be performed to extract
|
||||
data from this special "parent" pointer, in several systems this option also improves performance due to the
|
||||
improved cache usage produced by the node size reduction.
|
||||
|
||||
See the following example to see how [classref boost::container::tree_assoc_options tree_assoc_options] can be
|
||||
used to customize these containers:
|
||||
|
||||
[import ../example/doc_custom_tree.cpp]
|
||||
[doc_custom_tree]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:configurable_vectors Configurable vectors]
|
||||
|
||||
[*Boost.Container] offers the possibility to configure at compile time some parameters of
|
||||
[classref boost::container::vector vector] implementation. This configuration is passed as
|
||||
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.
|
||||
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 it's own implementation 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].
|
||||
|
||||
* [classref boost::container::stored_size stored_size]: the type that will be used to store size-related
|
||||
parameters inside of the vector. Sometimes, when the maximum capacity to be used is much less than the
|
||||
theoretical maximum that a vector can hold, it's interesting to use smaller unsigned integer types to represent
|
||||
`size()` and `capacity()` inside vector, so that the size of an empty vector is minimized and cache
|
||||
performance might be improved. See [classref boost::container::stored_size stored_size] for more details.
|
||||
|
||||
See the following example to see how [classref boost::container::vector_options vector_options] can be
|
||||
used to customize `vector` container:
|
||||
|
||||
[import ../example/doc_custom_vector.cpp]
|
||||
[doc_custom_vector]
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:extended_allocators Extended functionality: Extended allocators]
|
||||
|
||||
Many C++ programmers have ever wondered where does good old realloc fit in C++. And that's a good question.
|
||||
Could we improve [classref boost::container::vector vector] performance using memory expansion mechanisms
|
||||
@@ -700,7 +745,7 @@ Use them simply specifying the new allocator in the corresponding template argum
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:polymorphic_memory_resources Polymorphic Memory Resources ]
|
||||
[section:polymorphic_memory_resources Extended Functionality: Polymorphic Memory Resources ]
|
||||
|
||||
The document
|
||||
[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4480.html C++ Extensions for Library Fundamentals (Final draft: N4480)]
|
||||
@@ -818,31 +863,6 @@ type-erasured allocator-capable classes even in C++03 compilers.
|
||||
|
||||
[endsect]
|
||||
|
||||
[/
|
||||
/a__section:previous_element_slist Previous element for slist__a
|
||||
/
|
||||
/The C++11 `std::forward_list` class implement a singly linked list, similar to `slist`, and these
|
||||
/containers only offer forward iterators and implement insertions and splice operations that operate with ranges
|
||||
/to be inserted ['after] that position. In those cases, sometimes it's interesting to obtain an iterator pointing
|
||||
/to the previous element of another element. This operation can be implemented
|
||||
/
|
||||
/a__endsect__a
|
||||
]
|
||||
|
||||
[/
|
||||
/a__section:get_stored_allocator Obtain stored allocator__a
|
||||
/
|
||||
/STL containers offer a `get_allocator()` member to obtain a copy of the allocator that
|
||||
/the container is using to allocate and construct elements. For performance reasons, some
|
||||
/applications need o
|
||||
/
|
||||
/http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2271.html
|
||||
/
|
||||
/a__endsect__a
|
||||
/]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:Cpp11_conformance C++11/C++14 Conformance]
|
||||
|
||||
[*Boost.Container] aims for full C++11 conformance except reasoned deviations,
|
||||
@@ -1212,6 +1232,13 @@ use [*Boost.Container]? There are several reasons for that:
|
||||
|
||||
[section:release_notes Release Notes]
|
||||
|
||||
[section:release_notes_boost_1_67_00 Boost 1.67 Release]
|
||||
|
||||
* ['vector] can now have options, using [classref boost::container::vector_options vector_options].
|
||||
The growth factor and the stored size type can be specified.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:release_notes_boost_1_66_00 Boost 1.66 Release]
|
||||
|
||||
* ['flat_[multi]map/set] can now work as container adaptors, as proposed in [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/p0429r1.pdf P0429R1].
|
||||
@@ -1362,7 +1389,7 @@ use [*Boost.Container]? There are several reasons for that:
|
||||
|
||||
* Added DlMalloc-based [link container.extended_functionality.extended_allocators Extended Allocators].
|
||||
|
||||
* [link container.extended_functionality.configurable_tree_based_associative_containers Improved configurability]
|
||||
* [link container.extended_functionality.configurable_containers.configurable_tree_based_associative_containers Improved configurability]
|
||||
of tree-based ordered associative containers. AVL, Scapegoat and Splay trees are now available
|
||||
to implement [classref boost::container::set set], [classref boost::container::multiset multiset],
|
||||
[classref boost::container::map map] and [classref boost::container::multimap multimap].
|
||||
|
||||
Reference in new issue
Block a user