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

From cppreference.com
 
C++
 
Containers library
Sequence
(C++11)
(C++11)
Associative
Unordered associative
(C++11)
(C++11)
(C++11)
(C++11)
Adaptors
Views
(C++20)
 
std::forward_list
Member functions
Element access
Iterators
Capacity
Modifiers
forward_list::insert_after
Operations
Non-member functions
(C++20)(C++20)
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Deduction guides(C++17)
 
iterator insert_after( const_iterator pos, const T& value );
 (1) (since C++11)
iterator insert_after( const_iterator pos, T&& value );
 (2) (since C++11)
iterator insert_after( const_iterator pos, size_type count, const T& value );
 (3) (since C++11)
template< class InputIt >
iterator insert_after( const_iterator pos, InputIt first, InputIt last );
 (4) (since C++11)
iterator insert_after( const_iterator pos, std::initializer_list<T> ilist );
 (5) (since C++11)

Inserts elements after the specified position in the container.

1-2) inserts value after the element pointed to by pos
3) inserts count copies of the value after the element pointed to by pos
4) inserts elements from range [first, last) after the element pointed to by pos. The behavior is undefined if first and last are iterators into *this.
5) inserts elements from initializer list ilist.

No iterators or references are invalidated.

Parameters

pos - iterator after which the content will be inserted
value - element value to insert
count - number of copies to insert
first, last - the range of elements to insert
ilist - initializer list to insert the values from
Type requirements
-
InputIt must meet the requirements of LegacyInputIterator.

Return value

1-2) Iterator to the inserted element.
3) Iterator to the last element inserted, or pos if count==0.
4) Iterator to the last element inserted, or pos if first==last.
5) Iterator to the last element inserted, or pos if ilist is empty.

Exceptions

If an exception is thrown during insert_after there are no effects (strong exception guarantee).

Complexity

1-2) Constant.
3) Linear in count
4) Linear in std::distance(first, last)
5) Linear in ilist.size()

Example

Run this code
#include <forward_list>                                                         
#include <string>                                                               
#include <iostream>                                                             
#include <vector>                                                               
 
template<typename T>                                                            
std::ostream& operator<<(std::ostream& s, const std::forward_list<T>& v) {      
    s.put('[');                                                                 
    char comma[3] = {'\0', ' ', '\0'};                                          
    for (const auto& e : v) {                                                   
        s << comma << e;                                                        
        comma[0] = ',';                                                         
    }                                                                           
    return s << ']';                                                            
}                                                                               
 
int main()                                                                      
{                                                                               
    std::forward_list<std::string> words {"the", "frogurt", "is", "also", "cursed"};
    std::cout << "words: " << words << '\n';                                    
 
    // insert_after (2)                                                         
    auto beginIt = words.begin();                                               
    words.insert_after(beginIt, "strawberry");                                  
    std::cout << "words: " << words << '\n';                                    
 
    // insert_after (3)                                                         
    auto anotherIt = beginIt;                                                   
    ++anotherIt;                                                                
    anotherIt = words.insert_after(anotherIt, 2, "strawberry");                 
    std::cout << "words: " << words << '\n';                                    
 
    // insert_after (4)
    std::vector<std::string> V = { "apple", "banana", "cherry"};                
    anotherIt = words.insert_after(anotherIt, V.begin(), V.end());              
    std::cout << "words: " << words << '\n';                                    
 
    // insert_after (5)                                                         
    words.insert_after(anotherIt, {"jackfruit", "kiwifruit", "lime", "mango"});
    std::cout << "words: " << words << '\n';                                    
}

Output: 

words: [the, frogurt, is, also, cursed]
words: [the, strawberry, frogurt, is, also, cursed]
words: [the, strawberry, strawberry, strawberry, frogurt, is, also, cursed]
words: [the, strawberry, strawberry, strawberry, apple, banana, cherry, frogurt, is, also, cursed]
words: [the, strawberry, strawberry, strawberry, apple, banana, cherry, jackfruit, kiwifruit, lime, mango, frogurt, is, also, cursed]

See also

(C++11)
 constructs elements in-place after an element
(public member function)
(C++11)
 inserts an element to the beginning
(public member function)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/container/forward_list/insert_after&oldid=135246"