23 Containers library [containers]

23.3 Sequence containers [sequences]

23.3.7 Class template forward_list [forward.list]

23.3.7.1 Overview [forward.list.overview]

1
#
A forward_list is a container that supports forward iterators and allows constant time insert and erase operations anywhere within the sequence, with storage management handled automatically.
Fast random access to list elements is not supported.
[Note 1: 
It is intended that forward_list have zero space or time overhead relative to a hand-written C-style singly linked list.
Features that would conflict with that goal have been omitted.
— end note]
2
#
A forward_list meets all of the requirements of a container ([container.reqmts]), except that the size() member function is not provided and operator== has linear complexity.
A forward_list also meets all of the requirements for an allocator-aware container ([container.alloc.reqmts]).
In addition, a forward_list provides the assign member functions and several of the optional sequence container requirements ([sequence.reqmts]).
Descriptions are provided here only for operations on forward_list that are not described in that table or for operations where there is additional semantic information.
3
#
[Note 2: 
Modifying any list requires access to the element preceding the first element of interest, but in a forward_list there is no constant-time way to access a preceding element.
For this reason, erase_after and splice_after take fully-open ranges, not semi-open ranges.
— end note]
4
#
The types iterator and const_iterator meet the constexpr iterator requirements ([iterator.requirements.general]).
namespace std { template<class T, class Allocator = allocator<T>> class forward_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] // [forward.list.cons], construct/copy/destroy constexpr forward_list() : forward_list(Allocator()) { } constexpr explicit forward_list(const Allocator&); constexpr explicit forward_list(size_type n, const Allocator& = Allocator()); constexpr forward_list(size_type n, const T& value, const Allocator& = Allocator()); template<class InputIterator> constexpr forward_list(InputIterator first, InputIterator last, const Allocator& = Allocator()); template<container-compatible-range<T> R> constexpr forward_list(from_range_t, R&& rg, const Allocator& = Allocator()); constexpr forward_list(const forward_list& x); constexpr forward_list(forward_list&& x); constexpr forward_list(const forward_list& x, const type_identity_t<Allocator>&); constexpr forward_list(forward_list&& x, const type_identity_t<Allocator>&); constexpr forward_list(initializer_list<T>, const Allocator& = Allocator()); constexpr ~forward_list(); constexpr forward_list& operator=(const forward_list& x); constexpr forward_list& operator=(forward_list&& x) noexcept(allocator_traits<Allocator>::is_always_equal::value); constexpr forward_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; // [forward.list.iter], iterators constexpr iterator before_begin() noexcept; constexpr const_iterator before_begin() const noexcept; constexpr iterator begin() noexcept; constexpr const_iterator begin() const noexcept; constexpr iterator end() noexcept; constexpr const_iterator end() const noexcept; constexpr const_iterator cbegin() const noexcept; constexpr const_iterator cbefore_begin() const noexcept; constexpr const_iterator cend() const noexcept; // capacity constexpr bool empty() const noexcept; constexpr size_type max_size() const noexcept; // [forward.list.access], element access constexpr reference front(); constexpr const_reference front() const; // [forward.list.modifiers], modifiers template<class... Args> constexpr reference emplace_front(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(); template<class... Args> constexpr iterator emplace_after(const_iterator position, Args&&... args); constexpr iterator insert_after(const_iterator position, const T& x); constexpr iterator insert_after(const_iterator position, T&& x); constexpr iterator insert_after(const_iterator position, size_type n, const T& x); template<class InputIterator> constexpr iterator insert_after(const_iterator position, InputIterator first, InputIterator last); constexpr iterator insert_after(const_iterator position, initializer_list<T> il); template<container-compatible-range<T> R> constexpr iterator insert_range_after(const_iterator position, R&& rg); constexpr iterator erase_after(const_iterator position); constexpr iterator erase_after(const_iterator position, const_iterator last); constexpr void swap(forward_list&) noexcept(allocator_traits<Allocator>::is_always_equal::value); constexpr void resize(size_type sz); constexpr void resize(size_type sz, const value_type& c); constexpr void clear() noexcept; // [forward.list.ops], forward_list operations constexpr void splice_after(const_iterator position, forward_list& x); constexpr void splice_after(const_iterator position, forward_list&& x); constexpr void splice_after(const_iterator position, forward_list& x, const_iterator i); constexpr void splice_after(const_iterator position, forward_list&& x, const_iterator i); constexpr void splice_after(const_iterator position, forward_list& x, const_iterator first, const_iterator last); constexpr void splice_after(const_iterator position, forward_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); size_type unique(); template<class BinaryPredicate> constexpr size_type unique(BinaryPredicate binary_pred); constexpr void merge(forward_list& x); constexpr void merge(forward_list&& x); template<class Compare> constexpr void merge(forward_list& x, Compare comp); template<class Compare> constexpr void merge(forward_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>>> forward_list(InputIterator, InputIterator, Allocator = Allocator()) -> forward_list<iter-value-type<InputIterator>, Allocator>; template<ranges::input_range R, class Allocator = allocator<ranges::range_value_t<R>>> forward_list(from_range_t, R&&, Allocator = Allocator()) -> forward_list<ranges::range_value_t<R>, Allocator>; }
5
#
An incomplete type T may be used when instantiating forward_list if the allocator meets the allocator completeness requirements.
T shall be complete before any member of the resulting specialization of forward_list is referenced.