std::forward_list<T,Allocator>::insert_after (3) - Linux Manuals

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

NAME

std::forward_list<T,Allocator>::insert_after - std::forward_list<T,Allocator>::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 T& value ); (3) (since C++11)
template< class InputIt > (4) (since C++11)
iterator insert_after( const_iterator pos, InputIt first, InputIt last );
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]