home | help 
std::list::merge(3)	       C++ Standard Libary	     std::list::merge(3)

NAME
     std::list::merge - std::list::merge

Synopsis
	void merge( list& other );		  (1)
	void merge( list&& other );		  (2) (since C++11)
	template< class Compare >		  (3)
	void merge( list& other, Compare comp );
	template< class Compare >		  (4) (since C++11)
	void merge( list&& other, Compare comp );

	The function does nothing if other refers to the same object as *this.

	Otherwise, merges other into *this. Both lists should be sorted. No ele-
     ments are
	copied,  and the container other becomes empty after the merge. This op-
     eration is
	stable: for equivalent elements in the	two  lists,  the  elements  from
     *this always
	precede the elements from other, and the order of equivalent elements of
     *this and
	other does not change.

	No  iterators  or references become invalidated. The pointers and refer-
     ences to the
	elements moved from *this, as well as the iterators referring  to  these
     elements,
	will refer to the same elements of *this, instead of other.

	1,2) Elements are compared using operator<.
	3,4) Elements are compared using comp.

	If *this or other is not sorted with respected to the corresponding com-
     parator, or
	get_allocator() != other.get_allocator(), the behavior is undefined.

Parameters
	other - another container to merge
		comparison  function  object  (i.e. an object that satisfies the
     requirements
		of Compare) which returns true if the  first  argument	is  less
     than (i.e. is
		ordered before) the second.

		The signature of the comparison function should be equivalent to
     the
		following:

		bool cmp(const Type1& a, const Type2& b);
	comp  -
		While  the  signature does not need to have const&, the function
     must not
		modify the objects passed to it and must be able to  accept  all
     values of
		type  (possibly const) Type1 and Type2 regardless of value cate-
     gory (thus,
		Type1& is not allowed
		, nor is Type1 unless for Type1 a move is equivalent to a copy
		(since C++11)).
		The types Type1 and Type2 must be such that an object of type
		list<T,&nbsp;Allocator>::const_iterator can be dereferenced  and
     then
		implicitly converted to both of them.

Type requirements
	-
	Compare must meet the requirements of Compare.

Return value
	(none)

Exceptions
	If an exception is thrown for any reason, these functions have no effect
     (strong
	exception  safety  guarantee). Except if the exception comes from a com-
     parison.

Complexity
	If other refers to the same object as *this,  no  comparisons  are  per-
     formed.

	Otherwise, given \(\scriptsize N\)N as std::distance(begin(), end()) and
	\(\scriptsize R\)R as std::distance(other.begin(), other.end()):

	1,2) At most \(\scriptsize N+R-1\)N+R-1 comparisons using operator<.
	3,4)  At  most \(\scriptsize N+R-1\)N+R-1 applications of the comparison
     function
	comp.

Example
     // Run this code

      #include <iostream>
      #include <list>

      std::ostream& operator<<(std::ostream& ostr, const std::list<int>& list)
      {
	  for (const int i : list)
	      ostr << ' ' << i;
	  return ostr;
      }

      int main()
      {
	  std::list<int> list1 = {5, 9, 1, 3, 3};
	  std::list<int> list2 = {8, 7, 2, 3, 4, 4};

	  list1.sort();
	  list2.sort();
	  std::cout << "list1: " << list1 << '\n';
	  std::cout << "list2: " << list2 << '\n';

	  list1.merge(list2);
	  std::cout << "merged:" << list1 << '\n';
      }

Output:
      list1:  1 3 3 5 9
      list2:  2 3 4 4 7 8
      merged: 1 2 3 3 3 4 4 5 7 8 9

	Defect reports

	The following behavior-changing defect	reports  were  applied	retroac-
     tively to
	previously published C++ standards.

	   DR	  Applied  to		 Behavior as published		    Cor-
     rect behavior
	LWG 300  C++98	    the effect when *this and other refer	  speci-
     fied as no-op
			    to the same object was not specified
	LWG  1207  C++98       it was unclear whether iterators and/or	    keep
     valid
			    references will be invalidated
			    O(1) node moving could not be guaranteed if  the be-
     havior is
	LWG 1215 C++98	    get_allocator() !=	other.get_allocator()	   unde-
     fined in this
									 case

See also
	splice		      moves elements from another list
			      (public member function)
	merge		      merges two sorted ranges
			      (function template)
	inplace_merge	      merges two ordered ranges in-place
			      (function template)
	ranges::merge	      merges two sorted ranges
	(C++20) 	      (niebloid)
	ranges::inplace_merge merges two ordered ranges in-place
	(C++20) 	      (niebloid)

http://cppreference.com 	   2024.06.10		     std::list::merge(3)
home | help