Skip to main content
Pigweed's logo Pigweed
  1. Home
  2. Reference
  3. C/C++
  4. pw_containers
  5. Lists
  6. pw::ForwardList< T > Class Template Reference
Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | Friends | List of all members
pw::ForwardList< T > Class Template Reference
pw_containers » Lists

Overview

template<typename T>
class pw::ForwardList< T >

A singly-linked list that owns its elements and allocates them using a pw::Allocator. It provides an interface similar to std::forward_list.

ForwardList is an owning wrapper around IntrusiveForwardList that manages the lifetime and dynamic memory allocation of its elements. It provides both asserting operations (such as push_front and resize) and fallible try_* operations (such as try_push_front and try_resize) for allocation-failure handling without exceptions.

Warning
The container's allocator MUST outlive the container.
Template Parameters
TThe type of elements in the list.

Public Types

using value_type = T
 
using allocator_type = Allocator
 
using size_type = std::size_t
 
using difference_type = std::ptrdiff_t
 
using reference = value_type &
 
using const_reference = const value_type &
 
using pointer = value_type *
 
using const_pointer = const value_type *
 
using iterator = Iterator< false >
 
using const_iterator = Iterator< true >
 

Public Member Functions

constexpr ForwardList (Allocator &allocator) noexcept
 
 ~ForwardList ()
 Destroys the ForwardList and deallocates all stored elements.
 
 ForwardList (const ForwardList &)=delete
 
ForwardList & operator= (const ForwardList &)=delete
 
 ForwardList (ForwardList &&other) noexcept
 Moves the elements and allocator from other into this list.
 
ForwardList & operator= (ForwardList &&other) noexcept
 Move-assigns other into this list, clearing existing elements first.
 
iterator before_begin () noexcept
 Returns an iterator to the element before the first element of the list.
 
const_iterator before_begin () const noexcept
 
const_iterator cbefore_begin () const noexcept
 
iterator begin () noexcept
 Returns an iterator to the first element in the list.
 
const_iterator begin () const noexcept
 Returns a const iterator to the first element in the list.
 
const_iterator cbegin () const noexcept
 Returns a const iterator to the first element in the list.
 
iterator end () noexcept
 Returns an iterator to the end of the list.
 
const_iterator end () const noexcept
 Returns a const iterator to the end of the list.
 
const_iterator cend () const noexcept
 Returns a const iterator to the end of the list.
 
allocator_type & get_allocator () const noexcept
 Returns a reference to the allocator associated with this container.
 
bool empty () const noexcept
 Checks whether the container is empty.
 
constexpr size_type max_size () const noexcept
 Returns the maximum possible number of elements the list can hold.
 
reference front () noexcept
 Returns a reference to the first element.
 
const_reference front () const noexcept
 Returns a const reference to the first element.
 
template<typename... Args>
reference emplace_front (Args &&... args)
 
template<typename... Args>
bool try_emplace_front (Args &&... args)
 
void push_front (const T &value)
 
void push_front (T &&value)
 
bool try_push_front (const T &value)
 
bool try_push_front (T &&value)
 
void pop_front () noexcept
 
void clear () noexcept
 Erases all elements from the container and frees their allocated nodes.
 
void swap (ForwardList &other) noexcept
 
template<typename... Args>
iterator emplace_after (const_iterator pos, Args &&... args)
 
template<typename... Args>
bool try_emplace_after (const_iterator pos, Args &&... args)
 
iterator insert_after (const_iterator pos, const T &value)
 
iterator insert_after (const_iterator pos, T &&value)
 
bool try_insert_after (const_iterator pos, const T &value)
 Attempts to insert a copy of value after pos.
 
bool try_insert_after (const_iterator pos, T &&value)
 Attempts to insert value after pos via move.
 
iterator insert_after (const_iterator pos, size_type count, const T &value)
 
bool try_insert_after (const_iterator pos, size_type count, const T &value)
 
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
iterator insert_after (const_iterator pos, InputIt first, InputIt last)
 
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
bool try_insert_after (const_iterator pos, InputIt first, InputIt last)
 
iterator insert_after (const_iterator pos, std::initializer_list< T > ilist)
 
bool try_insert_after (const_iterator pos, std::initializer_list< T > ilist)
 Attempts to insert elements from ilist after pos.
 
void assign (size_type count, const T &value)
 
bool try_assign (size_type count, const T &value)
 
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
void assign (InputIt first, InputIt last)
 
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
bool try_assign (InputIt first, InputIt last)
 
void assign (std::initializer_list< T > ilist)
 
bool try_assign (std::initializer_list< T > ilist)
 
iterator erase_after (const_iterator pos)
 
iterator erase_after (const_iterator first, const_iterator last)
 
void resize (size_type count)
 
void resize (size_type count, const T &value)
 
bool try_resize (size_type count)
 
bool try_resize (size_type count, const T &value)
 
void splice_after (const_iterator pos, ForwardList &other) noexcept
 Moves all elements from other into this list after pos.
 
void splice_after (const_iterator pos, ForwardList &&other) noexcept
 Moves all elements from other into this list after pos.
 
void splice_after (const_iterator pos, ForwardList &other, const_iterator it) noexcept
 Moves the element pointed to after it from other to after pos.
 
void splice_after (const_iterator pos, ForwardList &&other, const_iterator it) noexcept
 Moves the element pointed to after it from other to after pos.
 
void splice_after (const_iterator pos, ForwardList &other, const_iterator first, const_iterator last) noexcept
 
void splice_after (const_iterator pos, ForwardList &&other, const_iterator first, const_iterator last) noexcept
 
size_type remove (const T &value)
 
template<typename UnaryPredicate >
size_type remove_if (UnaryPredicate pred)
 
size_type unique ()
 
template<typename BinaryPredicate >
size_type unique (BinaryPredicate binary_pred)
 
void merge (ForwardList &other)
 Merges two sorted lists into one using operator<.
 
void merge (ForwardList &&other)
 Merges two sorted lists into one using operator<.
 
template<typename Compare >
void merge (ForwardList &other, Compare comp)
 Merges two sorted lists into one using the comparator comp.
 
template<typename Compare >
void merge (ForwardList &&other, Compare comp)
 Merges two sorted lists into one using the comparator comp.
 
void sort ()
 Sorts the elements in non-descending order using operator<.
 
template<typename Compare >
void sort (Compare comp)
 Sorts the elements in non-descending order using the comparator comp.
 
void reverse () noexcept
 Reverses the order of the elements in the list.
 

Friends

void swap (ForwardList &lhs, ForwardList &rhs) noexcept
 

Constructor & Destructor Documentation

◆ ForwardList()

template<typename T >
constexpr pw::ForwardList< T >::ForwardList ( Allocator &  allocator)
inlineexplicitconstexprnoexcept

Constructs an empty ForwardList backed by the provided allocator.

Parameters
[in]allocatorThe allocator to use for node allocations.

Member Function Documentation

◆ assign() [1/3]

template<typename T >
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
void pw::ForwardList< T >::assign ( InputIt  first,
InputIt  last 
)
inline

Replaces the contents with elements from [first, last). Crashes if allocation fails.

◆ assign() [2/3]

template<typename T >
void pw::ForwardList< T >::assign ( size_type  count,
const T &  value 
)
inline

Replaces the contents with count copies of value. Crashes if allocation fails.

◆ assign() [3/3]

template<typename T >
void pw::ForwardList< T >::assign ( std::initializer_list< T >  ilist)
inline

Replaces the contents with elements from ilist. Crashes if allocation fails.

◆ before_begin()

template<typename T >
const_iterator pw::ForwardList< T >::before_begin ( ) const
inlinenoexcept

Returns a const iterator to the element before the first element of the list.

◆ cbefore_begin()

template<typename T >
const_iterator pw::ForwardList< T >::cbefore_begin ( ) const
inlinenoexcept

Returns a const iterator to the element before the first element of the list.

◆ emplace_after()

template<typename T >
template<typename... Args>
iterator pw::ForwardList< T >::emplace_after ( const_iterator  pos,
Args &&...  args 
)
inline

Constructs an element in-place directly after pos. Crashes if allocation fails.

Returns
An iterator pointing to the newly inserted element.

◆ emplace_front()

template<typename T >
template<typename... Args>
reference pw::ForwardList< T >::emplace_front ( Args &&...  args)
inline

Constructs an element in-place at the beginning of the list. Crashes if allocation fails.

◆ erase_after() [1/2]

template<typename T >
iterator pw::ForwardList< T >::erase_after ( const_iterator  first,
const_iterator  last 
)
inline

Removes the elements in the range (first, last).

Returns
Iterator to last.

◆ erase_after() [2/2]

template<typename T >
iterator pw::ForwardList< T >::erase_after ( const_iterator  pos)
inline

Removes the element following pos.

Returns
Iterator to the element following the erased element, or end().

◆ insert_after() [1/5]

template<typename T >
iterator pw::ForwardList< T >::insert_after ( const_iterator  pos,
const T &  value 
)
inline

Inserts a copy of value after pos. Crashes if allocation fails.

◆ insert_after() [2/5]

template<typename T >
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
iterator pw::ForwardList< T >::insert_after ( const_iterator  pos,
InputIt  first,
InputIt  last 
)
inline

Inserts elements from range [first, last) after pos. Crashes if allocation fails.

◆ insert_after() [3/5]

template<typename T >
iterator pw::ForwardList< T >::insert_after ( const_iterator  pos,
size_type  count,
const T &  value 
)
inline

Inserts count copies of value after pos. Crashes if allocation fails.

◆ insert_after() [4/5]

template<typename T >
iterator pw::ForwardList< T >::insert_after ( const_iterator  pos,
std::initializer_list< T >  ilist 
)
inline

Inserts elements from ilist after pos. Crashes if allocation fails.

◆ insert_after() [5/5]

template<typename T >
iterator pw::ForwardList< T >::insert_after ( const_iterator  pos,
T &&  value 
)
inline

Inserts value after pos via move. Crashes if allocation fails.

◆ pop_front()

template<typename T >
void pw::ForwardList< T >::pop_front ( )
inlinenoexcept

Removes the first element of the container. If the container is empty, this function does nothing.

◆ push_front() [1/2]

template<typename T >
void pw::ForwardList< T >::push_front ( const T &  value)
inline

Prepends the given element to the beginning of the list. Crashes if allocation fails.

◆ push_front() [2/2]

template<typename T >
void pw::ForwardList< T >::push_front ( T &&  value)
inline

Prepends the given element to the beginning of the list via move. Crashes if allocation fails.

◆ remove()

template<typename T >
size_type pw::ForwardList< T >::remove ( const T &  value)
inline

Removes all elements equal to value.

Returns
The number of elements removed.

◆ remove_if()

template<typename T >
template<typename UnaryPredicate >
size_type pw::ForwardList< T >::remove_if ( UnaryPredicate  pred)
inline

Removes all elements that satisfy the predicate pred.

Returns
The number of elements removed.

◆ resize() [1/2]

template<typename T >
void pw::ForwardList< T >::resize ( size_type  count)
inline

Resizes the container to contain count elements. Default-inserts additional elements if growing. Crashes on allocation failure.

◆ resize() [2/2]

template<typename T >
void pw::ForwardList< T >::resize ( size_type  count,
const T &  value 
)
inline

Resizes the container to contain count elements, copy-inserting value if growing. Crashes on allocation failure.

◆ splice_after() [1/2]

template<typename T >
void pw::ForwardList< T >::splice_after ( const_iterator  pos,
ForwardList< T > &&  other,
const_iterator  first,
const_iterator  last 
)
inlinenoexcept

Moves the elements in the range (first, last) from other to after pos.

◆ splice_after() [2/2]

template<typename T >
void pw::ForwardList< T >::splice_after ( const_iterator  pos,
ForwardList< T > &  other,
const_iterator  first,
const_iterator  last 
)
inlinenoexcept

Moves the elements in the range (first, last) from other to after pos.

◆ swap()

template<typename T >
void pw::ForwardList< T >::swap ( ForwardList< T > &  other)
inlinenoexcept

Exchanges the contents and allocator of the container with those of other.

◆ try_assign() [1/3]

template<typename T >
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
bool pw::ForwardList< T >::try_assign ( InputIt  first,
InputIt  last 
)
inline

Attempts to replace contents with elements from [first, last). If allocation fails, the list contents remain unchanged.

◆ try_assign() [2/3]

template<typename T >
bool pw::ForwardList< T >::try_assign ( size_type  count,
const T &  value 
)
inline

Attempts to replace the contents with count copies of value. If allocation fails, the list contents remain unchanged.

◆ try_assign() [3/3]

template<typename T >
bool pw::ForwardList< T >::try_assign ( std::initializer_list< T >  ilist)
inline

Attempts to replace contents with elements from ilist. If allocation fails, the list contents remain unchanged.

◆ try_emplace_after()

template<typename T >
template<typename... Args>
bool pw::ForwardList< T >::try_emplace_after ( const_iterator  pos,
Args &&...  args 
)
inline

Attempts to construct an element in-place directly after pos.

Returns
true on success, false if allocation failed.

◆ try_emplace_front()

template<typename T >
template<typename... Args>
bool pw::ForwardList< T >::try_emplace_front ( Args &&...  args)
inline

Attempts to construct an element in-place at the beginning of the list.

Returns
true if allocation succeeded, false otherwise.

◆ try_insert_after() [1/2]

template<typename T >
template<typename InputIt , typename = std::enable_if_t<!std::is_integral_v<InputIt>>>
bool pw::ForwardList< T >::try_insert_after ( const_iterator  pos,
InputIt  first,
InputIt  last 
)
inline

Attempts to insert elements from range [first, last) after pos. If allocation fails, all partially inserted elements are erased.

◆ try_insert_after() [2/2]

template<typename T >
bool pw::ForwardList< T >::try_insert_after ( const_iterator  pos,
size_type  count,
const T &  value 
)
inline

Attempts to insert count copies of value after pos. If allocation fails, all partially inserted elements are erased (strong guarantee).

◆ try_push_front() [1/2]

template<typename T >
bool pw::ForwardList< T >::try_push_front ( const T &  value)
inline

Attempts to prepend the given element to the beginning of the list.

Returns
true if allocation succeeded, false otherwise.

◆ try_push_front() [2/2]

template<typename T >
bool pw::ForwardList< T >::try_push_front ( T &&  value)
inline

Attempts to prepend the given element to the beginning of the list via move.

Returns
true if allocation succeeded, false otherwise.

◆ try_resize() [1/2]

template<typename T >
bool pw::ForwardList< T >::try_resize ( size_type  count)
inline

Attempts to resize the container to count elements with default-inserted values. If allocation fails, the container is restored to its prior state.

◆ try_resize() [2/2]

template<typename T >
bool pw::ForwardList< T >::try_resize ( size_type  count,
const T &  value 
)
inline

Attempts to resize the container to count elements with copies of value. If allocation fails, the container is restored to its prior state.

◆ unique() [1/2]

template<typename T >
size_type pw::ForwardList< T >::unique ( )
inline

Removes consecutive duplicate elements.

Returns
The number of elements removed.

◆ unique() [2/2]

template<typename T >
template<typename BinaryPredicate >
size_type pw::ForwardList< T >::unique ( BinaryPredicate  binary_pred)
inline

Removes consecutive duplicate elements according to binary_pred.

Returns
The number of elements removed.
The documentation for this class was generated from the following file: