| Home | Libraries | People | FAQ | More

## Class template list

boost::intrusive::list

## Synopsis

    template<typename T, class... Options>
    class list {
    public:
      // types
      typedef Config::value_traits                             value_traits;
      typedef real_value_traits::pointer                       pointer;
      typedef real_value_traits::const_pointer                 const_pointer;
      typedef std::iterator_traits< pointer >::value_type      value_type;
      typedef std::iterator_traits< pointer >::reference       reference;
      typedef std::iterator_traits< const_pointer >::reference const_reference;
      typedef std::iterator_traits< pointer >::difference_type difference_type;
      typedef Config::size_type                                size_type;
      typedef list_iterator< list, false >                     iterator;
      typedef list_iterator< list, true >                      const_iterator;
      typedef std::reverse_iterator< iterator >                reverse_iterator;
      typedef std::reverse_iterator< const_iterator >          const_reverse_iterator;
      typedef real_value_traits::node_traits                   node_traits;
      typedef node_traits::node                                node;
      typedef node_traits::node_ptr                            node_ptr;
      typedef node_traits::const_node_ptr                      const_node_ptr;
      typedef circular_list_algorithms< node_traits >          node_algorithms;

      // construct/copy/destruct
      list(const value_traits & = value_traits());
      template<typename Iterator>
        list(Iterator, Iterator, const value_traits & = value_traits());
      ~list();

      // public member functions
      const real_value_traits & get_real_value_traits() const;
      real_value_traits & get_real_value_traits() ;
      void push_back(reference) ;
      void push_front(reference) ;
      void pop_back() ;
      template<typename Disposer> void pop_back_and_dispose(Disposer) ;
      void pop_front() ;
      template<typename Disposer> void pop_front_and_dispose(Disposer) ;
      reference front() ;
      const_reference front() const;
      reference back() ;
      const_reference back() const;
      iterator begin() ;
      const_iterator begin() const;
      const_iterator cbegin() const;
      iterator end() ;
      const_iterator end() const;
      const_iterator cend() 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;
      size_type size() const;
      bool empty() const;
      void swap(list &) ;
      void shift_backwards(size_type = 1) ;
      void shift_forward(size_type = 1) ;
      iterator erase(iterator) ;
      iterator erase(iterator, iterator) ;
      template<typename Disposer> iterator erase_and_dispose(iterator, Disposer) ;
      template<typename Disposer>
        iterator erase_and_dispose(iterator, iterator, Disposer) ;
      void clear() ;
      template<typename Disposer> void clear_and_dispose(Disposer) ;
      template<typename Cloner, typename Disposer>
        void clone_from(const list &, Cloner, Disposer) ;
      iterator insert(iterator, reference) ;
      template<typename Iterator> void insert(iterator, Iterator, Iterator) ;
      template<typename Iterator> void assign(Iterator, Iterator) ;
      template<typename Iterator, typename Disposer>
        void dispose_and_assign(Disposer, Iterator, Iterator) ;
      void splice(iterator, list &) ;
      void splice(iterator, list &, iterator) ;
      void splice(iterator, list &, iterator, iterator) ;
      void splice(iterator, list &, iterator, iterator, difference_type) ;
      void sort() ;
      template<typename Predicate> void sort(Predicate) ;
      void merge(list &) ;
      template<typename Predicate> void merge(list &, Predicate) ;
      void reverse() ;
      void remove(const_reference) ;
      template<typename Disposer>
        void remove_and_dispose(const_reference, Disposer) ;
      template<typename Pred> void remove_if(Pred) ;
      template<typename Pred, typename Disposer>
        void remove_and_dispose_if(Pred, Disposer) ;
      void unique() ;
      template<typename BinaryPredicate> void unique(BinaryPredicate) ;
      template<typename Disposer> void unique_and_dispose(Disposer) ;
      template<typename BinaryPredicate, typename Disposer>
        void unique_and_dispose(BinaryPredicate, Disposer) ;
      iterator iterator_to(reference) ;
      const_iterator iterator_to(const_reference) const;

      // public static functions
      static list & container_from_end_iterator(iterator) ;
      static const list & container_from_end_iterator(const_iterator) ;
      static iterator s_iterator_to(reference) ;
      static const_iterator s_iterator_to(const_reference) ;
      static const bool constant_time_size;
      static const bool stateful_value_traits;
    };

## Description

The class template list is an intrusive container that mimics most of the interface of std::list as described in the C++ standard.

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<>` and `size_type<>`.

### `list` public construct/copy/destruct

1.     list(const value_traits & v_traits = value_traits());

   Effects: constructs an empty list.

   Complexity: Constant

   Throws: If real_value_traits::node_traits::node constructor throws (this does not happen with predefined Boost.Intrusive hooks).

2.     template<typename Iterator>
         list(Iterator b, Iterator e, const value_traits & v_traits = value_traits());

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

   Effects: Constructs a list equal to the range [first,last).

   Complexity: Linear in std::distance(b, e). No copy constructors are called.

   Throws: If real_value_traits::node_traits::node constructor throws (this does not happen with predefined Boost.Intrusive hooks).

3.     ~list();

   Effects: If it's not a safe-mode or an auto-unlink value_type the destructor does nothing (ie. no code is generated). Otherwise it detaches all elements from this. In this case the objects in the list are not deleted (i.e. no destructors are called), but the hooks according to the ValueTraits template parameter are set to their default value.

   Complexity: Linear to the number of elements in the list, if it's a safe-mode or auto-unlink value . Otherwise constant.

### `list` public member functions

1.     const real_value_traits & get_real_value_traits() const;

2.     real_value_traits & get_real_value_traits() ;

3.     void push_back(reference value) ;

   Requires: value must be an lvalue.

   Effects: Inserts the value in the back of the list. No copy constructors are called.

   Throws: Nothing.

   Complexity: Constant.

   Note: Does not affect the validity of iterators and references.

4.     void push_front(reference value) ;

   Requires: value must be an lvalue.

   Effects: Inserts the value in the front of the list. No copy constructors are called.

   Throws: Nothing.

   Complexity: Constant.

   Note: Does not affect the validity of iterators and references.

5.     void pop_back() ;

   Effects: Erases the last element of the list. No destructors are called.

   Throws: Nothing.

   Complexity: Constant.

   Note: Invalidates the iterators (but not the references) to the erased element.

6.     template<typename Disposer> void pop_back_and_dispose(Disposer disposer) ;

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

   Effects: Erases the last element of the list. No destructors are called. Disposer::operator()(pointer) is called for the removed element.

   Throws: Nothing.

   Complexity: Constant.

   Note: Invalidates the iterators to the erased element.

7.     void pop_front() ;

   Effects: Erases the first element of the list. No destructors are called.

   Throws: Nothing.

   Complexity: Constant.

   Note: Invalidates the iterators (but not the references) to the erased element.

8.     template<typename Disposer> void pop_front_and_dispose(Disposer disposer) ;

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

   Effects: Erases the first element of the list. No destructors are called. Disposer::operator()(pointer) is called for the removed element.

   Throws: Nothing.

   Complexity: Constant.

   Note: Invalidates the iterators to the erased element.

9.     reference front() ;

   Effects: Returns a reference to the first element of the list.

   Throws: Nothing.

   Complexity: Constant.

10.     const_reference front() const;

    Effects: Returns a const_reference to the first element of the list.

    Throws: Nothing.

    Complexity: Constant.

11.     reference back() ;

    Effects: Returns a reference to the last element of the list.

    Throws: Nothing.

    Complexity: Constant.

12.     const_reference back() const;

    Effects: Returns a const_reference to the last element of the list.

    Throws: Nothing.

    Complexity: Constant.

13.     iterator begin() ;

    Effects: Returns an iterator to the first element contained in the list.

    Throws: Nothing.

    Complexity: Constant.

14.     const_iterator begin() const;

    Effects: Returns a const_iterator to the first element contained in the list.

    Throws: Nothing.

    Complexity: Constant.

15.     const_iterator cbegin() const;

    Effects: Returns a const_iterator to the first element contained in the list.

    Throws: Nothing.

    Complexity: Constant.

16.     iterator end() ;

    Effects: Returns an iterator to the end of the list.

    Throws: Nothing.

    Complexity: Constant.

17.     const_iterator end() const;

    Effects: Returns a const_iterator to the end of the list.

    Throws: Nothing.

    Complexity: Constant.

18.     const_iterator cend() const;

    Effects: Returns a constant iterator to the end of the list.

    Throws: Nothing.

    Complexity: Constant.

19.     reverse_iterator rbegin() ;

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

    Throws: Nothing.

    Complexity: Constant.

20.     const_reverse_iterator rbegin() const;

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

    Throws: Nothing.

    Complexity: Constant.

21.     const_reverse_iterator crbegin() const;

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

    Throws: Nothing.

    Complexity: Constant.

22.     reverse_iterator rend() ;

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

    Throws: Nothing.

    Complexity: Constant.

23.     const_reverse_iterator rend() const;

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

    Throws: Nothing.

    Complexity: Constant.

24.     const_reverse_iterator crend() const;

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

    Throws: Nothing.

    Complexity: Constant.

25.     size_type size() const;

    Effects: Returns the number of the elements contained in the list.

    Throws: Nothing.

    Complexity: Linear to the number of elements contained in the list. if constant-time size option is disabled. Constant time otherwise.

    Note: Does not affect the validity of iterators and references.

26.     bool empty() const;

    Effects: Returns true if the list contains no elements.

    Throws: Nothing.

    Complexity: Constant.

    Note: Does not affect the validity of iterators and references.

27.     void swap(list & other) ;

    Effects: Swaps the elements of x and *this.

    Throws: Nothing.

    Complexity: Constant.

    Note: Does not affect the validity of iterators and references.

28.     void shift_backwards(size_type n = 1) ;

    Effects: Moves backwards all the elements, so that the first element becomes the second, the second becomes the third... the last element becomes the first one.

    Throws: Nothing.

    Complexity: Linear to the number of shifts.

    Note: Does not affect the validity of iterators and references.

29.     void shift_forward(size_type n = 1) ;

    Effects: Moves forward all the elements, so that the second element becomes the first, the third becomes the second... the first element becomes the last one.

    Throws: Nothing.

    Complexity: Linear to the number of shifts.

    Note: Does not affect the validity of iterators and references.

30.     iterator erase(iterator i) ;

    Effects: Erases the element pointed by i of the list. No destructors are called.

    Returns: the first element remaining beyond the removed element, or end() if no such element exists.

    Throws: Nothing.

    Complexity: Constant.

    Note: Invalidates the iterators (but not the references) to the erased element.

31.     iterator erase(iterator b, iterator e) ;

    Requires: first and last must be valid iterator to elements in *this.

    Effects: Erases the element range pointed by b and e No destructors are called.

    Returns: the first element remaining beyond the removed elements, or end() if no such element exists.

    Throws: Nothing.

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

    Note: Invalidates the iterators (but not the references) to the erased elements.

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

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

    Effects: Erases the element pointed by i of the list. No destructors are called. Disposer::operator()(pointer) is called for the removed element.

    Returns: the first element remaining beyond the removed element, or end() if no such element exists.

    Throws: Nothing.

    Complexity: Constant.

    Note: Invalidates the iterators to the erased element.

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

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

    Effects: Erases the element range pointed by b and e No destructors are called. Disposer::operator()(pointer) is called for the removed elements.

    Returns: the first element remaining beyond the removed elements, or end() if no such element exists.

    Throws: Nothing.

    Complexity: Linear to the number of elements erased.

    Note: Invalidates the iterators to the erased elements.

34.     void clear() ;

    Effects: Erases all the elements of the container. No destructors are called.

    Throws: Nothing.

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

    Note: Invalidates the iterators (but not the references) to the erased elements.

35.     template<typename Disposer> void clear_and_dispose(Disposer disposer) ;

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

    Effects: Erases all the elements of the container. No destructors are called. Disposer::operator()(pointer) is called for the removed elements.

    Throws: Nothing.

    Complexity: Linear to the number of elements of the list.

    Note: Invalidates the iterators to the erased elements.

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

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

    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.

    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. Basic guarantee.

37.     iterator insert(iterator p, reference value) ;

    Requires: value must be an lvalue and p must be a valid iterator of *this.

    Effects: Inserts the value before the position pointed by p.

    Returns: An iterator to the inserted element.

    Throws: Nothing.

    Complexity: Constant time. No copy constructors are called.

    Note: Does not affect the validity of iterators and references.

38.     template<typename Iterator> void insert(iterator p, Iterator b, Iterator e) ;

    Requires: Dereferencing iterator must yield an lvalue of type value_type and p must be a valid iterator of *this.

    Effects: Inserts the range pointed by b and e before the position p. No copy constructors are called.

    Throws: Nothing.

    Complexity: Linear to the number of elements inserted.

    Note: Does not affect the validity of iterators and references.

39.     template<typename Iterator> void assign(Iterator b, Iterator e) ;

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

    Effects: Clears the list and inserts the range pointed by b and e. No destructors or copy constructors are called.

    Throws: Nothing.

    Complexity: Linear to the number of elements inserted plus linear to the elements contained in the list if it's a safe-mode or auto-unlink value. Linear to the number of elements inserted in the list otherwise.

    Note: Invalidates the iterators (but not the references) to the erased elements.

40.     template<typename Iterator, typename Disposer>
          void dispose_and_assign(Disposer disposer, Iterator b, Iterator e) ;

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

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

    Effects: Clears the list and inserts the range pointed by b and e. No destructors or copy constructors are called. Disposer::operator()(pointer) is called for the removed elements.

    Throws: Nothing.

    Complexity: Linear to the number of elements inserted plus linear to the elements contained in the list.

    Note: Invalidates the iterators (but not the references) to the erased elements.

41.     void splice(iterator p, list & x) ;

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

    Effects: Transfers all the elements of list x to this list, before the the element pointed by p. No destructors or copy constructors are called.

    Throws: Nothing.

    Complexity: Constant.

    Note: Iterators of values obtained from list x now point to elements of this list. Iterators of this list and all the references are not invalidated.

42.     void splice(iterator p, list & x, iterator new_ele) ;

    Requires: p must be a valid iterator of *this. new_ele must point to an element contained in list x.

    Effects: Transfers the value pointed by new_ele, from list x to this list, before the the element pointed by p. No destructors or copy constructors are called. If p == new_ele or p == ++new_ele, this function is a null operation.

    Throws: Nothing.

    Complexity: Constant.

    Note: Iterators of values obtained from list x now point to elements of this list. Iterators of this list and all the references are not invalidated.

43.     void splice(iterator p, list & x, iterator start, iterator end) ;

    Requires: p must be a valid iterator of *this. start and end must point to elements contained in list x.

    Effects: Transfers the range pointed by start and end from list x to this list, before the the element pointed by p. No destructors or copy constructors are called.

    Throws: Nothing.

    Complexity: Linear to the number of elements transferred if constant-time size option is enabled. Constant-time otherwise.

    Note: Iterators of values obtained from list x now point to elements of this list. Iterators of this list and all the references are not invalidated.

44.     void splice(iterator p, list & x, iterator start, iterator end,
                    difference_type n) ;

    Requires: p must be a valid iterator of *this. start and end must point to elements contained in list x. n == std::distance(start, end)

    Effects: Transfers the range pointed by start and end from list x to this list, before the the element pointed by p. No destructors or copy constructors are called.

    Throws: Nothing.

    Complexity: Constant.

    Note: Iterators of values obtained from list x now point to elements of this list. Iterators of this list and all the references are not invalidated.

45.     void sort() ;

    Effects: This function sorts the list *this according to std::less<value_type>. The sort is stable, that is, the relative order of equivalent elements is preserved.

    Throws: If real_value_traits::node_traits::node constructor throws (this does not happen with predefined Boost.Intrusive hooks) or std::less<value_type> throws. Basic guarantee.

    Notes: Iterators and references are not invalidated.

    Complexity: The number of comparisons is approximately N log N, where N is the list's size.

46.     template<typename Predicate> void sort(Predicate p) ;

    Requires: p must be a comparison function that induces a strict weak ordering

    Effects: This function sorts the list *this according to p. The sort is stable, that is, the relative order of equivalent elements is preserved.

    Throws: If real_value_traits::node_traits::node constructor throws (this does not happen with predefined Boost.Intrusive hooks) or the predicate throws. Basic guarantee.

    Notes: This won't throw if list_base_hook<> or list_member_hook are used. Iterators and references are not invalidated.

    Complexity: The number of comparisons is approximately N log N, where N is the list's size.

47.     void merge(list & x) ;

    Effects: This function removes all of x's elements and inserts them in order into *this according to std::less<value_type>. The merge is stable; that is, if an element from *this is equivalent to one from x, then the element from *this will precede the one from x.

    Throws: If std::less<value_type> throws. Basic guarantee.

    Complexity: This function is linear time: it performs at most size() + x.size() - 1 comparisons.

    Note: Iterators and references are not invalidated

48.     template<typename Predicate> void merge(list & x, Predicate p) ;

    Requires: p must be a comparison function that induces a strict weak ordering and both *this and x must be sorted according to that ordering The lists x and *this must be distinct.

    Effects: This function removes all of x's elements and inserts them in order into *this. The merge is stable; that is, if an element from *this is equivalent to one from x, then the element from *this will precede the one from x.

    Throws: If the predicate throws. Basic guarantee.

    Complexity: This function is linear time: it performs at most size() + x.size() - 1 comparisons.

    Note: Iterators and references are not invalidated.

49.     void reverse() ;

    Effects: Reverses the order of elements in the list.

    Throws: Nothing.

    Complexity: This function is linear time.

    Note: Iterators and references are not invalidated

50.     void remove(const_reference value) ;

    Effects: Removes all the elements that compare equal to value. No destructors are called.

    Throws: If std::equal_to<value_type> throws. Basic guarantee.

    Complexity: Linear time. It performs exactly size() comparisons for equality.

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

51.     template<typename Disposer>
          void remove_and_dispose(const_reference value, Disposer disposer) ;

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

    Effects: Removes all the elements that compare equal to value. Disposer::operator()(pointer) is called for every removed element.

    Throws: If std::equal_to<value_type> throws. Basic guarantee.

    Complexity: Linear time. It performs exactly size() comparisons for equality.

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

52.     template<typename Pred> void remove_if(Pred pred) ;

    Effects: Removes all the elements for which a specified predicate is satisfied. No destructors are called.

    Throws: If pred throws. Basic guarantee.

    Complexity: Linear time. It performs exactly size() calls to the predicate.

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

53.     template<typename Pred, typename Disposer>
          void remove_and_dispose_if(Pred pred, Disposer disposer) ;

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

    Effects: Removes all the elements for which a specified predicate is satisfied. Disposer::operator()(pointer) is called for every removed element.

    Throws: If pred throws. Basic guarantee.

    Complexity: Linear time. It performs exactly size() comparisons for equality.

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

54.     void unique() ;

    Effects: Removes adjacent duplicate elements or adjacent elements that are equal from the list. No destructors are called.

    Throws: If std::equal_to<value_type throws. Basic guarantee.

    Complexity: Linear time (size()-1 comparisons calls to pred()).

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

55.     template<typename BinaryPredicate> void unique(BinaryPredicate pred) ;

    Effects: Removes adjacent duplicate elements or adjacent elements that satisfy some binary predicate from the list. No destructors are called.

    Throws: If pred throws. Basic guarantee.

    Complexity: Linear time (size()-1 comparisons equality comparisons).

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

56.     template<typename Disposer> void unique_and_dispose(Disposer disposer) ;

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

    Effects: Removes adjacent duplicate elements or adjacent elements that are equal from the list. Disposer::operator()(pointer) is called for every removed element.

    Throws: If std::equal_to<value_type throws. Basic guarantee.

    Complexity: Linear time (size()-1) comparisons equality comparisons.

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

57.     template<typename BinaryPredicate, typename Disposer>
          void unique_and_dispose(BinaryPredicate pred, Disposer disposer) ;

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

    Effects: Removes adjacent duplicate elements or adjacent elements that satisfy some binary predicate from the list. Disposer::operator()(pointer) is called for every removed element.

    Throws: If pred throws. Basic guarantee.

    Complexity: Linear time (size()-1) comparisons equality comparisons.

    Note: The relative order of elements that are not removed is unchanged, and iterators to elements that are not removed remain valid.

58.     iterator iterator_to(reference value) ;

    Requires: value must be a reference to a value inserted in a list.

    Effects: This function returns a const_iterator pointing to the element

    Throws: Nothing.

    Complexity: Constant time.

    Note: Iterators and references are not invalidated.

59.     const_iterator iterator_to(const_reference value) const;

    Requires: value must be a const reference to a value inserted in a list.

    Effects: This function returns an iterator pointing to the element.

    Throws: Nothing.

    Complexity: Constant time.

    Note: Iterators and references are not invalidated.

### `list` public static functions

1.     static list & container_from_end_iterator(iterator end_iterator) ;

   Precondition: end_iterator must be a valid end iterator of list.

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

   Throws: Nothing.

   Complexity: Constant.

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

   Precondition: end_iterator must be a valid end const_iterator of list.

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

   Throws: Nothing.

   Complexity: Constant.

3.     static iterator s_iterator_to(reference value) ;

   Requires: value must be a reference to a value inserted in a list.

   Effects: This function returns a const_iterator pointing to the element

   Throws: Nothing.

   Complexity: Constant time.

   Note: Iterators and references are not invalidated. This static function is available only if the value traits is stateless.

4.     static const_iterator s_iterator_to(const_reference value) ;

   Requires: value must be a const reference to a value inserted in a list.

   Effects: This function returns an iterator pointing to the element.

   Throws: Nothing.

   Complexity: Constant time.

   Note: Iterators and references are not invalidated. This static function is available only if the value traits is stateless.