public member function

std::forward_list::merge

<forward_list>
(1)
  void merge ( forward_list& fwdlst );
  void merge ( forward_list&& fwdlst );
(2)
template <class Compare>
  void merge ( forward_list& fwdlst, Compare comp );
template <class Compare>
  void merge ( forward_list&& fwdlst, Compare comp );
Merge sorted lists
Merges fwdlst into the forward_list by moving all of its elements into the container at their respective ordered positions. This effectively removes all the elements in fwdlst (which becomes empty), and inserts them into the container (which expands in size by the number of elements moved).

The template versions with two parameters (2), have the same behavior, but take a specific predicate (comp) to perform the comparison operation in charge of determining the insertion points. The comparison function has to perform weak strict ordering (which basically means the comparison operation is required to be transitive but not reflexive).

The merging is performed using two iterators: one to iterate through fwdlst and another one to keep the insertion point in the forward_list object; During the iteration of fwdlst, if the current element in fwdlst compares less than the element at the current insertion point in the forward_list object, the element is removed from fwdlst and inserted into that location, otherwise the insertion point is advanced. This operation is repeated until end is reached, in which moment the remaining elements of fwdlst (if any) are moved to the end of the forward_list object and the function returns (this last operation is performed in constant time).

The entire operation does not involve the construction, destruction or copy of any element object. They are moved, no matter whether fwdlst is lvalue or rvalue.

If no ordering is required, another option for merging lists is member function forward_list::splice_after, which is faster.

Parameters

fwdlst
A forward_list object containing the same type of objects as this container (with the same template arguments).
Note that this function modifies fwdlst no matter whether an lvalue or rvalue reference is passed.
comp
Comparison function that, taking two values of the same type than those contained in the list object, returns true if the first argument is to be considered less than the second, and false otherwise.
Compare can either be a function pointer type or a class that overloads operator().

Return value

none

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// forward_list::merge
#include <iostream>
#include <forward_list>
#include <functional>

int main ()
{
  std::forward_list<double> first = {4.2, 2.9, 3.1};
  std::forward_list<double> second = {1.4, 7.7, 3.1};
  std::forward_list<double> third = {6.2, 3.7, 7.1};

  first.sort();
  second.sort();
  first.merge(second);

  std::cout << "first contains:";
  for (double& x: first) std::cout << " " << x;
  std::cout << std::endl;

  first.sort (std::greater<double>());
  third.sort (std::greater<double>());
  first.merge (third, std::greater<double>());

  std::cout << "first contains:";
  for (double& x: first) std::cout << " " << x;
  std::cout << std::endl;

  return 0;
}


Output:
first contains: 1.4 2.9 3.1 3.1 4.2 7.7
first contains: 7.7 7.1 6.2 4.2 3.7 3.1 3.1 2.9 1.4

Complexity

At most, linear in the sum of both container sizes minus one (comparisons).

Iterator validity

The iterators, pointers and references that referred to moved elements keep referring to those same elements, but iterators now iterate into the container the elements have been transferred to.

See also