Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

NAME
       std::sort - std::sort

Synopsis
	  Defined in header <algorithm>
	  template<   class  RandomIt  >				(until
       C++20)
	  void sort( RandomIt first, RandomIt last );
	  template< class RandomIt >
	  constexpr void  sort(	 RandomIt  first,  RandomIt		(since
       C++20)
	  last );
	  template< class ExecutionPolicy, class RandomIt
	  >
							       (2)	(since
       C++17)
	  void sort( ExecutionPolicy&& policy,

	  RandomIt first, RandomIt last	);
	  template< class RandomIt, class Compare >	   (1)
	  void	    sort(      RandomIt	     first,	  RandomIt	 last,
       (until C++20)
	  Compare comp );
	  template< class RandomIt, class Compare >
	  constexpr	 void	   sort(      RandomIt	   first,     RandomIt
       (since C++20)
	  last,	Compare	comp );				       (3)
	  template< class ExecutionPolicy, class RandomIt,
	  class	Compare	>
								   (4)
       (since C++17)
	  void sort( ExecutionPolicy&& policy,

	  RandomIt first, RandomIt last, Compare comp );

	  Sorts	the elements in	the range [first, last)	in non-descending  or-
       der. The	order of
	  equal	elements is not	guaranteed to be preserved.

	  A  sequence  is  sorted with respect to a comparator comp if for any
       iterator	it
	  pointing to the sequence and any non-negative	integer	n such that it
       + n is a	valid
	  iterator pointing to an element of the  sequence,  comp(*(it	+  n),
       *it) (or	*(it + n)
	  < *it) evaluates to false.

	  1) Elements are compared using operator<.
	  3)  Elements are compared using the given binary comparison function
       comp.
	  2,4) Same as (1,3), but executed according to	 policy.  These	 over-
       loads do	not
	  participate in overload resolution unless
	  std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>
	  (until C++20)
	  std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>
	  (since C++20)	is true.

Parameters
	  first, last -	 the range of elements to sort
	  policy      -	 the execution policy to use. See execution policy for
       details.
			 comparison  function object (i.e. an object that sat-
       isfies 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  re-
       gardless	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
			 RandomIt can be dereferenced and then implicitly con-
       verted to both of
			 them.

Type requirements
	  -
	  RandomIt must	meet the requirements of ValueSwappable	and
	  LegacyRandomAccessIterator.
	  -
	  The type of dereferenced RandomIt  must  meet	 the  requirements  of
       MoveAssignable and
	  MoveConstructible.
	  -
	  Compare must meet the	requirements of	Compare.

Return value
	  (none)

Complexity
	  O(Nlog(N)),  where  N	 =  std::distance(first,  last)	comparisons on
       (until C++11)
	  average.
	  O(Nlog(N)),  where  N	 =  std::distance(first,  last)	  comparisons.
       (since C++11)

Exceptions
	  The overloads	with a template	parameter named	ExecutionPolicy	report
       errors as
	  follows:

	    *  If  execution  of  a  function invoked as part of the algorithm
       throws an exception
	      and ExecutionPolicy is one of the	standard policies, std::termi-
       nate is called.
	      For any other ExecutionPolicy, the behavior  is  implementation-
       defined.
	    *  If  the	algorithm  fails to allocate memory, std::bad_alloc is
       thrown.

Possible implementation
	  See also the implementations in libstdc++ and	libc++.

Example
       // Run this code

	#include <algorithm>
	#include <functional>
	#include <array>
	#include <iostream>
	#include <string_view>

	int main()
	{
	    std::array<int, 10>	s = {5,	7, 4, 2, 8, 6, 1, 9, 0,	3};

	    auto print = [&s](std::string_view const rem) {
		for (auto a : s) {
		    std::cout << a << '	';
		}
		std::cout << ":	" << rem << '\n';
	    };

	    std::sort(s.begin(), s.end());
	    print("sorted with the default operator<");

	    std::sort(s.begin(), s.end(), std::greater<int>());
	    print("sorted with the standard library compare function object");

	    struct {
		bool operator()(int a, int b) const { return a < b; }
	    } customLess;
	    std::sort(s.begin(), s.end(), customLess);
	    print("sorted with a custom	function object");

	    std::sort(s.begin(), s.end(), [](int a, int	b) {
		return a > b;
	    });
	    print("sorted with a lambda	expression");
	}

Output:
	0 1 2 3	4 5 6 7	8 9 : sorted with the default operator<
	9 8 7 6	5 4 3 2	1 0 : sorted with the standard library	compare	 func-
       tion object
	0 1 2 3	4 5 6 7	8 9 : sorted with a custom function object
	9 8 7 6	5 4 3 2	1 0 : sorted with a lambda expression

See also
	  partial_sort sorts the first N elements of a range
		       (function template)
	  stable_sort	sorts  a  range	of elements while preserving order be-
       tween equal elements
		       (function template)
	  ranges::sort sorts a range into ascending order
	  (C++20)      (niebloid)

http://cppreference.com		  2022.07.31			  std::sort(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::sort&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help