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

NAME
     std::list::sort - std::list::sort

Synopsis
	void sort();		   (1)
	template< class Compare >  (2)
	void sort( Compare comp );

	Sorts  the  elements  and preserves the order of equivalent elements. No
     references or
	iterators become invalidated.

	1) Elements are compared using operator<.
	2) Elements are compared using comp.

	If an exception is thrown, the order of elements in  *this  is	unspeci-
     fied.

Parameters
	       comparison function object (i.e. an object that satisfies the re-
     quirements 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 category
     (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,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)

Complexity
	Given \(\scriptsize N\)N as size():

	1) Approximately \(\scriptsize N \cdot log(N)\)NA.log(N) comparisons us-
     ing operator<.
	2) Approximately \(\scriptsize N \cdot log(N)\)NA.log(N) applications of
     the
	comparison function comp.

Notes
	std::sort  requires  random  access iterators and so cannot be used with
     list. This
	function also differs from std::sort in that it does not require the el-
     ement type of
	the list to be swappable, preserves the values	of  all  iterators,  and
     performs a
	stable sort.

Example
     // Run this code

      #include <functional>
      #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> list{8, 7, 5, 9, 0, 1, 3, 2, 6, 4};
	  std::cout << "initially: " << list << '\n';

	  list.sort();
	  std::cout << "ascending: " << list << '\n';

	  list.sort(std::greater<int>());
	  std::cout << "descending:" << list << '\n';
      }

Output:
      initially:  8 7 5 9 0 1 3 2 6 4
      ascending:  0 1 2 3 4 5 6 7 8 9
      descending: 9 8 7 6 5 4 3 2 1 0

       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 1207 C++98	    it was unclear whether iterators and/or	    keep
     valid
			    references will be invalidated

See also
	reverse reverses the order of the elements
		(public member function)

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