std::forward_list<T,Allocator>::emplace_after

template< class... Args > iterator emplace_after( const_iterator pos, Args&&... args );		(since C++11)

Inserts a new element into a position after the specified position in the container. The element is constructed in-place, i.e. no copy or move operations are performed. The constructor of the element is called with exactly the same arguments, as supplied to the function.

No iterators or references are invalidated.

Parameters

pos	-	iterator after which the new element will be constructed
args	-	arguments to forward to the constructor of the element

Return value

iterator to the new element.

Complexity

Constant.

Exceptions

If an exception is thrown for any reason, this function has no effect (strong exception safety guarantee).

Example

The example demonstrates a canonical filling of a single-linked list in natural (as opposed to reverse) order.

Run this code

#include <forward_list>
#include <iostream>
#include <string>
 
struct Sum
{
    std::string remark;
    int sum;
 
    Sum(std::string remark, int sum)
        : remark{std::move(remark)}, sum{sum} {}
 
    void print() const
    {
        std::cout << remark << " = " << sum << '\n';
    }
};
 
int main()
{
    std::forward_list<Sum> list;
 
    auto iter = list.before_begin();
    std::string str{"1"};
 
    for (int i{1}, sum{1}; i != 10; sum += i)
    {
        iter = list.emplace_after(iter, str, sum);
        ++i;
        str += " + " + std::to_string(i);
    }
 
    for (const Sum& s : list)
        s.print();
}

Output:

1 = 1
1 + 2 = 3
1 + 2 + 3 = 6
1 + 2 + 3 + 4 = 10
1 + 2 + 3 + 4 + 5 = 15
1 + 2 + 3 + 4 + 5 + 6 = 21
1 + 2 + 3 + 4 + 5 + 6 + 7 = 28
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 = 36
1 + 2 + 3 + 4 + 5 + 6 + 7 + 8 + 9 = 45

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Technical specifications
Symbols index
External libraries

Sequence
array (C++11)
vector
vector<bool>
deque
forward_list (C++11)
list
Associative
set
multiset
map
multimap
Unordered associative
unordered_set (C++11)
unordered_multiset (C++11)
unordered_map (C++11)
unordered_multimap (C++11)
Adaptors
stack
queue
priority_queue
flat_set (C++23)
flat_multiset (C++23)
flat_map (C++23)
flat_multimap (C++23)
Views
span (C++20)
mdspan (C++23)
Iterator invalidation
Member function table
Non-member function table

Member functions
forward_list::forward_list
forward_list::~forward_list
forward_list::operator=
forward_list::assign
forward_list::assign_range (C++23)
forward_list::get_allocator
Element access
forward_list::front
Iterators
forward_list::before_beginforward_list::cbefore_begin
forward_list::beginforward_list::cbegin
forward_list::endforward_list::cend
Capacity
forward_list::empty
forward_list::max_size
Modifiers
forward_list::clear
forward_list::insert_after
forward_list::emplace_after
forward_list::insert_range_after (C++23)
forward_list::erase_after
forward_list::push_front
forward_list::emplace_front
forward_list::prepend_range (C++23)
forward_list::pop_front
forward_list::resize
forward_list::swap
Operations
forward_list::merge
forward_list::splice_after
forward_list::removeforward_list::remove_if
forward_list::reverse
forward_list::unique
forward_list::sort
Non-member functions
std::swap
eraseerase_if (C++20)(C++20)
operator==operator!=operator<operator>operator<=operator>=operator<=> (until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Deduction guides(C++17)