Description

(1) the header node is maintained with links not only to the root but also to the leftmost node of the tree, to enable constant time begin(), and to the rightmost node of the tree, to enable linear time performance when used with the generic set algorithms (set_union, etc.);

(2) when a node being deleted has two children its successor node is relinked into its place, rather than copied, so that the only pointers invalidated are those referring to the deleted node.

treap_algorithms is configured with a NodeTraits class, which encapsulates the information about the node to be manipulated. NodeTraits must support the following interface:

Requires: node_to_be_replaced must be inserted in a tree and new_node must not be inserted in a tree.

Effects: Replaces node_to_be_replaced in its position in the tree with new_node. The tree does not need to be rebalanced

Complexity: Logarithmic.

Throws: Nothing.

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

Requires: node_to_be_replaced must be inserted in a tree with header "header" and new_node must not be inserted in a tree.

Effects: Replaces node_to_be_replaced in its position in the tree with new_node. The tree does not need to be rebalanced

Complexity: Constant.

Throws: Nothing.

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

Effects: Unlinks the leftmost node from the tree, and updates the header link to the new leftmost node.

Complexity: Average complexity is constant time.

Throws: Nothing.

Notes: This function breaks the tree and the tree 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 tree.

staticboolunique(const_node_ptr node);

Requires: node is a node of the tree or an node initialized by init(...).

Effects: Returns true if the node is initialized by init().

Complexity: Constant time.

Throws: Nothing.

staticstd::size_tcount(const_node_ptr node);

Requires: node is a node of the tree but it's not the header.

Effects: Returns the number of nodes of the subtree.

Complexity: Linear time.

Throws: Nothing.

staticstd::size_tsize(const_node_ptr header);

Requires: header is the header node of the tree.

Effects: Returns the number of nodes above the header.

Complexity: Linear time.

Throws: Nothing.

staticnode_ptrnext_node(node_ptr p);

Requires: p is a node from the tree except the header.

Effects: Returns the next node of the tree.

Complexity: Average constant time.

Throws: Nothing.

staticnode_ptrprev_node(node_ptr p);

Requires: p is a node from the tree except the leftmost node.

Effects: Returns the previous node of the tree.

Complexity: Average constant time.

Throws: Nothing.

staticvoidinit(node_ptr node);

Requires: node must not be part of any tree.

Effects: After the function unique(node) == true.

Complexity: Constant.

Throws: Nothing.

Nodes: If node is inserted in a tree, this function corrupts the tree.

Requires: "cloner" must be a function object taking a node_ptr and returning a new cloned node of it. "disposer" must take a node_ptr and shouldn't throw.

Effects: First empties target tree calling void disposer::operator()(node_ptr) for every node of the tree except the header.

Then, duplicates the entire tree pointed by "source_header" cloning each source node with node_ptr Cloner::operator()(node_ptr) to obtain the nodes of the target tree. If "cloner" throws, the cloned target nodes are disposed using void disposer(node_ptr).

Complexity: Linear to the number of element of the source tree plus the. number of elements of tree target tree when calling this function.

Throws: If cloner functor throws. If this happens target nodes are disposed.

Requires: "header" must be the header node of a tree. KeyNodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. KeyNodePtrCompare can compare KeyType with tree's node_ptrs.

Effects: Returns an node_ptr to the first element that is not less than "key" according to "comp" or "header" if that element does not exist.

Requires: "header" must be the header node of a tree. KeyNodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. KeyNodePtrCompare can compare KeyType with tree's node_ptrs.

Effects: Returns an node_ptr to the first element that is greater than "key" according to "comp" or "header" if that element does not exist.

Requires: "header" must be the header node of a tree. KeyNodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. KeyNodePtrCompare can compare KeyType with tree's node_ptrs.

Effects: Returns an node_ptr to the element that is equivalent to "key" according to "comp" or "header" if that element does not exist.

Requires: "header" must be the header node of a tree. KeyNodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. KeyNodePtrCompare can compare KeyType with tree's node_ptrs.

Effects: Returns an a pair of node_ptr delimiting a range containing all elements that are equivalent to "key" according to "comp" or an empty range that indicates the position where those elements would be if they there are no equivalent elements.

Requires: "h" must be the header node of a tree. NodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. NodePtrCompare compares two node_ptrs. NodePtrPriorityCompare is a priority function object that induces a strict weak ordering compatible with the one used to create the the tree. NodePtrPriorityCompare compares two node_ptrs.

Effects: Inserts new_node into the tree before the upper bound according to "comp" and rotates the tree according to "pcomp".

Complexity: Average complexity for insert element is at most logarithmic.

Requires: "h" must be the header node of a tree. NodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. NodePtrCompare compares two node_ptrs. NodePtrPriorityCompare is a priority function object that induces a strict weak ordering compatible with the one used to create the the tree. NodePtrPriorityCompare compares two node_ptrs.

Effects: Inserts new_node into the tree before the upper bound according to "comp" and rotates the tree according to "pcomp".

Complexity: Average complexity for insert element is at most logarithmic.

Requires: "header" must be the header node of a tree. NodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. NodePtrCompare compares two node_ptrs. "hint" is node from the "header"'s tree. NodePtrPriorityCompare is a priority function object that induces a strict weak ordering compatible with the one used to create the the tree. NodePtrPriorityCompare compares two node_ptrs.

Effects: Inserts new_node into the tree, using "hint" as a hint to where it will be inserted. If "hint" is the upper_bound the insertion takes constant time (two comparisons in the worst case). Rotates the tree according to "pcomp".

Complexity: Logarithmic in general, but it is amortized constant time if new_node is inserted immediately before "hint".

Requires: "header" must be the header node of a tree. "pos" must be a valid node of the tree (including header end) node. "pos" must be a node pointing to the successor to "new_node" once inserted according to the order of already inserted nodes. This function does not check "pos" and this precondition must be guaranteed by the caller. NodePtrPriorityCompare is a priority function object that induces a strict weak ordering compatible with the one used to create the the tree. NodePtrPriorityCompare compares two node_ptrs.

Effects: Inserts new_node into the tree before "pos" and rotates the tree according to "pcomp".

Complexity: Constant-time.

Throws: If "pcomp" throws, strong guarantee.

Note: If "pos" is not the successor of the newly inserted "new_node" tree invariants might be broken.

Requires: "header" must be the header node of a tree. "new_node" must be, according to the used ordering no less than the greatest inserted key. NodePtrPriorityCompare is a priority function object that induces a strict weak ordering compatible with the one used to create the the tree. NodePtrPriorityCompare compares two node_ptrs.

Effects: Inserts x into the tree in the last position and rotates the tree according to "pcomp".

Complexity: Constant-time.

Throws: If "pcomp" throws, strong guarantee.

Note: If "new_node" is less than the greatest inserted key tree invariants are broken. This function is slightly faster than using "insert_before".

Requires: "header" must be the header node of a tree. "new_node" must be, according to the used ordering, no greater than the lowest inserted key. NodePtrPriorityCompare is a priority function object that induces a strict weak ordering compatible with the one used to create the the tree. NodePtrPriorityCompare compares two node_ptrs.

Effects: Inserts x into the tree in the first position and rotates the tree according to "pcomp".

Complexity: Constant-time.

Throws: If "pcomp" throws, strong guarantee.

Note: If "new_node" is greater than the lowest inserted key tree invariants are broken. This function is slightly faster than using "insert_before".

Requires: "header" must be the header node of a tree. KeyNodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. NodePtrCompare compares KeyType with a node_ptr.

Effects: Checks if there is an equivalent node to "key" in the tree according to "comp" and obtains the needed information to realize a constant-time node insertion if there is no equivalent node.

Returns: If there is an equivalent value returns a pair containing a node_ptr to the already present node and false. If there is not equivalent key can be inserted returns true in the returned pair's boolean and fills "commit_data" that is meant to be used with the "insert_commit" function to achieve a constant-time insertion function.

Complexity: Average complexity is at most logarithmic.

Throws: If "comp" throws.

Notes: This function is used to improve performance when constructing a node is expensive and the user does not want to have two equivalent nodes in the tree: 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 node 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 node and use "insert_commit" to insert the node 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_unique_commit" only if no more objects are inserted or erased from the set.

Requires: "header" must be the header node of a tree. KeyNodePtrCompare is a function object that induces a strict weak ordering compatible with the strict weak ordering used to create the the tree. NodePtrCompare compares KeyType with a node_ptr. "hint" is node from the "header"'s tree.

Effects: Checks if there is an equivalent node to "key" in the tree according to "comp" using "hint" as a hint to where it should be inserted and obtains the needed information to realize a constant-time node insertion if there is no equivalent node. If "hint" is the upper_bound the function has constant time complexity (two comparisons in the worst case).

Returns: If there is an equivalent value returns a pair containing a node_ptr to the already present node and false. If there is not equivalent key can be inserted returns true in the returned pair's boolean and fills "commit_data" that is meant to be used with the "insert_commit" function to achieve a constant-time insertion function.

Complexity: Average complexity is at most logarithmic, but it is amortized constant time if new_node should be inserted immediately before "hint".

Throws: If "comp" throws.

Notes: This function is used to improve performance when constructing a node is expensive and the user does not want to have two equivalent nodes in the tree: 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 node 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 node and use "insert_commit" to insert the node 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_unique_commit" only if no more objects are inserted or erased from the set.

Requires: "header" must be the header node of a tree. "commit_data" must have been obtained from a previous call to "insert_unique_check". No objects should have been inserted or erased from the set between the "insert_unique_check" that filled "commit_data" and the call to "insert_commit".

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

Complexity: Constant time.

Throws: Nothing.

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