std::forward_list::insert_after(3)

NAME
std::forward_list::insert_after - std::forward_list::insert_after

Synopsis
   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 (3) (since C++11)
   T& value );
   template< class InputIt >
   iterator insert_after( const_iterator pos, InputIt first, InputIt (4) (since C++11)
   last );
   iterator insert_after( const_iterator pos, (5) (since C++11)
   std::initializer_list<T> ilist );
   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
   emplace_after constructs elements in-place after an element
   (C++11) (public member function)
   push_front inserts an element to the beginning
   (C++11) (public member function)