caution

Note, this article is not finished! You can help by editing this doc page.

Overview

Simplified (since C++11)

template< class T, /* .. */ >
class forward_list;

Detailed

Regular (since C++11)

template<
    class T,
    class Allocator = std::allocator<T>
> class forward_list;

Polymorphic (since C++17)

namespace pmr {
    template< class T >
    using forward_list = std::forward_list<T, std::pmr::polymorphic_allocator<T>>;
}

Forward list is a container that supports fast insertion and removal of elements from anywhere in the container.

Technical definition of a forward list

std::forward_list is a container that supports fast insertion and removal of elements from anywhere in the container.

important

Fast random access is not supported.

It is implemented as a singly-linked list. Compared to std::list this container provides more space efficient storage when bidirectional iteration is not needed.

Adding, removing and moving the elements within the list, or across several lists, does not invalidate the iterators currently referring to other elements in the list. However, an iterator or reference referring to an element is invalidated when the corresponding element is removed (via erase_after) from the list.

std::forward_list meets the requirements of Container (except for the size member function and that operator=='s complexity is always linear), AllocatorAwareContainer and SequenceContainer.

std::forward_list

Defined in

forward_list

Template parameters

See technical details for more detailed information.

pub	T	Type of the elements.
pub	Allocator	Allocator that is used to acquire/release memory and to construct/destroy the elements in that memory.

Type names

pub	value_type	T
pub	allocator_type	Allocator
pub	size_type	Unsigned integer type (usually std::size_t)
pub	difference_type	Signed integer type (usually std::ptrdiff_t)
pub	reference	value_type&
pub	const_reference	value_type const&
pub	pointer	Allocator::pointer (until C++11) std::allocator_traits<Allocator>::pointer (since C++11)
pub	const_pointer	Allocator::const_pointer (until C++11) std::allocator_traits<Allocator>::const_pointer (since C++11)
pub	iterator	LegacyForwardIterator to value_type
pub	const_iterator	LegacyForwardIterator to const value_type

Member functions

pub	(constructors)	Constructs a vector.
pub	(destructor)	Destroys the vector, deallocating internal storage if used.
pub	operator=	Assigns values to the container.
pub	assign	Assigns values to the container.
pub	get_allocator	Returns the associated allocator.

Element access

pub

front

Access the first element.

Iterators

pub	before_begin cbefore_begin	Returns an iterator/const_iterator to the element before the beginning.
pub	begin cbegin	Returns an iterator/const_iterator to the beginning.
pub	end cend	Returns an iterator/const_iterator to the end.

Capacity

pub	empty	Returns true if the list is empty, otherwise false.
pub	max_size	Returns the maximum possible number of elements.

Modifiers

pub	clear	Clears the contents.
pub	insert_after	Inserts elements after the elements.
pub	emplace_after	Constructs elements in-place after an element.
pub	erase_after	Erases an element after an element.
pub	push_front	Inserts an element to the beginning.
pub	emplace_front	Constructs an element in-place at the beginning.
pub	pop_front	Removes the first element.
pub	resize	Changes the number of elements stored.
pub	swap	Swaps the contents.

Operations

pub	merge	Merges two sorted lists.
pub	splice_after	Moves elements from another forward list.
pub	remove remove_if	Removes elements satisfying specific criteria.
pub	reverse	Reverses the order of the elements.
pub	unique	Removes consecutive duplicate elements.
pub	sort	Sorts the elements.

Non-member functions

pub	operator== operator!= (removed in C++20) operator< (removed in C++20) operator> (removed in C++20) operator<= (removed in C++20) operator>= (removed in C++20) operator<=> (since C++20)	Lexicographically compares the values in the list.
pub	std::swap (std::forward_list)	An overload for a std::swap algorithm.
pub	erase (std::forward_list) erase_if (std::forward_list)	Overloads for std::erase/std::erase_if algorithms.

Deduction guides (since C++17)

Click to expand

Deduction guides

// (1)
template< class InputIt,
          class Alloc = std::allocator<typename std::iterator_traits<InputIt>::value_type>>
forward_list(InputIt, InputIt, Alloc = Alloc())
  -> forward_list<typename std::iterator_traits<InputIt>::value_type, Alloc>;

(1) allows deduction from an iterator range.

Overload resolution

In order for any of the deduction guides to participate in overload resolution, the folllowing requirements must be met:

• InputIt satisfies the requirements of LegacyInputIterator
• Alloc satisfies the requirements of Allocator

note

The extent to which the library determines that a type does not satisfy LegacyInputIterator is unspecified, except that as a minimum:

• Integral types do not qualify as input iterators.

Likewise, the extent to which it determines that a type does not satisfy Allocator is unspecified, except that as a minimum:

• The member type Alloc::value_type must exist.
• The expression std::declval<Alloc&>().allocate(std::size_t{}) must be well-formed when treated as an unevaluated operand.

Examples

important

This section requires improvement. You can help by editing this doc page.