forked from boostorg/intrusive
Fixed documentation after removal of deprecated splay_set_xxx_hooks.
This commit is contained in:
Ion Gaztañaga
@@ -1364,163 +1364,6 @@ the unordered container:
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:splay_set_multiset Intrusive splay tree based associative containers: splay_set, splay_multiset and , splay_tree]
|
||||
|
||||
C++ associative containers are usually based on red-black tree implementations (e.g.: STL,
|
||||
Boost.Intrusive associative containers). However, there are other interesting data
|
||||
structures that offer some advantages (and also disadvantages).
|
||||
|
||||
Splay trees are self-adjusting binary search trees used typically in caches, memory
|
||||
allocators and other applications, because splay trees have a "caching effect": recently
|
||||
accessed elements have better access times than elements accessed less frequently.
|
||||
For more information on splay trees see [@http://en.wikipedia.org/wiki/Splay_tree Wikipedia entry].
|
||||
|
||||
[*Boost.Intrusive] offers 3 containers based on splay trees:
|
||||
[classref boost::intrusive::splay_set splay_set],
|
||||
[classref boost::intrusive::splay_multiset splay_multiset] and
|
||||
[classref boost::intrusive::splaytree splaytree]. The first two are similar to
|
||||
[classref boost::intrusive::set set] or
|
||||
[classref boost::intrusive::multiset multiset] and the latter is a generalization
|
||||
that offers functions both to insert unique and multiple keys.
|
||||
|
||||
The memory overhead of these containers with Boost.Intrusive hooks is usually 3 pointers.
|
||||
An empty, non constant-time size splay container has also a size of 3 pointers.
|
||||
|
||||
[section:splay_set_multiset_disadvantages Advantages and disadvantages of splay tree based containers]
|
||||
|
||||
Splay tree based intrusive containers have logarithmic complexity in many
|
||||
operations like searches, insertions, erasures, etc., but if some elements are
|
||||
more frequently accessed than others, splay trees perform faster searches than equivalent
|
||||
balanced binary trees (such as red-black trees).
|
||||
|
||||
The caching effect offered by splay trees comes with a cost: the tree must be
|
||||
rebalanced when an element is searched. This disallows const versions of search
|
||||
functions like `find()`, `lower_bound()`, `upper_bound()`, `equal_range()`,
|
||||
`count()`, etc.
|
||||
|
||||
Because of this, splay-tree based associative containers are not drop-in
|
||||
replacements of [classref boost::intrusive::set set]/
|
||||
[classref boost::intrusive::multiset multiset].
|
||||
|
||||
Apart from this, if element searches are randomized, the tree will be rebalanced
|
||||
without taking advantage of the cache effect, so splay trees can offer worse
|
||||
performance than other balanced trees for some search patterns.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:splay_set_multiset_hooks splay_set, splay_multiset and splaytree hooks]
|
||||
|
||||
[classref boost::intrusive::splay_set splay_set],
|
||||
[classref boost::intrusive::splay_multiset splay_multiset] and
|
||||
[classref boost::intrusive::splaytree splaytree]
|
||||
share the same hooks.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class splay_set_base_hook;
|
||||
|
||||
* [classref boost::intrusive::splay_set_base_hook splay_set_base_hook]:
|
||||
the user class derives publicly from this class to make
|
||||
it compatible with splay tree based containers.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class splay_set_member_hook;
|
||||
|
||||
* [classref boost::intrusive::set_member_hook set_member_hook]:
|
||||
the user class contains a public member of this class to make
|
||||
it compatible with splay tree based containers.
|
||||
|
||||
[classref boost::intrusive::splay_set_base_hook splay_set_base_hook] and
|
||||
[classref boost::intrusive::splay_set_member_hook splay_set_member_hook] receive
|
||||
the same options explained in the section
|
||||
[link intrusive.usage How to use Boost.Intrusive]:
|
||||
|
||||
* [*`tag<class Tag>`] (for base hooks only): This argument serves as a tag,
|
||||
so you can derive from more than one base hook.
|
||||
Default: `tag<default_tag>`.
|
||||
|
||||
* [*`link_mode<link_mode_type LinkMode>`]: The linking policy.
|
||||
Default: `link_mode<safe_link>`.
|
||||
|
||||
* [*`void_pointer<class VoidPointer>`]: The pointer type to be used
|
||||
internally in the hook and propagated to the container.
|
||||
Default: `void_pointer<void*>`.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:set_multiset_containers splay_set, splay_multiset and splaytree containers]
|
||||
|
||||
[c++]
|
||||
|
||||
template <class T, class ...Options>
|
||||
class splay_set;
|
||||
|
||||
template <class T, class ...Options>
|
||||
class splay_multiset;
|
||||
|
||||
template <class T, class ...Options>
|
||||
class splaytree;
|
||||
|
||||
These containers receive the same options explained in the section
|
||||
[link intrusive.usage How to use Boost.Intrusive]:
|
||||
|
||||
* [*`base_hook<class Hook>`] / [*`member_hook<class T, class Hook, Hook T::* PtrToMember>`] /
|
||||
[*`value_traits<class ValueTraits>`]: To specify the hook type or value traits used
|
||||
to configure the container. (To learn about value traits go to the section
|
||||
[link intrusive.value_traits Containers with custom ValueTraits].)
|
||||
|
||||
* [*`constant_time_size<bool Enabled>`]: To activate the constant-time `size()` operation.
|
||||
Default: `constant_time_size<true>`
|
||||
|
||||
* [*`size_type<bool Enabled>`]: To specify the type that will be used to store the size
|
||||
of the container. Default: `size_type<std::size_t>`
|
||||
|
||||
And they also can receive an additional option:
|
||||
|
||||
* [*`compare<class Compare>`]: Comparison function for the objects to be inserted
|
||||
in containers. The comparison functor must induce a strict weak ordering.
|
||||
Default: `compare< std::less<T> >`
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:splay_set_bst_hook Splay trees with BST hooks]
|
||||
|
||||
Intrusive splay containers can also use plain binary search tree hooks
|
||||
[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and
|
||||
[classref boost::intrusive::bs_set_base_hook bs_set_base_hook].
|
||||
These hooks can be used by other intrusive containers like
|
||||
intrusive scapegoat containers
|
||||
[classref boost::intrusive::sg_set sg_set] and
|
||||
[classref boost::intrusive::sg_multiset sg_multiset]. A programmer
|
||||
might prefer using a binary search tree hook so that the same type
|
||||
can be inserted in some situations in a splay container but
|
||||
also inserted in other compatible containers when
|
||||
the hook is not being used in a splay container.
|
||||
|
||||
[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and
|
||||
[classref boost::intrusive::bs_set_base_hook bs_set_member_hook] admit
|
||||
the same options as [classref boost::intrusive::splay_set_base_hook splay_set_base_hook].
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:splay_set_multiset_example Example]
|
||||
|
||||
Now let's see a small example using both splay hooks,
|
||||
binary search tree hooks and
|
||||
[classref boost::intrusive::splay_set splay_set]/
|
||||
[classref boost::intrusive::splay_multiset splay_multiset]
|
||||
containers:
|
||||
|
||||
[import ../example/doc_splay_set.cpp]
|
||||
[doc_splay_set_code]
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:avl_set_multiset Intrusive avl tree based associative containers: avl_set, avl_multiset and avltree]
|
||||
|
||||
Similar to red-black trees, AVL trees are balanced binary trees.
|
||||
@@ -1649,6 +1492,103 @@ containers:
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:splay_set_multiset Intrusive splay tree based associative containers: splay_set, splay_multiset and , splay_tree]
|
||||
|
||||
C++ associative containers are usually based on red-black tree implementations (e.g.: STL,
|
||||
Boost.Intrusive associative containers). However, there are other interesting data
|
||||
structures that offer some advantages (and also disadvantages).
|
||||
|
||||
Splay trees are self-adjusting binary search trees used typically in caches, memory
|
||||
allocators and other applications, because splay trees have a "caching effect": recently
|
||||
accessed elements have better access times than elements accessed less frequently.
|
||||
For more information on splay trees see [@http://en.wikipedia.org/wiki/Splay_tree the corresponding Wikipedia entry].
|
||||
|
||||
[*Boost.Intrusive] offers 3 containers based on splay trees:
|
||||
[classref boost::intrusive::splay_set splay_set],
|
||||
[classref boost::intrusive::splay_multiset splay_multiset] and
|
||||
[classref boost::intrusive::splaytree splaytree]. The first two are similar to
|
||||
[classref boost::intrusive::set set] or
|
||||
[classref boost::intrusive::multiset multiset] and the latter is a generalization
|
||||
that offers functions both to insert unique and multiple keys.
|
||||
|
||||
The memory overhead of these containers with Boost.Intrusive hooks is usually 3 pointers.
|
||||
An empty, non constant-time size splay container has also a size of 3 pointers.
|
||||
|
||||
[section:splay_set_multiset_disadvantages Advantages and disadvantages of splay tree based containers]
|
||||
|
||||
Splay tree based intrusive containers have logarithmic complexity in many
|
||||
operations like searches, insertions, erasures, etc., but if some elements are
|
||||
more frequently accessed than others, splay trees perform faster searches than equivalent
|
||||
balanced binary trees (such as red-black trees).
|
||||
|
||||
The caching effect offered by splay trees comes with a cost: the tree must be
|
||||
rebalanced when an element is searched. To maintain const-correctness and thread-safety
|
||||
guarantees, this caching effect is not updated when const versions of
|
||||
search functions like `find()`, `lower_bound()`, `upper_bound()`, `equal_range()`,
|
||||
`count()`... are called. This means that using splay-tree based associative containers as drop-in
|
||||
replacements of [classref boost::intrusive::set set]/
|
||||
[classref boost::intrusive::multiset multiset], specially for const search functions,
|
||||
might not result in desired performance improvements.
|
||||
|
||||
If element searches are randomized, the tree will be continuously srebalanced
|
||||
without taking advantage of the cache effect, so splay trees can offer worse
|
||||
performance than other balanced trees for several search patterns.
|
||||
|
||||
[*Boost.Intrusive] splay associative containers don't use their own hook types but plain Binary search tree hooks.
|
||||
See [link intrusive.bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook] section for more
|
||||
information about these hooks.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:set_multiset_containers splay_set, splay_multiset and splaytree containers]
|
||||
|
||||
[c++]
|
||||
|
||||
template <class T, class ...Options>
|
||||
class splay_set;
|
||||
|
||||
template <class T, class ...Options>
|
||||
class splay_multiset;
|
||||
|
||||
template <class T, class ...Options>
|
||||
class splaytree;
|
||||
|
||||
These containers receive the same options explained in the section
|
||||
[link intrusive.usage How to use Boost.Intrusive]:
|
||||
|
||||
* [*`base_hook<class Hook>`] / [*`member_hook<class T, class Hook, Hook T::* PtrToMember>`] /
|
||||
[*`value_traits<class ValueTraits>`]: To specify the hook type or value traits used
|
||||
to configure the container. (To learn about value traits go to the section
|
||||
[link intrusive.value_traits Containers with custom ValueTraits].)
|
||||
|
||||
* [*`constant_time_size<bool Enabled>`]: To activate the constant-time `size()` operation.
|
||||
Default: `constant_time_size<true>`
|
||||
|
||||
* [*`size_type<bool Enabled>`]: To specify the type that will be used to store the size
|
||||
of the container. Default: `size_type<std::size_t>`
|
||||
|
||||
And they also can receive an additional option:
|
||||
|
||||
* [*`compare<class Compare>`]: Comparison function for the objects to be inserted
|
||||
in containers. The comparison functor must induce a strict weak ordering.
|
||||
Default: `compare< std::less<T> >`
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:splay_set_multiset_example Example]
|
||||
|
||||
Now let's see a small example using
|
||||
[classref boost::intrusive::splay_set splay_set]/
|
||||
[classref boost::intrusive::splay_multiset splay_multiset]
|
||||
containers:
|
||||
|
||||
[import ../example/doc_splay_set.cpp]
|
||||
[doc_splay_set_code]
|
||||
|
||||
[endsect]
|
||||
|
||||
[endsect]
|
||||
|
||||
|
||||
[section:sg_set_multiset Intrusive scapegoat tree based associative containers: sg_set, sg_multiset and sgtree]
|
||||
|
||||
@@ -1705,50 +1645,9 @@ An empty, [classref boost::intrusive::sg_set sg_set],
|
||||
has also the size of 3 pointers, two integers and two floating point values
|
||||
(equivalent to the size of 7 pointers on most systems).
|
||||
|
||||
[section:sg_set_multiset_hooks Using binary search tree hooks: bs_set_base_hook and bs_set_member_hook]
|
||||
|
||||
[classref boost::intrusive::sg_set sg_set],
|
||||
[classref boost::intrusive::sg_multiset sg_multiset] and
|
||||
[classref boost::intrusive::sgtree sgtree] don't use their
|
||||
own hooks but plain binary search tree hooks. This has many advantages
|
||||
since binary search tree hooks can also be used to insert values in
|
||||
splay and treap containers.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class bs_set_base_hook;
|
||||
|
||||
* [classref boost::intrusive::bs_set_base_hook bs_set_base_hook]:
|
||||
the user class derives publicly from this class to make
|
||||
it compatible with scapegoat tree based containers.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class bs_set_member_hook;
|
||||
|
||||
* [classref boost::intrusive::set_member_hook set_member_hook]:
|
||||
the user class contains a public member of this class to make
|
||||
it compatible with scapegoat tree based containers.
|
||||
|
||||
[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and
|
||||
[classref boost::intrusive::bs_set_member_hook bs_set_member_hook] receive
|
||||
the same options explained in the section
|
||||
[link intrusive.usage How to use Boost.Intrusive]:
|
||||
|
||||
* [*`tag<class Tag>`] (for base hooks only): This argument serves as a tag,
|
||||
so you can derive from more than one base hook.
|
||||
Default: `tag<default_tag>`.
|
||||
|
||||
* [*`link_mode<link_mode_type LinkMode>`]: The linking policy.
|
||||
Default: `link_mode<safe_link>`.
|
||||
|
||||
* [*`void_pointer<class VoidPointer>`]: The pointer type to be used
|
||||
internally in the hook and propagated to the container.
|
||||
Default: `void_pointer<void*>`.
|
||||
|
||||
[endsect]
|
||||
[*Boost.Intrusive] scapegoat associative containers don't use their own hook types but plain Binary search tree hooks.
|
||||
See [link intrusive.bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook] section for more
|
||||
information about these hooks.
|
||||
|
||||
[section:sg_set_multiset_containers sg_set, sg_multiset and sgtree containers]
|
||||
|
||||
@@ -1791,7 +1690,7 @@ And they also can receive additional options:
|
||||
|
||||
[section:sg_set_multiset_example Example]
|
||||
|
||||
Now let's see a small example using both hooks and
|
||||
Now let's see a small example using binary search tree hooks and
|
||||
[classref boost::intrusive::sg_set sg_set]/
|
||||
[classref boost::intrusive::sg_multiset sg_multiset]
|
||||
containers:
|
||||
@@ -1841,50 +1740,9 @@ An empty, [classref boost::intrusive::treap_set treap_set],
|
||||
has also the size of 3 pointers and an integer (supposing empty function objects for key and priority
|
||||
comparison and constant-time size).
|
||||
|
||||
[section:treap_set_multiset_hooks Using binary search tree hooks: bs_set_base_hook and bs_set_member_hook]
|
||||
|
||||
[classref boost::intrusive::treap_set treap_set],
|
||||
[classref boost::intrusive::treap_multiset treap_multiset] and
|
||||
[classref boost::intrusive::treap treap] don't use their
|
||||
own hooks but plain binary search tree hooks. This has many advantages
|
||||
since binary search tree hooks can also be used to insert values in
|
||||
splay containers and scapegoat trees.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class bs_set_base_hook;
|
||||
|
||||
* [classref boost::intrusive::bs_set_base_hook bs_set_base_hook]:
|
||||
the user class derives publicly from this class to make
|
||||
it compatible with scapegoat tree based containers.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class bs_set_member_hook;
|
||||
|
||||
* [classref boost::intrusive::set_member_hook set_member_hook]:
|
||||
the user class contains a public member of this class to make
|
||||
it compatible with scapegoat tree based containers.
|
||||
|
||||
[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and
|
||||
[classref boost::intrusive::bs_set_member_hook bs_set_member_hook] receive
|
||||
the same options explained in the section
|
||||
[link intrusive.usage How to use Boost.Intrusive]:
|
||||
|
||||
* [*`tag<class Tag>`] (for base hooks only): This argument serves as a tag,
|
||||
so you can derive from more than one base hook.
|
||||
Default: `tag<default_tag>`.
|
||||
|
||||
* [*`link_mode<link_mode_type LinkMode>`]: The linking policy.
|
||||
Default: `link_mode<safe_link>`.
|
||||
|
||||
* [*`void_pointer<class VoidPointer>`]: The pointer type to be used
|
||||
internally in the hook and propagated to the container.
|
||||
Default: `void_pointer<void*>`.
|
||||
|
||||
[endsect]
|
||||
[*Boost.Intrusive] treap associative containers don't use their own hook types but plain Binary search tree hooks.
|
||||
See [link intrusive.bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook] section for more
|
||||
information about these hooks.
|
||||
|
||||
[section:treap_set_multiset_containers treap_set, treap_multiset and treap containers]
|
||||
|
||||
@@ -1967,7 +1825,7 @@ the strongest possible behaviour in these situations. In summary:
|
||||
|
||||
[section:treap_set_multiset_example Example]
|
||||
|
||||
Now let's see a small example using both hooks and
|
||||
Now let's see a small example using binary search tree hooks and
|
||||
[classref boost::intrusive::treap_set treap_set]/
|
||||
[classref boost::intrusive::treap_multiset treap_multiset]
|
||||
containers:
|
||||
@@ -1979,6 +1837,48 @@ containers:
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:bst_hooks Binary search tree hooks: bs_set_base_hook and bs_set_member_hook]
|
||||
|
||||
Binary search tree hooks can be used with several tree-like containers that don't
|
||||
need any additional metadata for rebalancing operations. This has many advantages
|
||||
since binary search tree hooks can also be used to insert values in
|
||||
plain binary search tree, splay tree, scapegoat tree, and treap containers.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class bs_set_base_hook;
|
||||
|
||||
* [classref boost::intrusive::bs_set_base_hook bs_set_base_hook]:
|
||||
the user class derives publicly from this class to make
|
||||
it compatible with the mentioned tree based containers.
|
||||
|
||||
[c++]
|
||||
|
||||
template <class ...Options>
|
||||
class bs_set_member_hook;
|
||||
|
||||
* [classref boost::intrusive::bs_set_member_hook bs_set_member_hook]:
|
||||
the user class contains a public member of this class to make
|
||||
it compatible with the mentioned tree based containers.
|
||||
|
||||
[classref boost::intrusive::bs_set_base_hook bs_set_base_hook] and
|
||||
[classref boost::intrusive::bs_set_member_hook bs_set_member_hook] receive
|
||||
the same options explained in the section
|
||||
[link intrusive.usage How to use Boost.Intrusive]:
|
||||
|
||||
* [*`tag<class Tag>`] (for base hooks only): This argument serves as a tag,
|
||||
so you can derive from more than one base hook.
|
||||
Default: `tag<default_tag>`.
|
||||
|
||||
* [*`link_mode<link_mode_type LinkMode>`]: The linking policy.
|
||||
Default: `link_mode<safe_link>`.
|
||||
|
||||
* [*`void_pointer<class VoidPointer>`]: The pointer type to be used
|
||||
internally in the hook and propagated to the container.
|
||||
Default: `void_pointer<void*>`.
|
||||
|
||||
[endsect]
|
||||
|
||||
[section:advanced_lookups_insertions Advanced lookup and insertion functions for associative containers]
|
||||
|
||||
|
||||
Reference in New Issue
Block a user