23 Containers library [containers]

23.3 Sequence containers [sequences]

23.3.11 Class template list [list]

23.3.11.1 Overview [list.overview]

1
#
A list is a sequence container that supports bidirectional iterators and allows constant time insert and erase operations anywhere within the sequence, with storage management handled automatically.
Unlike vectors and deques, fast random access to list elements is not supported, but many algorithms only need sequential access anyway.
2
#
A list meets all of the requirements of a container ([container.reqmts]), of a reversible container ([container.rev.reqmts]), of an allocator-aware container ([container.alloc.reqmts]), and of a sequence container, including most of the optional sequence container requirements ([sequence.reqmts]).
The exceptions are the operator[] and at member functions, which are not provided.196
Descriptions are provided here only for operations on list that are not described in one of these tables or for operations where there is additional semantic information.
3
#
The types iterator and const_iterator meet the constexpr iterator requirements[iterator.requirements.general].
namespace std { template<class T, class Allocator = allocator<T>> class list { public: // types using value_type = T; using allocator_type = Allocator; using pointer = typename allocator_traits<Allocator>::pointer; using const_pointer = typename allocator_traits<Allocator>::const_pointer; using reference = value_type&; using const_reference = const value_type&; using size_type = implementation-defined; // see [container.requirements] using difference_type = implementation-defined; // see [container.requirements] using iterator = implementation-defined; // see [container.requirements] using const_iterator = implementation-defined; // see [container.requirements] using reverse_iterator = std::reverse_iterator<iterator>; using const_reverse_iterator = std::reverse_iterator<const_iterator>; // [list.cons], construct/copy/destroy constexpr list() : list(Allocator()) { } constexpr explicit list(const Allocator&); constexpr explicit list(size_type n, const Allocator& = Allocator()); constexpr list(size_type n, const T& value, const Allocator& = Allocator()); template<class InputIterator> constexpr list(InputIterator first, InputIterator last, const Allocator& = Allocator()); template<container-compatible-range<T> R> constexpr list(from_range_t, R&& rg, const Allocator& = Allocator()); constexpr list(const list& x); constexpr list(list&& x); constexpr list(const list&, const type_identity_t<Allocator>&); constexpr list(list&&, const type_identity_t<Allocator>&); constexpr list(initializer_list<T>, const Allocator& = Allocator()); constexpr ~list(); constexpr list& operator=(const list& x); constexpr list& operator=(list&& x) noexcept(allocator_traits<Allocator>::is_always_equal::value); constexpr list& operator=(initializer_list<T>); template<class InputIterator> constexpr void assign(InputIterator first, InputIterator last); template<container-compatible-range<T> R> constexpr void assign_range(R&& rg); constexpr void assign(size_type n, const T& t); constexpr void assign(initializer_list<T>); constexpr allocator_type get_allocator() const noexcept; // iterators constexpr iterator begin() noexcept; constexpr const_iterator begin() const noexcept; constexpr iterator end() noexcept; constexpr const_iterator end() const noexcept; constexpr reverse_iterator rbegin() noexcept; constexpr const_reverse_iterator rbegin() const noexcept; constexpr reverse_iterator rend() noexcept; constexpr const_reverse_iterator rend() const noexcept; constexpr const_iterator cbegin() const noexcept; constexpr const_iterator cend() const noexcept; constexpr const_reverse_iterator crbegin() const noexcept; constexpr const_reverse_iterator crend() const noexcept; // [list.capacity], capacity constexpr bool empty() const noexcept; constexpr size_type size() const noexcept; constexpr size_type max_size() const noexcept; constexpr void resize(size_type sz); constexpr void resize(size_type sz, const T& c); // element access constexpr reference front(); constexpr const_reference front() const; constexpr reference back(); constexpr const_reference back() const; // [list.modifiers], modifiers template<class... Args> constexpr reference emplace_front(Args&&... args); template<class... Args> constexpr reference emplace_back(Args&&... args); constexpr void push_front(const T& x); constexpr void push_front(T&& x); template<container-compatible-range<T> R> constexpr void prepend_range(R&& rg); constexpr void pop_front(); constexpr void push_back(const T& x); constexpr void push_back(T&& x); template<container-compatible-range<T> R> constexpr void append_range(R&& rg); constexpr void pop_back(); template<class... Args> constexpr iterator emplace(const_iterator position, Args&&... args); constexpr iterator insert(const_iterator position, const T& x); constexpr iterator insert(const_iterator position, T&& x); constexpr iterator insert(const_iterator position, size_type n, const T& x); template<class InputIterator> constexpr iterator insert(const_iterator position, InputIterator first, InputIterator last); template<container-compatible-range<T> R> constexpr iterator insert_range(const_iterator position, R&& rg); constexpr iterator insert(const_iterator position, initializer_list<T> il); constexpr iterator erase(const_iterator position); constexpr iterator erase(const_iterator position, const_iterator last); constexpr void swap(list&) noexcept(allocator_traits<Allocator>::is_always_equal::value); constexpr void clear() noexcept; // [list.ops], list operations constexpr void splice(const_iterator position, list& x); constexpr void splice(const_iterator position, list&& x); constexpr void splice(const_iterator position, list& x, const_iterator i); constexpr void splice(const_iterator position, list&& x, const_iterator i); constexpr void splice(const_iterator position, list& x, const_iterator first, const_iterator last); constexpr void splice(const_iterator position, list&& x, const_iterator first, const_iterator last); constexpr size_type remove(const T& value); template<class Predicate> constexpr size_type remove_if(Predicate pred); constexpr size_type unique(); template<class BinaryPredicate> constexpr size_type unique(BinaryPredicate binary_pred); constexpr void merge(list& x); constexpr void merge(list&& x); template<class Compare> constexpr void merge(list& x, Compare comp); template<class Compare> constexpr void merge(list&& x, Compare comp); constexpr void sort(); template<class Compare> constexpr void sort(Compare comp); constexpr void reverse() noexcept; }; template<class InputIterator, class Allocator = allocator<iter-value-type<InputIterator>>> list(InputIterator, InputIterator, Allocator = Allocator()) -> list<iter-value-type<InputIterator>, Allocator>; template<ranges::input_range R, class Allocator = allocator<ranges::range_value_t<R>>> list(from_range_t, R&&, Allocator = Allocator()) -> list<ranges::range_value_t<R>, Allocator>; }
4
#
An incomplete type T may be used when instantiating list if the allocator meets the allocator completeness requirements.
T shall be complete before any member of the resulting specialization of list is referenced.
196)196)
These member functions are only provided by containers whose iterators are random access iterators.