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 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())
explicit
list
(size_type n, const T& value = T(),
const Alloc& = Alloc())
n
copies of value
.template < typename InputIterator>
list
(InputIterator first, InputIterator last,
const Alloc& = Alloc())
first
, last
).
list
(const list<T,Alloc>& x)
x
.list<T,Alloc>&
operator=
(const list<T,Alloc>& x)
x
.template < typename InputIterator>
void
assign
(InputIterator first, InputIterator last)
void
assign
(size_type n, const T& value)
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
back
function returns the last item in the list. The behavior is undefined if the list is empty.iterator
begin
()
const_iterator
begin
()
const
begin
function returns an iterator that points to the first item in the list.void
clear
()
clear
function erases all the items in the list, invalidating all iterators that point to the list.bool
empty
()
const
empty
function returns size()
==
0
.iterator
end
()
const_iterator
end
()
const
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)
erase
function erases the item at position
or all the items in the range [first
, last
).reference
front
()
const_reference
front
()
const
front
function returns the first item in the list. The behavior is undefined if the list is empty.allocator_type
get_allocator
()
const
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)
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
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)
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.size()
+
x.size() -
1
comparisons are performed.void
pop_back
()
pop_back
function erases the last item from the list. The behavior is undefined if the list is empty.void
pop_front
()
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)
push_back
function inserts x
at the end of the list.void
push_front
(const T& x)
push_front
function inserts x
at the beginning of the list.reverse_iterator
rbegin
()
const_reverse_iterator
rbegin
()
const
rbegin
function returns a reverse iterator that points to the last item in the list.void
remove
(const T& value)
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)
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
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())
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
()
reverse
function reverses the order of the entire list. The performance is linear.size_type
size
()
const
size
function returns the number of elements in the list.void
sort
()
template <typename Compare>
void
sort
(Compare comp)
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().
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)
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)
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)
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).deque in <deque>, vector in <vector>
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())
.
equals in <algorithm>
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)
.
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())
.
lexicographic_compare in <algorithm>
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)
.
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)
.
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 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)
.
swap in <algorithm>