| Home | Libraries | People | FAQ | More

## Class template treap

boost::intrusive::treap

## Synopsis

    // In header: <boost/intrusive/treap.hpp>

    template<typename T, class... Options>
    class treap {
    public:
      // types
      typedef ValueTraits                                    value_traits;
      typedef implementation_defined::pointer                pointer;
      typedef implementation_defined::const_pointer          const_pointer;
      typedef implementation_defined::value_type             value_type;
      typedef implementation_defined::key_type               key_type;
      typedef implementation_defined::key_of_value           key_of_value;
      typedef implementation_defined::reference              reference;
      typedef implementation_defined::const_reference        const_reference;
      typedef implementation_defined::difference_type        difference_type;
      typedef implementation_defined::size_type              size_type;
      typedef implementation_defined::value_compare          value_compare;
      typedef implementation_defined::key_compare            key_compare;
      typedef implementation_defined::iterator               iterator;
      typedef implementation_defined::const_iterator         const_iterator;
      typedef implementation_defined::reverse_iterator       reverse_iterator;
      typedef implementation_defined::const_reverse_iterator const_reverse_iterator;
      typedef implementation_defined::node_traits            node_traits;
      typedef implementation_defined::node                   node;
      typedef implementation_defined::node_ptr               node_ptr;
      typedef implementation_defined::const_node_ptr         const_node_ptr;
      typedef implementation_defined                         node_algorithms;
      typedef implementation_defined                         priority_compare;
      typedef unspecified                                    key_node_prio_comp_t;
      typedef node_algorithms::insert_commit_data            insert_commit_data;

      // construct/copy/destruct
      treap();
      explicit treap(const key_compare &,
                     const priority_compare & = priority_compare(),
                     const value_traits & = value_traits());
      template<typename Iterator>
        treap(bool, Iterator, Iterator, const key_compare & = key_compare(),
              const priority_compare & = priority_compare(),
              const value_traits & = value_traits());
      treap(treap &&);
      treap & operator=(treap &&);
      ~treap();

      // public member functions
      template<typename KeyPrioComp>
        unspecified key_node_prio_comp(KeyPrioComp) const;
      iterator begin();
      const_iterator begin() const;
      const_iterator cbegin() const;
      iterator end();
      const_iterator end() const;
      const_iterator cend() const;
      iterator top();
      const_iterator top() const;
      const_iterator ctop() const;
      reverse_iterator rbegin();
      const_reverse_iterator rbegin() const;
      const_reverse_iterator crbegin() const;
      reverse_iterator rend();
      const_reverse_iterator rend() const;
      const_reverse_iterator crend() const;
      reverse_iterator rtop();
      const_reverse_iterator rtop() const;
      const_reverse_iterator crtop() const;
      key_compare key_comp() const;
      value_compare value_comp() const;
      bool empty() const;
      size_type size() const;
      priority_compare priority_comp() const;
      void swap(treap &);
      template<typename Cloner, typename Disposer>
        void clone_from(const treap &, Cloner, Disposer);
      template<typename Cloner, typename Disposer>
        void clone_from(treap &&, Cloner, Disposer);
      iterator insert_equal(reference);
      iterator insert_equal(const_iterator, reference);
      template<typename Iterator> void insert_equal(Iterator, Iterator);
      std::pair< iterator, bool > insert_unique(reference);
      iterator insert_unique(const_iterator, reference);
      template<typename Iterator> void insert_unique(Iterator, Iterator);
      std::pair< iterator, bool >
      insert_unique_check(const key_type &, insert_commit_data &);
      std::pair< iterator, bool >
      insert_unique_check(const_iterator, const key_type &, insert_commit_data &);
      template<typename KeyType, typename KeyTypeKeyCompare,
               typename KeyValuePrioCompare>
        std::pair< iterator BOOST_INTRUSIVE_I bool >
        insert_unique_check(const KeyType &, KeyTypeKeyCompare,
                            KeyValuePrioCompare, insert_commit_data &);
      template<typename KeyType, typename KeyTypeKeyCompare,
               typename KeyValuePrioCompare>
        std::pair< iterator, bool >
        insert_unique_check(const_iterator, const KeyType &, KeyTypeKeyCompare,
                            KeyValuePrioCompare, insert_commit_data &);
      iterator insert_unique_commit(reference, const insert_commit_data &);
      iterator insert_before(const_iterator, reference);
      void push_back(reference);
      void push_front(reference);
      iterator erase(const_iterator);
      iterator erase(const_iterator, const_iterator);
      size_type erase(const key_type &);
      template<typename KeyType, typename KeyTypeKeyCompare>
        size_type erase(const KeyType &, KeyTypeKeyCompare);
      template<typename Disposer>
        iterator erase_and_dispose(const_iterator, Disposer);
      template<typename Disposer>
        iterator erase_and_dispose(const_iterator, const_iterator, Disposer);
      template<typename Disposer>
        size_type erase_and_dispose(const key_type &, Disposer);
      template<typename KeyType, typename KeyTypeKeyCompare, typename Disposer>
        size_type erase_and_dispose(const KeyType &, KeyTypeKeyCompare, Disposer);
      void clear();
      template<typename Disposer> void clear_and_dispose(Disposer);
      template<typename ExtraChecker> void check(ExtraChecker) const;
      void check() const;
      size_type count(const key_type &) const;
      template<typename KeyType, typename KeyTypeKeyCompare>
        size_type count(const KeyType &, KeyTypeKeyCompare) const;
      iterator lower_bound(const key_type &);
      template<typename KeyType, typename KeyTypeKeyCompare>
        iterator lower_bound(const KeyType &, KeyTypeKeyCompare);
      const_iterator lower_bound(const key_type &) const;
      template<typename KeyType, typename KeyTypeKeyCompare>
        const_iterator lower_bound(const KeyType &, KeyTypeKeyCompare) const;
      iterator upper_bound(const key_type &);
      template<typename KeyType, typename KeyTypeKeyCompare>
        iterator upper_bound(const KeyType &, KeyTypeKeyCompare);
      const_iterator upper_bound(const key_type &) const;
      template<typename KeyType, typename KeyTypeKeyCompare>
        const_iterator upper_bound(const KeyType &, KeyTypeKeyCompare) const;
      iterator find(const key_type &);
      template<typename KeyType, typename KeyTypeKeyCompare>
        iterator find(const KeyType &, KeyTypeKeyCompare);
      const_iterator find(const key_type &) const;
      template<typename KeyType, typename KeyTypeKeyCompare>
        const_iterator find(const KeyType &, KeyTypeKeyCompare) const;
      std::pair< iterator, iterator > equal_range(const key_type &);
      template<typename KeyType, typename KeyTypeKeyCompare>
        std::pair< iterator, iterator >
        equal_range(const KeyType &, KeyTypeKeyCompare);
      std::pair< const_iterator, const_iterator >
      equal_range(const key_type &) const;
      template<typename KeyType, typename KeyTypeKeyCompare>
        std::pair< const_iterator, const_iterator >
        equal_range(const KeyType &, KeyTypeKeyCompare) const;
      std::pair< iterator, iterator >
      bounded_range(const key_type &, const key_type &, bool, bool);
      template<typename KeyType, typename KeyTypeKeyCompare>
        std::pair< iterator, iterator >
        bounded_range(const KeyType &, const KeyType &, KeyTypeKeyCompare, bool,
                      bool);
      std::pair< const_iterator, const_iterator >
      bounded_range(const key_type &, const key_type &, bool, bool) const;
      template<typename KeyType, typename KeyTypeKeyCompare>
        std::pair< const_iterator, const_iterator >
        bounded_range(const KeyType &, const KeyType &, KeyTypeKeyCompare, bool,
                      bool) const;
      iterator iterator_to(reference);
      const_iterator iterator_to(const_reference) const;
      pointer unlink_leftmost_without_rebalance();
      void replace_node(iterator, reference);
      void remove_node(reference);

      // public static functions
      static treap & container_from_end_iterator(iterator);
      static const treap & container_from_end_iterator(const_iterator);
      static treap & container_from_iterator(iterator);
      static const treap & container_from_iterator(const_iterator);
      static iterator s_iterator_to(reference);
      static const_iterator s_iterator_to(const_reference);
      static void init_node(reference);

      // public data members
      static const bool constant_time_size;
      static const bool stateful_value_traits;
      static const bool safemode_or_autounlink;
    };

## Description

The class template treap is an intrusive treap container that is used to construct intrusive set and multiset containers. The no-throw guarantee holds only, if the key_compare object and priority_compare object don'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<>`, `compare<>` and `priority_compare<>`

### `treap` public construct/copy/destruct

1.     treap();

   Effects: Constructs an empty container.

   Complexity: Constant.

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

2.     explicit treap(const key_compare & cmp,
                      const priority_compare & pcmp = priority_compare(),
                      const value_traits & v_traits = value_traits());

   Effects: Constructs an empty container.

   Complexity: Constant.

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

3.     template<typename Iterator>
         treap(bool unique, Iterator b, Iterator e,
               const key_compare & cmp = key_compare(),
               const priority_compare & pcmp = priority_compare(),
               const value_traits & v_traits = value_traits());

   Requires: Dereferencing iterator must yield an lvalue of type value_type. cmp must be a comparison function that induces a strict weak ordering.

   Effects: Constructs an empty container and inserts elements from [b, e).

   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 key_compare/priority_compare objects throw. Basic guarantee.

4.     treap(treap && x);

   Effects: to-do

5.     treap & operator=(treap && x);

   Effects: to-do

6.     ~treap();

   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.

### `treap` public member functions

1.     template<typename KeyPrioComp>
         unspecified key_node_prio_comp(KeyPrioComp keypriocomp) const;

2.     iterator begin();

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

   Complexity: Constant.

   Throws: Nothing.

3.     const_iterator begin() const;

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

   Complexity: Constant.

   Throws: Nothing.

4.     const_iterator cbegin() const;

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

   Complexity: Constant.

   Throws: Nothing.

5.     iterator end();

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

   Complexity: Constant.

   Throws: Nothing.

6.     const_iterator end() const;

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

   Complexity: Constant.

   Throws: Nothing.

7.     const_iterator cend() const;

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

   Complexity: Constant.

   Throws: Nothing.

8.     iterator top();

   Effects: Returns an iterator pointing to the highest priority object of the treap.

   Complexity: Constant.

   Throws: Nothing.

9.     const_iterator top() const;

   Effects: Returns a const_iterator pointing to the highest priority object of the treap..

   Complexity: Constant.

   Throws: Nothing.

10.     const_iterator ctop() const;

    Effects: Returns a const_iterator pointing to the highest priority object of the treap..

    Complexity: Constant.

    Throws: Nothing.

11.     reverse_iterator rbegin();

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

    Complexity: Constant.

    Throws: Nothing.

12.     const_reverse_iterator rbegin() const;

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

    Complexity: Constant.

    Throws: Nothing.

13.     const_reverse_iterator crbegin() const;

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

    Complexity: Constant.

    Throws: Nothing.

14.     reverse_iterator rend();

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

    Complexity: Constant.

    Throws: Nothing.

15.     const_reverse_iterator rend() const;

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

    Complexity: Constant.

    Throws: Nothing.

16.     const_reverse_iterator crend() const;

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

    Complexity: Constant.

    Throws: Nothing.

17.     reverse_iterator rtop();

    Effects: Returns a reverse_iterator pointing to the highest priority object of the reversed treap.

    Complexity: Constant.

    Throws: Nothing.

18.     const_reverse_iterator rtop() const;

    Effects: Returns a const_reverse_iterator pointing to the highest priority objec of the reversed treap.

    Complexity: Constant.

    Throws: Nothing.

19.     const_reverse_iterator crtop() const;

    Effects: Returns a const_reverse_iterator pointing to the highest priority object of the reversed treap.

    Complexity: Constant.

    Throws: Nothing.

20.     key_compare key_comp() const;

    Effects: Returns the key_compare object used by the container.

    Complexity: Constant.

    Throws: If key_compare copy-constructor throws.

21.     value_compare value_comp() const;

    Effects: Returns the value_compare object used by the container.

    Complexity: Constant.

    Throws: If value_compare copy-constructor throws.

22.     bool empty() const;

    Effects: Returns true if the container is empty.

    Complexity: Constant.

    Throws: Nothing.

23.     size_type size() 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.

    Throws: Nothing.

24.     priority_compare priority_comp() const;

    Effects: Returns the priority_compare object used by the container.

    Complexity: Constant.

    Throws: If priority_compare copy-constructor throws.

25.     void swap(treap & other);

    Effects: Swaps the contents of two treaps.

    Complexity: Constant.

    Throws: If the comparison functor's swap call throws.

26.     template<typename Cloner, typename Disposer>
          void clone_from(const treap & src, Cloner cloner, Disposer disposer);

    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).

    Complexity: Linear to erased plus inserted elements.

    Throws: If cloner throws or predicate copy assignment throws. Basic guarantee.

27.     template<typename Cloner, typename Disposer>
          void clone_from(treap && src, Cloner cloner, Disposer disposer);

    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()(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).

    Complexity: Linear to erased plus inserted elements.

    Throws: If cloner throws or predicate copy assignment throws. Basic guarantee.

28.     iterator insert_equal(reference value);

    Requires: value must be an lvalue

    Effects: Inserts value into the container before the upper bound.

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

    Throws: If the internal key_compare or priority_compare functions throw. Strong guarantee.

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

29.     iterator insert_equal(const_iterator hint, reference value);

    Requires: value must be an lvalue, and "hint" must be a valid iterator.

    Effects: Inserts x into the container, 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)

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

    Throws: If the internal key_compare or priority_compare functions throw. Strong guarantee.

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

30.     template<typename Iterator> void insert_equal(Iterator b, Iterator e);

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

    Effects: Inserts a each element of a range into the container before the upper bound of the key of each element.

    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 key_comp().

    Throws: If the internal key_compare or priority_compare functions throw. Strong guarantee.

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

31.     std::pair< iterator, bool > insert_unique(reference value);

    Requires: value must be an lvalue

    Effects: Inserts value into the container if the value is not already present.

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

    Throws: If the internal key_compare or priority_compare functions throw. Strong guarantee.

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

32.     iterator insert_unique(const_iterator hint, reference value);

    Requires: value must be an lvalue, and "hint" must be a valid iterator

    Effects: Tries to insert x into the container, using "hint" as a hint to where it will be inserted.

    Complexity: Logarithmic in general, but it is amortized constant time (two comparisons in the worst case) if t is inserted immediately before hint.

    Throws: If the internal key_compare or priority_compare functions throw. Strong guarantee.

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

33.     template<typename Iterator> void insert_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 key_comp().

    Throws: If the internal key_compare or priority_compare functions throw. Strong guarantee.

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

34.     std::pair< iterator, bool >
        insert_unique_check(const key_type & key, insert_commit_data & commit_data);

    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.

    Complexity: Average complexity is at most logarithmic.

    Throws: If the comparison or predicate functions throw. Strong guarantee.

    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.

35.     std::pair< iterator, bool >
        insert_unique_check(const_iterator hint, const key_type & key,
                            insert_commit_data & commit_data);

    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.

    Throws: If the comparison or predicate functions throw. Strong guarantee.

    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.

36.     template<typename KeyType, typename KeyTypeKeyCompare,
                 typename KeyValuePrioCompare>
          std::pair< iterator BOOST_INTRUSIVE_I bool >
          insert_unique_check(const KeyType & key, KeyTypeKeyCompare comp,
                              KeyValuePrioCompare key_value_pcomp,
                              insert_commit_data & commit_data);

    Requires: comp must be a comparison function that induces the same strict weak ordering as key_compare. key_value_pcomp must be a comparison function that induces the same strict weak ordering as priority_compare. The difference is that key_value_pcomp and comp compare 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.

    Complexity: Average complexity is at most logarithmic.

    Throws: If the comp or key_value_pcomp ordering functions throw. Strong guarantee.

    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.

37.     template<typename KeyType, typename KeyTypeKeyCompare,
                 typename KeyValuePrioCompare>
          std::pair< iterator, bool >
          insert_unique_check(const_iterator hint, const KeyType & key,
                              KeyTypeKeyCompare comp,
                              KeyValuePrioCompare key_value_pcomp,
                              insert_commit_data & commit_data);

    Requires: comp must be a comparison function that induces the same strict weak ordering as key_compare. key_value_pcomp must be a comparison function that induces the same strict weak ordering as priority_compare. The difference is that key_value_pcomp and comp compare 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.

    Throws: If the comp or key_value_pcomp ordering functions throw. Strong guarantee.

    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.

38.     iterator insert_unique_commit(reference value,
                                      const insert_commit_data & commit_data);

    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 `avl_set` 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.

39.     iterator insert_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: If the internal priority_compare function throws. Strong guarantee.

    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.

40.     void push_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: If the internal priority_compare function throws. Strong guarantee.

    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.

41.     void push_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: If the internal priority_compare function throws. Strong guarantee.

    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.

42.     iterator erase(const_iterator i);

    Effects: Erases the element pointed to by i.

    Complexity: Average complexity for erase element is constant time.

    Throws: if the internal priority_compare function throws. Strong guarantee.

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

43.     iterator erase(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: if the internal priority_compare function throws. Strong guarantee.

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

44.     size_type erase(const key_type & key);

    Effects: Erases all the elements with the given value.

    Returns: The number of erased elements.

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

    Throws: if the internal priority_compare function throws. Strong guarantee.

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

45.     template<typename KeyType, typename KeyTypeKeyCompare>
          size_type erase(const KeyType & key, KeyTypeKeyCompare comp);

    Effects: Erases all the elements with the given key. according to the comparison functor "comp".

    Returns: The number of erased elements.

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

    Throws: if the internal priority_compare function throws. Equivalent guarantee to while(beg != end) erase(beg++);

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

46.     template<typename Disposer>
          iterator erase_and_dispose(const_iterator i, Disposer disposer);

    Requires: Disposer::operator()(pointer) shouldn't throw.

    Effects: Erases the element pointed to by i. Disposer::operator()(pointer) is called for the removed element.

    Complexity: Average complexity for erase element is constant time.

    Throws: if the internal priority_compare function throws. Strong guarantee.

    Note: Invalidates the iterators to the erased elements.

47.     template<typename Disposer>
          iterator erase_and_dispose(const_iterator b, const_iterator e,
                                     Disposer disposer);

    Requires: Disposer::operator()(pointer) shouldn't throw.

    Effects: Erases the range pointed to by b end e. Disposer::operator()(pointer) is called for the removed elements.

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

    Throws: if the internal priority_compare function throws. Strong guarantee.

    Note: Invalidates the iterators to the erased elements.

48.     template<typename Disposer>
          size_type erase_and_dispose(const key_type & key, Disposer disposer);

    Requires: Disposer::operator()(pointer) shouldn't throw.

    Effects: Erases all the elements with the given value. Disposer::operator()(pointer) is called for the removed elements.

    Returns: The number of erased elements.

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

    Throws: if the priority_compare function throws then weak guarantee and heap invariants are broken. The safest thing would be to clear or destroy the container.

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

49.     template<typename KeyType, typename KeyTypeKeyCompare, typename Disposer>
          size_type erase_and_dispose(const KeyType & key, KeyTypeKeyCompare comp,
                                      Disposer disposer);

    Requires: Disposer::operator()(pointer) shouldn't throw.

    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: if the priority_compare function throws then weak guarantee and heap invariants are broken. The safest thing would be to clear or destroy the container.

    Note: Invalidates the iterators to the erased elements.

50.     void clear();

    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.

51.     template<typename Disposer> void clear_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.

52.     template<typename ExtraChecker> void check(ExtraChecker extra_checker) const;

    Effects: Asserts the integrity of the container with additional checks provided by the user.

    Complexity: Linear time.

    Note: The method might not have effect when asserts are turned off (e.g., with NDEBUG). Experimental function, interface might change in future versions.

53.     void check() const;

    Effects: Asserts the integrity of the container.

    Complexity: Linear time.

    Note: The method has no effect when asserts are turned off (e.g., with NDEBUG). Experimental function, interface might change in future versions.

54.     size_type count(const key_type & key) const;

    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.

    Throws: If `key_compare` throws.

55.     template<typename KeyType, typename KeyTypeKeyCompare>
          size_type count(const KeyType & key, KeyTypeKeyCompare comp) const;

    Requires: key is a value such that `*this` is partitioned with respect to comp(nk, key) and !comp(key, nk), with comp(nk, key) implying !comp(key, nk), and nk the key_type of a value_type inserted into `*this`.

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

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

    Throws: If `comp` throws.

56.     iterator lower_bound(const key_type & key);

    Effects: Returns an iterator to the first element whose key is not less than k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

57.     template<typename KeyType, typename KeyTypeKeyCompare>
          iterator lower_bound(const KeyType & key, KeyTypeKeyCompare comp);

    Effects: Returns an iterator to the first element whose key is not less than k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

58.     const_iterator lower_bound(const key_type & key) const;

    Effects: Returns an iterator to the first element whose key is not less than k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

59.     template<typename KeyType, typename KeyTypeKeyCompare>
          const_iterator
          lower_bound(const KeyType & key, KeyTypeKeyCompare comp) const;

    Effects: Returns an iterator to the first element whose key is not less than k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

60.     iterator upper_bound(const key_type & key);

    Effects: Returns an iterator to the first element whose key is greater than k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

61.     template<typename KeyType, typename KeyTypeKeyCompare>
          iterator upper_bound(const KeyType & key, KeyTypeKeyCompare comp);

    Requires: key is a value such that `*this` is partitioned with respect to !comp(key, nk), with nk the key_type of a value_type inserted into `*this`.

    Effects: Returns an iterator to the first element whose key is greater than k according to comp or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `comp` throws.

62.     const_iterator upper_bound(const key_type & key) const;

    Effects: Returns an iterator to the first element whose key is greater than k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

63.     template<typename KeyType, typename KeyTypeKeyCompare>
          const_iterator
          upper_bound(const KeyType & key, KeyTypeKeyCompare comp) const;

    Requires: key is a value such that `*this` is partitioned with respect to !comp(key, nk), with nk the key_type of a value_type inserted into `*this`.

    Effects: Returns an iterator to the first element whose key is greater than k according to comp or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `comp` throws.

64.     iterator find(const key_type & key);

    Effects: Finds an iterator to the first element whose key is k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

65.     template<typename KeyType, typename KeyTypeKeyCompare>
          iterator find(const KeyType & key, KeyTypeKeyCompare comp);

    Requires: key is a value such that `*this` is partitioned with respect to comp(nk, key) and !comp(key, nk), with comp(nk, key) implying !comp(key, nk), and nk the key_type of a value_type inserted into `*this`.

    Effects: Finds an iterator to the first element whose key is k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `comp` throws.

66.     const_iterator find(const key_type & key) const;

    Effects: Finds an iterator to the first element whose key is k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

67.     template<typename KeyType, typename KeyTypeKeyCompare>
          const_iterator find(const KeyType & key, KeyTypeKeyCompare comp) const;

    Requires: key is a value such that `*this` is partitioned with respect to comp(nk, key) and !comp(key, nk), with comp(nk, key) implying !comp(key, nk), and nk the key_type of a value_type inserted into `*this`.

    Effects: Finds an iterator to the first element whose key is k or end() if that element does not exist.

    Complexity: Logarithmic.

    Throws: If `comp` throws.

68.     std::pair< iterator, iterator > equal_range(const key_type & key);

    Effects: Finds a range containing all elements whose key is k or an empty range that indicates the position where those elements would be if they there is no elements with key k.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

69.     template<typename KeyType, typename KeyTypeKeyCompare>
          std::pair< iterator, iterator >
          equal_range(const KeyType & key, KeyTypeKeyCompare comp);

    Requires: key is a value such that `*this` is partitioned with respect to comp(nk, key) and !comp(key, nk), with comp(nk, key) implying !comp(key, nk), with nk the key_type of a value_type inserted into `*this`.

    Effects: Finds a range containing all elements whose key is k or an empty range that indicates the position where those elements would be if they there is no elements with key k.

    Complexity: Logarithmic.

    Throws: If `comp` throws.

70.     std::pair< const_iterator, const_iterator >
        equal_range(const key_type & key) const;

    Effects: Finds a range containing all elements whose key is k or an empty range that indicates the position where those elements would be if they there is no elements with key k.

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

71.     template<typename KeyType, typename KeyTypeKeyCompare>
          std::pair< const_iterator, const_iterator >
          equal_range(const KeyType & key, KeyTypeKeyCompare comp) const;

    Requires: key is a value such that `*this` is partitioned with respect to comp(nk, key) and !comp(key, nk), with comp(nk, key) implying !comp(key, nk), with nk the key_type of a value_type inserted into `*this`.

    Effects: Finds a range containing all elements whose key is k or an empty range that indicates the position where those elements would be if they there is no elements with key k.

    Complexity: Logarithmic.

    Throws: If `comp` throws.

72.     std::pair< iterator, iterator >
        bounded_range(const key_type & lower_key, const key_type & upper_key,
                      bool left_closed, bool right_closed);

    Requires: `upper_key` shall not precede `lower_key` according to key_compare. [key_comp()(upper_key, lower_key) shall be false]

    If `lower_key` is equivalent to `upper_key` [!key_comp()(upper_key, lower_key) && !key_comp()(lower_key, upper_key)] then ('left_closed' || 'right_closed') must be false.

    Effects: Returns an a pair with the following criteria:

    first = lower_bound(lower_key) if left_closed, upper_bound(lower_key) otherwise

    second = upper_bound(upper_key) if right_closed, lower_bound(upper_key) otherwise

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

    Note: This function can be more efficient than calling upper_bound and lower_bound for lower_value and upper_value.

    Note: Experimental function, the interface might change in future releases.

73.     template<typename KeyType, typename KeyTypeKeyCompare>
          std::pair< iterator, iterator >
          bounded_range(const KeyType & lower_key, const KeyType & upper_key,
                        KeyTypeKeyCompare comp, bool left_closed, bool right_closed);

    Requires: `lower_key` is a value such that `*this` is partitioned with respect to comp(nk, lower_key) if left_closed is true, with respect to !comp(lower_key, nk) otherwise.

    `upper_key` is a value such that `*this` is partitioned with respect to !comp(upper_key, nk) if right_closed is true, with respect to comp(nk, upper_key) otherwise.

    `upper_key` shall not precede `lower_key` according to comp [comp(upper_key, lower_key) shall be false]

    If `lower_key` is equivalent to `upper_key` [!comp(upper_key, lower_key) && !comp(lower_key, upper_key)] then ('left_closed' || 'right_closed') must be false.

    Effects: Returns an a pair with the following criteria:

    first = lower_bound(lower_key, comp) if left_closed, upper_bound(lower_key, comp) otherwise

    second = upper_bound(upper_key, comp) if right_closed, lower_bound(upper_key, comp) otherwise

    Complexity: Logarithmic.

    Throws: If `comp` throws.

    Note: This function can be more efficient than calling upper_bound and lower_bound for lower_key and upper_key.

    Note: Experimental function, the interface might change in future releases.

74.     std::pair< const_iterator, const_iterator >
        bounded_range(const key_type & lower_key, const key_type & upper_key,
                      bool left_closed, bool right_closed) const;

    Requires: `upper_key` shall not precede `lower_key` according to key_compare. [key_comp()(upper_key, lower_key) shall be false]

    If `lower_key` is equivalent to `upper_key` [!key_comp()(upper_key, lower_key) && !key_comp()(lower_key, upper_key)] then ('left_closed' || 'right_closed') must be false.

    Effects: Returns an a pair with the following criteria:

    first = lower_bound(lower_key) if left_closed, upper_bound(lower_key) otherwise

    second = upper_bound(upper_key) if right_closed, lower_bound(upper_key) otherwise

    Complexity: Logarithmic.

    Throws: If `key_compare` throws.

    Note: This function can be more efficient than calling upper_bound and lower_bound for lower_value and upper_value.

    Note: Experimental function, the interface might change in future releases.

75.     template<typename KeyType, typename KeyTypeKeyCompare>
          std::pair< const_iterator, const_iterator >
          bounded_range(const KeyType & lower_key, const KeyType & upper_key,
                        KeyTypeKeyCompare comp, bool left_closed, bool right_closed) const;

    Requires: `lower_key` is a value such that `*this` is partitioned with respect to comp(nk, lower_key) if left_closed is true, with respect to !comp(lower_key, nk) otherwise.

    `upper_key` is a value such that `*this` is partitioned with respect to !comp(upper_key, nk) if right_closed is true, with respect to comp(nk, upper_key) otherwise.

    `upper_key` shall not precede `lower_key` according to comp [comp(upper_key, lower_key) shall be false]

    If `lower_key` is equivalent to `upper_key` [!comp(upper_key, lower_key) && !comp(lower_key, upper_key)] then ('left_closed' || 'right_closed') must be false.

    Effects: Returns an a pair with the following criteria:

    first = lower_bound(lower_key, comp) if left_closed, upper_bound(lower_key, comp) otherwise

    second = upper_bound(upper_key, comp) if right_closed, lower_bound(upper_key, comp) otherwise

    Complexity: Logarithmic.

    Throws: If `comp` throws.

    Note: This function can be more efficient than calling upper_bound and lower_bound for lower_key and upper_key.

    Note: Experimental function, the interface might change in future releases.

76.     iterator iterator_to(reference value);

    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.

77.     const_iterator iterator_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.

78.     pointer unlink_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.

79.     void replace_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.

80.     void remove_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.

### `treap` public static functions

1.     static treap & container_from_end_iterator(iterator end_iterator);

   Precondition: end_iterator must be a valid end iterator of the container.

   Effects: Returns a const reference to the container associated to the end iterator

   Throws: Nothing.

   Complexity: Constant.

2.     static const treap & container_from_end_iterator(const_iterator end_iterator);

   Precondition: end_iterator must be a valid end iterator of the container.

   Effects: Returns a const reference to the container associated to the end iterator

   Throws: Nothing.

   Complexity: Constant.

3.     static treap & container_from_iterator(iterator it);

   Precondition: it must be a valid iterator of the container.

   Effects: Returns a const reference to the container associated to the iterator

   Throws: Nothing.

   Complexity: Logarithmic.

4.     static const treap & container_from_iterator(const_iterator it);

   Precondition: it must be a valid iterator of the container.

   Effects: Returns a const reference to the container associated to the iterator

   Throws: Nothing.

   Complexity: Logarithmic.

5.     static iterator s_iterator_to(reference value);

   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.

   Note: This static function is available only if the value traits is stateless.

6.     static const_iterator s_iterator_to(const_reference value);

   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.

   Note: This static function is available only if the value traits is stateless.

7.     static void init_node(reference value);

   Requires: value shall not be in a container.

   Effects: init_node puts the hook of a value in a well-known default state.

   Throws: Nothing.

   Complexity: Constant time.

   Note: This function puts the hook in the well-known default state used by auto_unlink and safe hooks.