Draft 2002-08-08

<list>

The <list> header is one of the standard container template headers. It declares the list class template and a few global functions that operate on list objects.

A list is a sequence container that has constant performance when adding to or removing from any point in the container, but does not random access iterators. Although the standard does not mandate any particular implementation, the obvious choice is to use a doubly-linked list to implement the list class template.

See Chapter 11 for information about containers in general.

list class template

List container

template <typename T, typename Alloc = allocator<T> >
class list
{
public:
  // types:
  typedef typename Alloc::reference reference;
  typedef typename Alloc::const_reference const_reference;
  typedef ... iterator;
  typedef ... const_iterator;
  typedef ... size_type;
  typedef ... difference_type;
  typedef T value_type;
  typedef Alloc allocator_type;
  typedef typename Alloc::pointer pointer;
  typedef typename Alloc::const_pointer const_pointer;
  typedef std::reverse_iterator<iterator> reverse_iterator;
  typedef std::reverse_iterator<const_iterator>
    const_reverse_iterator;

  // construct/copy/destroy:
  explicit list(const Alloc& = Alloc());
  explicit list(size_type n, const T& value = T(),
                const Alloc& = Alloc());
  template <class InputIterator>
  list(InputIterator first, InputIterator last,
       const Alloc& = Alloc());
  list(const list<T,Alloc>& x);
  ~list();
  list<T,Alloc>& operator=(const list<T,Alloc>& x);
  template <class InputIterator>
  void assign(InputIterator first, InputIterator last);
  void assign(size_type n, const T& t);
  allocator_type get_allocator() const;
  // iterators:
  iterator begin();
  const_iterator begin() const;
  iterator end();
  const_iterator end() const;
  reverse_iterator rbegin();
  const_reverse_iterator rbegin() const;
  reverse_iterator rend();
  const_reverse_iterator rend() const;
  // capacity:
  bool empty() const;
  size_type size() const;
  size_type max_size() const;
  void resize(size_type sz, T c = T());
  // element access:
  reference front();
  const_reference front() const;
  reference back();
  const_reference back() const;
  // modifiers:
  void push_front(const T& x);
  void pop_front();
  void push_back(const T& x);
  void pop_back();
  iterator insert(iterator position, const T& x);
  void insert(iterator position, size_type n, const T& x);
  template <class InputIterator>
  void insert(iterator position, InputIterator first,
              InputIterator last);
  iterator erase(iterator position);
  iterator erase(iterator position, iterator last);
  void swap(list<T,Alloc>&);
  void clear();
  // list operations:
  void splice(iterator position, list<T,Alloc>& x);
  void splice(iterator position, list<T,Alloc>& x, iterator i);
  void splice(iterator position, list<T,Alloc>& x,
              iterator first, iterator last);
  void remove(const T& value);
  template <class Predicate>
  void remove_if(Predicate pred);
  void unique();
  template <class BinaryPredicate>
  void unique(BinaryPredicate binary_pred);
  void merge(list<T,Alloc>& x);
  template <class Compare>
  void merge(list<T,Alloc>& x, Compare comp);
  void sort();
  template <class Compare> void sort(Compare comp);
  void reverse();
};

The list class template is one of the standard container types, like deque and vector. A list stores a sequence of items such that inserting or erasing an item at any position requires constant time. The list template supports all the usual operations for a sequence container, plus some functions that are unique to list.

When an item is erased from the list (by calling pop_back, erase, remove, etc.), all iterators that point to that item become invalid. All references to the item become invalid.

Following are the member functions of list:

explicit list (const Alloc& = Alloc())
The constructor initializes an empty list that uses the given allocator.
explicit list (size_type n, const T& value = T(),
const Alloc& = Alloc())
The constructor initializes a list that contains n copies of value.
template < typename InputIterator>
list (InputIterator first, InputIterator last,
const Alloc& = Alloc())
The constructor initializes the list with a copy of the items in the range [first, last).
list (const list<T,Alloc>& x)
The constructor constructs a copy of the contents and allocator of the list x.
list<T,Alloc>& operator= (const list<T,Alloc>& x)
The assignment operator replaces the list's contents with copies of the contents of x.
template < typename InputIterator>
void assign (InputIterator first, InputIterator last)
void assign (size_type n, const T& value)
The assign function replaces the list's contents with the items in the range [first, last) or with n copies of value.
reference back ()
const_reference back () const
The back function returns the last item in the list. The behavior is undefined if the list is empty.
iterator begin ()
const_iterator begin () const
The begin function returns an iterator that points to the first item in the list.
void clear ()
The clear function erases all the items in the list, invalidating all iterators that point to the list.
bool empty () const
The empty function returns size() == 0.
iterator end ()
const_iterator end () const
The end function returns an iterator that points to the one past the last item in the list.
iterator erase (iterator position)
iterator erase (iterator first, iterator last)
The erase function erases the item at position or all the items in the range [first, last).
reference front ()
const_reference front () const
The front function returns the first item in the list. The behavior is undefined if the list is empty.
allocator_type get_allocator () const
The get_allocator function returns the list's allocator.
iterator insert (iterator position, const T& x)
void insert (iterator position, size_type n,
const T& x)
template < typename InputIterator>
void insert (iterator position, InputIterator first,
InputIterator last)
The insert function inserts one or more items before position. The performance is linear in the number of items inserted, and the T copy constructor is invoked once for each item inserted in the list. The first form inserts the item x; the second form inserts n copies of x; the third form copies the items in the range [first, last).
size_type max_size () const
The max_size function returns the size of the largest possible list.
void merge (list<T,Alloc>& x)
template <class Compare>
void merge (list<T,Alloc>& x, Compare comp)
The merge function merges the sorted list x into a sorted list. Items are moved from x so after merge returns, x is empty. Items are compared using the < operator or comp. The merge is stable, so the relative order of items is unchanged; if the same item is already in the list and in x, the item from x is added after the item already in the list.
The performance in linear: exactly size() + x.size() - 1 comparisons are performed.
void pop_back ()
The pop_back function erases the last item from the list. The behavior is undefined if the list is empty.
void pop_front ()
The pop_front function erases the first item from the list. The behavior is undefined if the list is empty.
void push_back (const T& x)
The push_back function inserts x at the end of the list.
void push_front (const T& x)
The push_front function inserts x at the beginning of the list.
reverse_iterator rbegin ()
const_reverse_iterator rbegin () const
The rbegin function returns a reverse iterator that points to the last item in the list.
void remove (const T& value)
The remove function erases all occurrences of value from the list. The performance is linear, exactly size() comparisons are performed.
template < typename Predicate>
void remove_if (Predicate pred)
The remove_if function erases all items for which pred(item) returns true. The performance is linear: pred is called exactly size() times.
reverse_iterator rend ()
const_reverse_iterator rend () const
The rend function returns a reverse iterator that points to one item before the first item in the list.
void resize (size_type sz, T c = T())
The resize function changes the size of this list to n. If n > size(), one or more copies of c are added to the end of the list to reach the desired size. If the new size is smaller than the current size, elements are erased from the end to reach the new size.
void reverse ()
The reverse function reverses the order of the entire list. The performance is linear.
size_type size () const
The size function returns the number of elements in the list.
void sort ()
template <typename Compare>
void sort (Compare comp)
The sort function sorts the items in the list, comparing items with the < operator or by calling comp. The sort is stable, so the relative positions of items does not change. The performance is N log N where N is size().
Note that you must call the sort member function to sort a list. The generic sort algorithm requires a random access iterator, but list provides only a bidirectional iterator.
void splice (iterator position, list<T,Alloc>& x)
void splice (iterator position, list<T,Alloc>& x,
iterator i)
void splice (iterator position, list<T,Alloc>& x,
iterator first, iterator last)
The splice function moves one or more items from x, inserting the items just before position. The first form moves every item from x to the list. The second form moves the item at position i. The third form moves all items in the range [first, last); position must not be in that range. The third form requires linear time when &x != this; all other cases work in constant time.
void swap (list<T,Alloc>& x)
The swap function swaps all the items in this list with all the items in x.
void unique ()
template <typename BinaryPredicate>
void unique (BinaryPredicate binary_pred)
The unique function erases adjacent duplicate items from the list. Items are compared with the == operator or by calling pred. When adjacent equal items are found in the list, the first one is retained and the second and subsequent items are erased. The performance is linear: size() - 1 comparisons are performed (unless the list is empty).

See Also

deque in <deque>, vector in <vector>

operator== function template

Compare lists for equality

template <typename T, typename A>
bool operator==(const list<T,A>& x, const list<T,A>& y);

The == operator returns true if x and y have the same size and their elements are equal, that is, x.size() == y.size() && equals(x.begin(), x.end(), y.begin()).

See Also

equals in <algorithm>

operator!= function template

Compare lists for inequality

template <typename T, typename A>
bool operator!=(const list<T,A>& x, const list<T,A>& y);

The != operator is equivalent to ! (x == y).

operator< function template

Compare lists for less than

template <typename T, typename A>
bool operator<(const list<T,A>& x, const list<T,A>& y);

The < operator determines whether x is less than y, using the same algorithm as lexicographic_compare(x.begin(), x.end(), y.begin(), y.end()).

See Also

lexicographic_compare in <algorithm>

operator<= function template

Compare lists for less than or equality

template <typename T, typename A>
bool operator<=(const list<T,A>& x, const list<T,A>& y);

The <= operator is equivalent to ! (y < x).

operator> function template

Compare lists for greater than

template <typename T, typename A>
bool operator>(const list<T,A>& x, const list<T,A>& y);

The > operator is equivalent to (y < x).

operator>= function template

Compare lists for greater than or equality

template <typename T, typename A>
bool operator>=(const list<T,A>& x, const list<T,A>& y);

The >= operator is equivalent to ! (x < y).

swap function template

Swap the contents of two lists

template<typename T, typename A>
void swap(list<T, A>& x, list<T, A>& y)

The swap function template specialization is equivalent to calling x.swap(y).

See Also

swap in <algorithm>