Description

The class template splaytree is an intrusive splay tree container that is used to construct intrusive splay_set and splay_multiset containers. The no-throw guarantee holds only, if the value_compare object doesn't throw.

The template parameter T is the type to be managed by the container. The user can specify additional options and if no options are provided default options are used.

The container supports the following options: base_hook<>/member_hook<>/value_traits<>, constant_time_size<>, size_type<> and compare<>.

Complexity: Linear in N if [b, e) is already sorted using comp and otherwise N * log N, where N is the distance between first and last.

Throws: If value_traits::node_traits::node constructor throws (this does not happen with predefined Boost.Intrusive hooks) or the copy constructor/operator() of the value_compare object throws. Basic guarantee.

Effects: Detaches all elements from this. The objects in the set are not deleted (i.e. no destructors are called), but the nodes according to the value_traits template parameter are reinitialized and thus can be reused.

Complexity: Linear to elements contained in *this.

Throws: Nothing.

splaytree public member functions

iteratorbegin();

Effects: Returns an iterator pointing to the beginning of the container.

Complexity: Constant.

Throws: Nothing.

const_iteratorbegin()const;

Effects: Returns a const_iterator pointing to the beginning of the container.

Complexity: Constant.

Throws: Nothing.

const_iteratorcbegin()const;

Effects: Returns a const_iterator pointing to the beginning of the container.

Complexity: Constant.

Throws: Nothing.

iteratorend();

Effects: Returns an iterator pointing to the end of the container.

Complexity: Constant.

Throws: Nothing.

const_iteratorend()const;

Effects: Returns a const_iterator pointing to the end of the container.

Complexity: Constant.

Throws: Nothing.

const_iteratorcend()const;

Effects: Returns a const_iterator pointing to the end of the container.

Complexity: Constant.

Throws: Nothing.

reverse_iteratorrbegin();

Effects: Returns a reverse_iterator pointing to the beginning of the reversed container.

Complexity: Constant.

Throws: Nothing.

const_reverse_iteratorrbegin()const;

Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed container.

Complexity: Constant.

Throws: Nothing.

const_reverse_iteratorcrbegin()const;

Effects: Returns a const_reverse_iterator pointing to the beginning of the reversed container.

Complexity: Constant.

Throws: Nothing.

reverse_iteratorrend();

Effects: Returns a reverse_iterator pointing to the end of the reversed container.

Complexity: Constant.

Throws: Nothing.

const_reverse_iteratorrend()const;

Effects: Returns a const_reverse_iterator pointing to the end of the reversed container.

Complexity: Constant.

Throws: Nothing.

const_reverse_iteratorcrend()const;

Effects: Returns a const_reverse_iterator pointing to the end of the reversed container.

Complexity: Constant.

Throws: Nothing.

key_comparekey_comp()const;

Effects: Returns the key_compare object used by the container.

Complexity: Constant.

Throws: If value_compare copy-constructor throws.

value_comparevalue_comp()const;

Effects: Returns the value_compare object used by the container.

Complexity: Constant.

Throws: If value_compare copy-constructor throws.

boolempty()const;

Effects: Returns true if the container is empty.

Complexity: Constant.

Throws: Nothing.

size_typesize()const;

Effects: Returns the number of elements stored in the container.

Complexity: Linear to elements contained in *this if constant-time size option is disabled. Constant time otherwise.

Requires: Disposer::operator()(pointer) shouldn't throw. Cloner should yield to nodes equivalent to the original nodes.

Effects: Erases all the elements from *this calling Disposer::operator()(pointer), clones all the elements from src calling Cloner::operator()(const_reference ) and inserts them on *this. Copies the predicate from the source container.

If cloner throws, all cloned elements are unlinked and disposed calling Disposer::operator()(pointer).

Requires: key_value_comp must be a comparison function that induces the same strict weak ordering as value_compare. The difference is that key_value_comp compares an arbitrary key with the contained values.

Effects: Checks if a value can be inserted in the container, using a user provided key instead of the value itself.

Returns: If there is an equivalent value returns a pair containing an iterator to the already present value and false. If the value can be inserted returns true in the returned pair boolean and fills "commit_data" that is meant to be used with the "insert_commit" function.

Notes: This function is used to improve performance when constructing a value_type is expensive: if there is an equivalent value the constructed object must be discarded. Many times, the part of the node that is used to impose the order is much cheaper to construct than the value_type and this function offers the possibility to use that part to check if the insertion will be successful.

If the check is successful, the user can construct the value_type and use "insert_commit" to insert the object in constant-time. This gives a total logarithmic complexity to the insertion: check(O(log(N)) + commit(O(1)).

"commit_data" remains valid for a subsequent "insert_commit" only if no more objects are inserted or erased from the container.

Requires: key_value_comp must be a comparison function that induces the same strict weak ordering as value_compare. The difference is that key_value_comp compares an arbitrary key with the contained values.

Effects: Checks if a value can be inserted in the container, using a user provided key instead of the value itself, using "hint" as a hint to where it will be inserted.

Returns: If there is an equivalent value returns a pair containing an iterator to the already present value and false. If the value can be inserted returns true in the returned pair boolean and fills "commit_data" that is meant to be used with the "insert_commit" function.

Complexity: Logarithmic in general, but it's amortized constant time if t is inserted immediately before hint.

Notes: This function is used to improve performance when constructing a value_type is expensive: if there is an equivalent value the constructed object must be discarded. Many times, the part of the constructing that is used to impose the order is much cheaper to construct than the value_type and this function offers the possibility to use that key to check if the insertion will be successful.

If the check is successful, the user can construct the value_type and use "insert_commit" to insert the object in constant-time. This can give a total constant-time complexity to the insertion: check(O(1)) + commit(O(1)).

"commit_data" remains valid for a subsequent "insert_commit" only if no more objects are inserted or erased from the container.

Requires: value must be an lvalue of type value_type. commit_data must have been obtained from a previous call to "insert_check". No objects should have been inserted or erased from the container between the "insert_check" that filled "commit_data" and the call to "insert_commit".

Effects: Inserts the value in the container using the information obtained from the "commit_data" that a previous "insert_check" filled.

Returns: An iterator to the newly inserted object.

Complexity: Constant time.

Throws: Nothing.

Notes: This function has only sense if a "insert_check" has been previously executed to fill "commit_data". No value should be inserted or erased between the "insert_check" and "insert_commit" calls.

template<typename Iterator>voidinsert_unique(Iterator b,Iterator e);

Requires: Dereferencing iterator must yield an lvalue of type value_type.

Effects: Tries to insert each element of a range into the container.

Complexity: Insert range is in general O(N * log(N)), where N is the size of the range. However, it is linear in N if the range is already sorted by value_comp().

Throws: Nothing.

Note: Does not affect the validity of iterators and references. No copy-constructors are called.

iteratorinsert_before(const_iterator pos,reference value);

Requires: value must be an lvalue, "pos" must be a valid iterator (or end) and must be the succesor of value once inserted according to the predicate

Effects: Inserts x into the container before "pos".

Complexity: Constant time.

Throws: Nothing.

Note: This function does not check preconditions so if "pos" is not the successor of "value" container ordering invariant will be broken. This is a low-level function to be used only for performance reasons by advanced users.

voidpush_back(reference value);

Requires: value must be an lvalue, and it must be no less than the greatest inserted key

Effects: Inserts x into the container in the last position.

Complexity: Constant time.

Throws: Nothing.

Note: This function does not check preconditions so if value is less than the greatest inserted key container ordering invariant will be broken. This function is slightly more efficient than using "insert_before". This is a low-level function to be used only for performance reasons by advanced users.

voidpush_front(reference value);

Requires: value must be an lvalue, and it must be no greater than the minimum inserted key

Effects: Inserts x into the container in the first position.

Complexity: Constant time.

Throws: Nothing.

Note: This function does not check preconditions so if value is greater than the minimum inserted key container ordering invariant will be broken. This function is slightly more efficient than using "insert_before". This is a low-level function to be used only for performance reasons by advanced users.

iteratorerase(const_iterator i);

Effects: Erases the element pointed to by pos.

Complexity: Average complexity for erase element is constant time.

Throws: Nothing.

Note: Invalidates the iterators (but not the references) to the erased elements. No destructors are called.

iteratorerase(const_iterator b,const_iterator e);

Effects: Erases the range pointed to by b end e.

Complexity: Average complexity for erase range is at most O(log(size() + N)), where N is the number of elements in the range.

Throws: Nothing.

Note: Invalidates the iterators (but not the references) to the erased elements. No destructors are called.

size_typeerase(const_reference value);

Effects: Erases the element pointed to by pos.

Complexity: Average complexity for erase element is constant time.

Throws: Nothing.

Note: Invalidates the iterators (but not the references) to the erased elements. No destructors are called.

Effects: Erases all the elements with the given key. according to the comparison functor "comp". Disposer::operator()(pointer) is called for the removed elements.

Returns: The number of erased elements.

Complexity: O(log(size() + N).

Throws: Nothing.

Note: Invalidates the iterators to the erased elements.

voidclear();

Effects: Erases all of the elements.

Complexity: Linear to the number of elements on the container. if it's a safe-mode or auto-unlink value_type. Constant time otherwise.

Throws: Nothing.

Note: Invalidates the iterators (but not the references) to the erased elements. No destructors are called.

template<typename Disposer>voidclear_and_dispose(Disposer disposer);

Effects: Erases all of the elements calling disposer(p) for each node to be erased. Complexity: Average complexity for is at most O(log(size() + N)), where N is the number of elements in the container.

Throws: Nothing.

Note: Invalidates the iterators (but not the references) to the erased elements. Calls N times to disposer functor.

size_typecount(const_reference value);

Effects: Returns the number of contained elements with the given value

Complexity: Logarithmic to the number of elements contained plus lineal to number of objects with the given value.

Requires: KeyValueCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the container. 'lower_key' must not be greater than 'upper_key' according to 'comp'. If 'lower_key' == 'upper_key', ('left_closed' || 'right_closed') must be false.

Requires: KeyValueCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the container. 'lower_key' must not be greater than 'upper_key' according to 'comp'. If 'lower_key' == 'upper_key', ('left_closed' || 'right_closed') must be false.

Requires: value must be an lvalue and shall be in a set of appropriate type. Otherwise the behavior is undefined.

Effects: Returns: a valid iterator i belonging to the set that points to the value

Complexity: Constant.

Throws: Nothing.

const_iteratoriterator_to(const_reference value)const;

Requires: value must be an lvalue and shall be in a set of appropriate type. Otherwise the behavior is undefined.

Effects: Returns: a valid const_iterator i belonging to the set that points to the value

Complexity: Constant.

Throws: Nothing.

pointerunlink_leftmost_without_rebalance();

Effects: Unlinks the leftmost node from the container.

Complexity: Average complexity is constant time.

Throws: Nothing.

Notes: This function breaks the container and the container can only be used for more unlink_leftmost_without_rebalance calls. This function is normally used to achieve a step by step controlled destruction of the container.

voidreplace_node(iterator replace_this,reference with_this);

Requires: replace_this must be a valid iterator of *this and with_this must not be inserted in any container.

Effects: Replaces replace_this in its position in the container with with_this. The container does not need to be rebalanced.

Complexity: Constant.

Throws: Nothing.

Note: This function will break container ordering invariants if with_this is not equivalent to *replace_this according to the ordering rules. This function is faster than erasing and inserting the node, since no rebalancing or comparison is needed.

voidremove_node(reference value);

Effects: removes "value" from the container.

Throws: Nothing.

Complexity: Logarithmic time.

Note: This static function is only usable with non-constant time size containers that have stateless comparison functors.

If the user calls this function with a constant time size container or stateful comparison functor a compilation error will be issued.

voidsplay_up(iterator i);

Requires: i must be a valid iterator of *this.

Effects: Rearranges the container so that the element pointed by i is placed as the root of the tree, improving future searches of this value.

Effects: Rearranges the container so that if *this stores an element with a key equivalent to value the element is placed as the root of the tree. If the element is not present returns the last node compared with the key. If the tree is empty, end() is returned.

Complexity: Amortized logarithmic.

Returns: An iterator to the new root of the tree, end() if the tree is empty.

Throws: If the comparison functor throws.

iteratorsplay_down(const_reference value);

Effects: Rearranges the container so that if *this stores an element with a key equivalent to value the element is placed as the root of the tree.

Complexity: Amortized logarithmic.

Returns: An iterator to the new root of the tree, end() if the tree is empty.