◆ stable_sort_by_key() [3/4]

template<typename DerivedPolicy , typename RandomAccessIterator1 , typename RandomAccessIterator2 , typename StrictWeakOrdering >
__host__ __device__ void thrust::stable_sort_by_key ( const thrust::detail::execution_policy_base< DerivedPolicy > &  exec,
RandomAccessIterator1  keys_first,
RandomAccessIterator1  keys_last,
RandomAccessIterator2  values_first,
StrictWeakOrdering  comp 

stable_sort_by_key performs a key-value sort. That is, stable_sort_by_key sorts the elements in [keys_first, keys_last) and [values_first, values_first + (keys_last - keys_first)) into ascending key order, meaning that if i and j are any two valid iterators in [keys_first, keys_last) such that i precedes j, and p and q are iterators in [values_first, values_first + (keys_last - keys_first)) corresponding to i and j respectively, then *j is not less than *i.

As the name suggests, stable_sort_by_key is stable: it preserves the relative ordering of equivalent elements. That is, if x and y are elements in [keys_first, keys_last) such that x precedes y, and if the two elements are equivalent (neither x < y nor y < x) then a postcondition of stable_sort_by_key is that x still precedes y.

This version of stable_sort_by_key compares key objects using the function object comp.

The algorithm's execution is parallelized as determined by exec.

execThe execution policy to use for parallelization.
keys_firstThe beginning of the key sequence.
keys_lastThe end of the key sequence.
values_firstThe beginning of the value sequence.
compComparison operator.
Template Parameters
DerivedPolicyThe name of the derived execution policy.
RandomAccessIterator1is a model of Random Access Iterator, RandomAccessIterator1 is mutable, and RandomAccessIterator1's value_type is convertible to StrictWeakOrdering's first_argument_type and second_argument_type.
RandomAccessIterator2is a model of Random Access Iterator, and RandomAccessIterator2 is mutable.
StrictWeakOrderingis a model of Strict Weak Ordering.
The range [keys_first, keys_last)) shall not overlap the range [values_first, values_first + (keys_last - keys_first)).

The following code snippet demonstrates how to use sort_by_key to sort an array of character values using integers as sorting keys using the thrust::host execution policy for parallelization. The keys are sorted in descending order using the greater<int> comparison operator.

#include <thrust/sort.h>
const int N = 6;
int keys[N] = { 1, 4, 2, 8, 5, 7};
char values[N] = {'a', 'b', 'c', 'd', 'e', 'f'};
// keys is now { 8, 7, 5, 4, 2, 1}
// values is now {'d', 'f', 'e', 'b', 'c', 'a'}
See also