# <list>

<head><title>&lt;list&gt;</title></head>

# `<list>`

* * *

Include the [STL](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#STL)
standard header **`<list>`** to define the
[container](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cont.html#Containers)
template class `list` and several supporting
templates.

    namespace std {
    template<class Ty, class Alloc>
        class list;
    
            // TEMPLATE FUNCTIONS
    template<class Ty, class Alloc>
        bool operator==(
            const list<Ty, Alloc>& left,
            const list<Ty, Alloc>& right);
    template<class Ty, class Alloc>
        bool operator!=(
            const list<Ty, Alloc>& left,
            const list<Ty, Alloc>& right);
    template<class Ty, class Alloc>
        bool operator<(
            const list<Ty, Alloc>& left,
            const list<Ty, Alloc>& right);
    template<class Ty, class Alloc>
        bool operator>(
            const list<Ty, Alloc>& left,
            const list<Ty, Alloc>& right);
    template<class Ty, class Alloc>
        bool operator<=(
            const list<Ty, Alloc>& left,
            const list<Ty, Alloc>& right);
    template<class Ty, class Alloc>
        bool operator>=(
            const list<Ty, Alloc>& left,
            const list<Ty, Alloc>& right);
    template<class Ty, class Alloc>
        void swap(
            list<Ty, Alloc>& left,
            list<Ty, Alloc>& right);
    }  // namespace stdCopy to clipboard

## `list`

* * *

**`allocator_type· assign· back· begin· clear· const_iterator· const_pointer· const_reference· const_reverse_iterator· difference_type· empty· end· erase· front· get_allocator· insert· iterator· list· max_size· merge· pointer· pop_back· pop_front· push_back· push_front· rbegin· reference· remove· remove_if· rend· resize· reverse· reverse_iterator· size· size_type· sort· splice· swap· unique· value_type`**

* * *

    template<class Ty, class Alloc = allocator<Ty> >
        class list {
    public:
        typedef Alloc allocator_type;
        typedef typename Alloc::pointer pointer;
        typedef typename Alloc::const_pointer
            const_pointer;
        typedef typename Alloc::reference reference;
        typedef typename Alloc::const_reference const_reference;
        typedef typename Alloc::value_type value_type;
    
        typedef T0 iterator;
        typedef T1 const_iterator;
        typedef T2 size_type;
        typedef T3 difference_type;
        typedef reverse_iterator<const_iterator>
            const_reverse_iterator;
        typedef reverse_iterator<iterator>
            reverse_iterator;
    
        list();
        explicit list(const Alloc& al);
        explicit list(size_type count);
        list(size_type count, const Ty& val);
        list(size_type count, const Ty& val, const Alloc& al);
        list(const list& right);
        template<class InIt>
            list(InIt first, InIt last);
        template<class InIt>
            list(InIt first, InIt last, const Alloc& al);
    
        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;
    
        void resize(size_type newsize);
        void resize(size_type newsize, Ty val);
        size_type size() const;
        size_type max_size() const;
        bool empty() const;
    
        Alloc get_allocator() const;
    
        reference front();
        const_reference front() const;
        reference back();
        const_reference back() const;
        void push_front(const Ty& val);
        void pop_front();
        void push_back(const Ty& val);
        void pop_back();
    
        template<class InIt>
            void assign(InIt first, InIt last);
        void assign(size_type count, const Ty& val);
    
        iterator insert(iterator where, const Ty& val);
        void insert(iterator where, size_type count, const Ty& val);
        template<class InIt>
            void insert(iterator where, InIt first, InIt last);
    
        iterator erase(iterator where);
        iterator erase(iterator first, iterator last);
        void clear();
    
        void swap(list& right);
    
        void splice(iterator where, list& right);
        void splice(iterator where, list& right, iterator first);
        void splice(iterator where, list& right, iterator first,
            iterator last);
    
        void remove(const Ty& val);
        templace<class Pr1>
            void remove_if(Pr1 pred);
        void unique();
        template<class Pr2>
            void unique(Pr2 pred);
    
        void merge(list& right);
        template<class Pr3>
            void merge(list& right, Pr3 pred);
        void sort();
        template<class Pr3>
            void sort(Pr3 pred);
        void reverse();
        };Copy to clipboard

The template class describes an object that controls a
varying-length sequence of elements of type `Ty`.
The sequence is stored as a bidirectional linked list of elements,
each containing a member of type `Ty`.

The object allocates and frees storage for the sequence it controls
through a stored [allocator object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator%20object)
of class `Alloc`. Such an allocator object must have
the same external interface as an object of template class
[`allocator`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator).
Note that the stored allocator object is *not* copied when the container
object is assigned.

**List reallocation**
occurs when a member function must insert, erase, or splice elements of
the controlled sequence. In all such cases, only iterators
or references that designate erased or spliced elemets
of the controlled sequence become
**invalid**.

All additions to the controlled sequence occur as if by calls to
`insert`, which is the
only member function that calls the constructor
`Ty(const Ty&)`. If such an expression throws
an exception, the container object inserts no new elements and rethrows
the exception. Thus, an object of template class `list`
is left in a known state when such exceptions occur.

### `list::allocator_type`

    typedef Alloc allocator_type;Copy to clipboard

The type is a synonym for the template parameter `Alloc`.

### `list::assign`

    template<class InIt>
        void assign(InIt first, InIt last);
    void assign(size_type count, const Ty& val);Copy to clipboard

If `InIt` is an integer type, the first member
function behaves the same as `assign((size_type)first, (Ty)last)`.
Otherwise, the
first member function replaces the sequence
controlled by `*this` with the sequence
`[first, last)`, which must *not* overlap
the initial controlled sequence.
The second member function replaces the sequence
controlled by `*this` with a repetition of `count`
elements of value `val`.

### `list::back`

    reference back();
    const_reference back() const;Copy to clipboard

The member function returns a reference to the last element of the
controlled sequence, which must be non-empty.

### `list::begin`

    const_iterator begin() const;
    iterator begin();Copy to clipboard

The member function returns a bidirectional iterator that points at
the first element of the sequence (or just beyond the end of an empty
sequence).

### `list::clear`

    void clear();Copy to clipboard

The member function calls
`erase(
begin(),
end())`.

### `list::const_iterator`

    typedef T1 const_iterator;Copy to clipboard

The type describes an object that can serve as a constant
bidirectional iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type `T1`.

### `list::const_pointer`

    typedef typename Alloc::const_pointer
        const_pointer;Copy to clipboard

The type describes an object that can serve as a constant pointer
to an element of the controlled sequence.

### `list::const_reference`

    typedef typename Alloc::const_reference const_reference;Copy to clipboard

The type describes an object that can serve as a constant reference
to an element of the controlled sequence.

### `list::const_reverse_iterator`

    typedef reverse_iterator<const_iterator>
        const_reverse_iterator;Copy to clipboard

The type describes an object that can serve as a constant reverse
bidirectional iterator for the controlled sequence.

### `list::difference_type`

    typedef T3 difference_type;Copy to clipboard

The signed integer type describes an object that can represent the
difference between the addresses of any two elements in the controlled
sequence. It is described here as a
synonym for the implementation-defined type `T3`.

### `list::empty`

    bool empty() const;Copy to clipboard

The member function returns true for an empty controlled sequence.

### `list::end`

    const_iterator end() const;
    iterator end();Copy to clipboard

The member function returns a bidirectional iterator that points
just beyond the end of the sequence.

### `list::erase`

    iterator erase(iterator where);
    iterator erase(iterator first, iterator last);Copy to clipboard

The first member function removes the element of the controlled
sequence pointed to by `where`. The second member function
removes the elements of the controlled sequence
in the range `[first, last)`.
Both return an iterator that designates the first element remaining
beyond any elements removed, or
`end()` if no such element exists.

Erasing `N` elements causes
`N` destructor calls.
[Reallocation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_list.html#list%20reallocation) occurs,
so iterators and references become
[invalid](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_list.html#invalid%20list%20iterators) for the erased
elements.

The member functions never throw an exception.

### `list::front`

    reference front();
    const_reference front() const;Copy to clipboard

The member function returns a reference to the first element of the
controlled sequence, which must be non-empty.

### `list::get_allocator`

    Alloc get_allocator() const;Copy to clipboard

The member function returns the stored
[allocator object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator%20object).

### `list::insert`

    iterator insert(iterator where, const Ty& val);
    void insert(iterator where, size_type count, const Ty& val);
    template<class InIt>
        void insert(iterator where, InIt first, InIt last);Copy to clipboard

Each of the member functions inserts, before the element pointed to
by `where` in the controlled sequence, a sequence
specified by the remaining operands.
The first member function inserts
a single element with value `val` and returns an iterator
that designates the newly inserted element. The second member function
inserts a repetition of `count` elements of value `val`.

If `InIt` is an integer type, the last member
function behaves the same as `insert(where, (size_type)first, (Ty)last)`.
Otherwise, the last member function inserts the sequence
`[first, last)`, which must *not* overlap
the initial controlled sequence.

Inserting `N` elements causes `N`
constructor calls.
[Reallocation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_list.html#list%20reallocation) occurs,
but no iterators or references become
[invalid](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_list.html#invalid%20list%20iterators).

If an exception is thrown during the
insertion of one or more elements, the container is left unaltered
and the exception is rethrown.

### `list::iterator`

    typedef T0 iterator;Copy to clipboard

The type describes an object that can serve as a bidirectional
iterator for the controlled sequence.
It is described here as a
synonym for the implementation-defined type `T0`.

### `list::list`

    list();
    explicit list(const Alloc& al);
    explicit list(size_type count);
    list(size_type count, const Ty& val);
    list(size_type count, const Ty& val,
        const Alloc& al);
    list(const list& right);
    template<class InIt>
        list(InIt first, InIt last);
    template<class InIt>
        list(InIt first, InIt last, const Alloc& al);Copy to clipboard

All constructors store an
[allocator object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator%20object) and
initialize the controlled sequence. The allocator object is the argument
`al`, if present. For the copy constructor, it is
`right.get_allocator()`.
Otherwise, it is `Alloc()`.

The first two constructors specify an
empty initial controlled sequence. The third constructor specifies
a repetition of `count` elements of value `Ty()`.
The fourth and fifth constructors specify
a repetition of `count` elements of value `val`.
The sixth constructor specifies a copy of the sequence controlled by
`right`.
If `InIt` is an integer type, the last two constructors
specify a repetition of `(size_type)first` elements of value
`(Ty)last`. Otherwise, the
last two constructors specify the sequence
`[first, last)`.

### `list::max_size`

    size_type max_size() const;Copy to clipboard

The member function returns the length of the longest sequence that
the object can control.

### `list::merge`

    void merge(list& right);
    template<class Pr3>
        void merge(list& right, Pre3 pred);Copy to clipboard

Both member functions remove all elements from the sequence
controlled by `right` and insert them in the controlled
sequence. Both sequences must be
[ordered by](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_stl.html#sequence%20ordering) the same predicate,
described below. The resulting sequence is also ordered by that
predicate.

For the iterators `Pi` and `Pj`
designating elements at positions `I`
and `J`, the first member function imposes the
order `!(*Pj < *Pi)` whenever `I < J`.
(The elements are sorted in *ascending* order.)
The second member function imposes the order
`!pred(*Pj, *Pi)` whenever `I < J`.

No pairs of elements in the original controlled sequence
are reversed in the resulting controlled sequence. If a pair
of elements in the resulting controlled sequence has
[equivalent ordering](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_stl.html#equivalent%20ordering)
(`!(*Pi < *Pj) && !(*Pj < *Pi)`),
an element from the original controlled sequence appears before
an element from the sequence controlled by `right`.

An exception occurs only if `pred` throws an exception.
In that case, the controlled sequence is left in unspecified order
and the exception is rethrown.

### `list::pointer`

    typedef typename Alloc::pointer pointer;Copy to clipboard

The type describes an object that can serve as a pointer to an
element of the controlled sequence.

### `list::pop_back`

    void pop_back();Copy to clipboard

The member function removes the last element of the
controlled sequence, which must be non-empty.

The member function never throws an exception.

### `list::pop_front`

    void pop_front();Copy to clipboard

The member function removes the first element of the
controlled sequence, which must be non-empty.

The member function never throws an exception.

### `list::push_back`

    void push_back(const Ty& val);Copy to clipboard

The member function inserts an element with value `val`
at the end of the controlled sequence.

If an exception is thrown, the container is left unaltered
and the exception is rethrown.

### `list::push_front`

    void push_front(const Ty& val);Copy to clipboard

The member function inserts an element with value `val`
at the beginning of the controlled sequence.

If an exception is thrown, the container is left unaltered
and the exception is rethrown.

### `list::rbegin`

    const_reverse_iterator rbegin() const;
    reverse_iterator rbegin();Copy to clipboard

The member function returns a reverse bidirectional
iterator that points just
beyond the end of the controlled sequence. Hence, it designates the
beginning of the reverse sequence.

### `list::reference`

    typedef typename Alloc::reference reference;Copy to clipboard

The type describes an object that can serve as a reference to an
element of the controlled sequence.

### `list::remove`

    void remove(const Ty& val);Copy to clipboard

The member function removes from the controlled sequence
all elements, designated by the iterator `where`, for which
`*where == val`.

The member function never throws an exception.

### `list::remove_if`

    templace<class Pr1>
        void remove_if(Pr1 pred);Copy to clipboard

The member function removes from the controlled sequence
all elements, designated by the iterator `where`, for which
`pred(*where)` is true.

An exception occurs only if `pred` throws an exception.
In that case, the controlled sequence is left in an unspecified state
and the exception is rethrown.

### `list::rend`

    const_reverse_iterator rend() const;
    reverse_iterator rend();Copy to clipboard

The member function returns a reverse bidirectional
iterator that points at the
first element of the sequence (or just beyond the end of an empty
sequence). Hence, it designates the end of the reverse sequence.

### `list::resize`

    void resize(size_type newsize);
    void resize(size_type newsize, Ty val);Copy to clipboard

The member functions both ensure that
`size()` henceforth
returns `newsize`. If it must make the controlled sequence longer,
the first member function
appends elements with value `Ty()`, while the second member function
appends elements with value `val`.
To make the controlled sequence shorter, both member functions call
`erase(begin() + newsize, end())`.

### `list::reverse`

    void reverse();Copy to clipboard

The member function reverses the order in which elements appear
in the controlled sequence.

### `list::reverse_iterator`

    typedef reverse_iterator<iterator>
        reverse_iterator;Copy to clipboard

The type describes an object that can serve as a reverse
bidirectional iterator for the controlled sequence.

### `list::size`

    size_type size() const;Copy to clipboard

The member function returns the length of the controlled sequence.

### `list::size_type`

    typedef T2 size_type;Copy to clipboard

The unsigned integer type describes an object that can represent the
length of any controlled sequence. It is described here as a
synonym for the implementation-defined type `T2`.

### `list::sort`

    void sort();
    template<class Pr3>
        void sort(Pr3 pred);Copy to clipboard

Both member functions order the elements in the controlled
sequence by a predicate, described below.

For the iterators `Pi` and `Pj`
designating elements at positions `I`
and `J`, the first member function imposes the
order `!(*Pj < *Pi)` whenever `I < J`.
(The elements are sorted in *ascending* order.)
The member template function imposes the order
`!pred(*Pj, *Pi)` whenever `I < J`.
No ordered pairs of elements in the original controlled sequence
are reversed in the resulting controlled sequence.
(The sort is stable.)

An exception occurs only if `pred` throws an exception.
In that case, the controlled sequence is left in unspecified order
and the exception is rethrown.

### `list::splice`

    void splice(iterator where, list& right);
    void splice(iterator where, list& right, iterator first);
    void splice(iterator where, list& right, iterator first,
        iterator last);Copy to clipboard

The first member function inserts the sequence controlled
by `right` before the element in the controlled sequence
pointed to by `where`. It also removes all elements from
`right`. (`&right` must not equal `this`.)

The second member function removes the element pointed to by
`first` in the sequence controlled by `right` and
inserts it before the element in the controlled sequence
pointed to by `where`. (If `where == first || where == ++first`,
no change occurs.)

The third member function inserts the subrange
designated by `[first, last)` from the sequence
controlled by `right`
before the element in the controlled sequence pointed to by `where`.
It also removes the original subrange from the sequence controlled
by `right`. (If `&right == this`,
the range `[first, last)` must not include the element
pointed to by `where`.)

If the third member function inserts
`N` elements, and `&right != this`, an object of class
`iterator` is
incremented `N` times.
For all `splice` member functions, If
`get_allocator()
== str.get_allocator()`, no exception occurs.
Otherwise, a copy and a destructor call also
occur for each inserted element.

Only iterators or references that designate spliced elements become
**[invalid](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_list.html#invalid%20list%20iterators)**.

### `list::swap`

    void swap(list& right);Copy to clipboard

The member function swaps the controlled sequences between
`*this` and `where`. If
`get_allocator()
== where.get_allocator()`, it does so in constant time,
it throws no exceptions, and it invalidates no references, pointers,
or iterators that designate elements in the two controlled sequences.
Otherwise, it performs a number of element assignments and constructor calls
proportional to the number of elements in the two controlled sequences.

### `list::unique`

    void unique();
    template<class Pr2>
        void unique(Pr2 pred);Copy to clipboard

The first member function removes from the controlled sequence
every element that compares equal to its preceding element.
For the iterators `Pi` and `Pj`
designating elements at positions `I`
and `J`, the second member function removes every
element for which `I + 1 == J && pred(*Pi, *Pj)`.

For a controlled sequence of length `N`
(&gt; 0), the predicate `pred(*Pi, *Pj)`
is evaluated `N - 1` times.

An exception occurs only if `pred` throws an exception.
In that case, the controlled sequence is left in an unspecified state
and the exception is rethrown.

### `list::value_type`

    typedef typename Alloc::value_type value_type;Copy to clipboard

The type is a synonym for the template parameter `Ty`.

## `operator!=`

    template<class Ty, class Alloc>
        bool operator!=(
            const list <Ty, Alloc>& left,
            const list <Ty, Alloc>& right);Copy to clipboard

The template function returns `!(left == right)`.

## `operator==`

    template<class Ty, class Alloc>
        bool operator==(
            const list <Ty, Alloc>& left,
            const list <Ty, Alloc>& right);Copy to clipboard

The template function overloads `operator==` to compare
two objects of template class
[`list`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_list.html#list). The function returns
`left.size() == right.size() &&
equal(left.
begin(), left.
end(), right.begin())`.

## `operator<`

    template<class Ty, class Alloc>
        bool operator<(
            const list <Ty, Alloc>& left,
            const list <Ty, Alloc>& right);Copy to clipboard

The template function overloads `operator<` to compare
two objects of template class
[`list`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_list.html#list). The function returns
`lexicographical_compare(left.
begin(), left.
end(), right.begin(), right.end())`.

## `operator<=`

    template<class Ty, class Alloc>
        bool operator<=(
            const list <Ty, Alloc>& left,
            const list <Ty, Alloc>& right);Copy to clipboard

The template function returns `!(right < left)`.

## `operator>`

    template<class Ty, class Alloc>
        bool operator>(
            const list <Ty, Alloc>& left,
            const list <Ty, Alloc>& right);Copy to clipboard

The template function returns `right < left`.

## `operator>=`

    template<class Ty, class Alloc>
        bool operator>=(
            const list <Ty, Alloc>& left,
            const list <Ty, Alloc>& right);Copy to clipboard

The template function returns `!(left < right)`.

## `swap`

    template<class Ty, class Alloc>
        void swap(
            list <Ty, Alloc>& left,
            list <Ty, Alloc>& right);Copy to clipboard

The template function executes
`left.swap(right)`.

* * *

See also the
**[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the
**[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**.

*[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. Portions derived from work[copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_hp.html) © 1994by Hewlett-Packard Company. All rights reserved.*

<!--V5.01:1566-->

Last Published: Oct 06, 2026

Previous Topic
 
<limits></limits> Next Topic

<locale.h></locale.h>