/*
* Copyright 2008-2010 NVIDIA Corporation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/*! \file sort.h
* \brief Defines the interface to various
* sorting functions.
*/
#pragma once
#include
namespace thrust
{
/*! \addtogroup sorting
* \ingroup algorithms
* \{
*/
/*! \p sort sorts the elements in `[first, last)` into
* ascending order, meaning that if \c i and \c j are any two valid
* iterators in `[first, last)` such that \c i precedes \c j,
* then \c *j is not less than \c *i. Note: \c sort is not guaranteed
* to be stable. That is, suppose that \c *i and \c *j are equivalent:
* neither one is less than the other. It is not guaranteed that the
* relative order of these two elements will be preserved by \p sort.
*
* This version of \p sort compares objects using \c operator<.
*
* \param first The beginning of the sequence.
* \param last The end of the sequence.
*
* \tparam RandomAccessIterator is a model of Random Access Iterator,
* \p RandomAccessIterator is mutable,
* and \p RandomAccessIterator's \c value_type is a model of LessThan Comparable,
* and the ordering relation on \p RandomAccessIterator's \c value_type is a *strict weak ordering*, as defined in the
* LessThan Comparable requirements.
*
* The following code snippet demonstrates how to use \p sort to sort
* a sequence of integers.
*
* \code
* #include
* ...
* const int N = 6;
* int A[N] = {1, 4, 2, 8, 5, 7};
* thrust::sort(A, A + N);
* // A is now {1, 2, 4, 5, 7, 8}
* \endcode
*
* \see http://www.sgi.com/tech/stl/sort.html
* \see \p stable_sort
* \see \p sort_by_key
*/
template
void sort(RandomAccessIterator first,
RandomAccessIterator last);
/*! \p sort sorts the elements in `[first, last)` into
* ascending order, meaning that if \c i and \c j are any two valid
* iterators in `[first, last)` such that \c i precedes \c j,
* then \c *j is not less than \c *i. Note: \c sort is not guaranteed
* to be stable. That is, suppose that \c *i and \c *j are equivalent:
* neither one is less than the other. It is not guaranteed that the
* relative order of these two elements will be preserved by \p sort.
*
* This version of \p sort compares objects using a function object
* \p comp.
*
* \param first The beginning of the sequence.
* \param last The end of the sequence.
* \param comp Comparison operator.
*
* \tparam RandomAccessIterator is a model of Random Access Iterator,
* \p RandomAccessIterator is mutable,
* and \p RandomAccessIterator's \c value_type is convertible to \p StrictWeakOrdering's
* \c first_argument_type and \c second_argument_type.
* \tparam StrictWeakOrdering is a model of Strict Weak Ordering.
*
* \see http://www.sgi.com/tech/stl/sort.html
* \see \p stable_sort
* \see \p sort_by_key
*/
template
void sort(RandomAccessIterator first,
RandomAccessIterator last,
StrictWeakOrdering comp);
/*! \p stable_sort is much like \c sort: it sorts the elements in
* `[first, last)` into ascending order, meaning that if \c i
* and \c j are any two valid iterators in `[first, last)` such
* that \c i precedes \c j, then \c *j is not less than \c *i.
*
* As the name suggests, \p stable_sort is stable: it preserves the
* relative ordering of equivalent elements. That is, if \c x and \c y
* are elements in `[first, last)` such that \c x precedes \c y,
* and if the two elements are equivalent (neither `x < y` nor
* `y < x`) then a postcondition of \p stable_sort is that \c x
* still precedes \c y.
*
* This version of \p stable_sort compares objects using \c operator<.
*
* \param first The beginning of the sequence.
* \param last The end of the sequence.
*
* \tparam RandomAccessIterator is a model of Random Access Iterator,
* \p RandomAccessIterator is mutable,
* and \p RandomAccessIterator's \c value_type is a model of LessThan Comparable,
* and the ordering relation on \p RandomAccessIterator's \c value_type is a *strict weak ordering*, as defined in the
* LessThan Comparable requirements.
*
* The following code snippet demonstrates how to use \p sort to sort
* a sequence of integers.
*
* \code
* #include
* ...
* const int N = 6;
* int A[N] = {1, 4, 2, 8, 5, 7};
* thrust::stable_sort(A, A + N);
* // A is now {1, 2, 4, 5, 7, 8}
* \endcode
*
* \see http://www.sgi.com/tech/stl/stable_sort.html
* \see \p sort
* \see \p stable_sort_by_key
*/
template
void stable_sort(RandomAccessIterator first,
RandomAccessIterator last);
/*! \p stable_sort is much like \c sort: it sorts the elements in
* `[first, last)` into ascending order, meaning that if \c i
* and \c j are any two valid iterators in `[first, last)` such
* that \c i precedes \c j, then \c *j is not less than \c *i.
*
* As the name suggests, \p stable_sort is stable: it preserves the
* relative ordering of equivalent elements. That is, if \c x and \c y
* are elements in `[first, last)` such that \c x precedes \c y,
* and if the two elements are equivalent (neither `x < y` nor
* `y < x`) then a postcondition of \p stable_sort is that \c x
* still precedes \c y.
*
* This version of \p stable_sort compares objects using a function object
* \p comp.
*
* \param first The beginning of the sequence.
* \param last The end of the sequence.
* \param comp Comparison operator.
*
* \tparam RandomAccessIterator is a model of Random Access Iterator,
* \p RandomAccessIterator is mutable,
* and \p RandomAccessIterator's \c value_type is convertible to \p StrictWeakOrdering's
* \c first_argument_type and \c second_argument_type.
* \tparam StrictWeakOrdering is a model of Strict Weak Ordering.
*
* \see http://www.sgi.com/tech/stl/stable_sort.html
* \see \p sort
* \see \p stable_sort_by_key
*/
template
void stable_sort(RandomAccessIterator first,
RandomAccessIterator last,
StrictWeakOrdering comp);
///////////////
// Key Value //
///////////////
/*! \p sort_by_key performs a key-value sort. That is, \p 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 \c i and \c j are any two valid iterators in `[keys_first,
* keys_last)` such that \c i precedes \c j, and \c p and \c q are iterators
* in `[values_first, values_first + (keys_last - keys_first))`
* corresponding to \c i and \c j respectively, then \c *j is not less than
* \c *i.
*
* Note: \c sort_by_key is not guaranteed to be stable. That is, suppose that
* \c *i and \c *j are equivalent: neither one is less than the other. It is not
* guaranteed that the relative order of these two keys or the relative
* order of their corresponding values will be preserved by \p sort_by_key.
*
* This version of \p sort_by_key compares key objects using \c operator<.
*
* \param keys_first The beginning of the key sequence.
* \param keys_last The end of the key sequence.
* \param values_first The beginning of the value sequence.
*
* \tparam RandomAccessIterator1 is a model of Random Access Iterator,
* \p RandomAccessIterator1 is mutable,
* and \p RandomAccessIterator1's \c value_type is a model of LessThan Comparable,
* and the ordering relation on \p RandomAccessIterator1's \c value_type is a *strict weak ordering*, as defined in the
* LessThan Comparable requirements.
* \tparam RandomAccessIterator2 is a model of Random Access Iterator,
* and \p RandomAccessIterator2 is mutable.
*
* The following code snippet demonstrates how to use \p sort_by_key to sort
* an array of characters using integers as sorting keys.
*
* \code
* #include
* ...
* const int N = 6;
* int keys[N] = { 1, 4, 2, 8, 5, 7};
* char values[N] = {'a', 'b', 'c', 'd', 'e', 'f'};
* thrust::sort_by_key(keys, keys + N, values);
* // keys is now { 1, 2, 4, 5, 7, 8}
* // values is now {'a', 'c', 'b', 'e', 'f', 'd'}
* \endcode
*
* \see http://www.sgi.com/tech/stl/sort.html
* \see \p stable_sort_by_key
* \see \p sort
*/
template
void sort_by_key(RandomAccessIterator1 keys_first,
RandomAccessIterator1 keys_last,
RandomAccessIterator2 values_first);
/*! \p sort_by_key performs a key-value sort. That is, \p 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 \c i and \c j are any two valid iterators in `[keys_first,
* keys_last)` such that \c i precedes \c j, and \c p and \c q are iterators
* in `[values_first, values_first + (keys_last - keys_first))`
* corresponding to \c i and \c j respectively, then \c *j is not less than
* \c *i.
*
* Note: \c sort_by_key is not guaranteed to be stable. That is, suppose that
* \c *i and \c *j are equivalent: neither one is less than the other. It is not
* guaranteed that the relative order of these two keys or the relative
* order of their corresponding values will be preserved by \p sort_by_key.
*
* This version of \p sort_by_key compares key objects using a function object
* \c comp.
*
* \param keys_first The beginning of the key sequence.
* \param keys_last The end of the key sequence.
* \param values_first The beginning of the value sequence.
* \param comp Comparison operator.
*
* \tparam RandomAccessIterator1 is a model of Random Access Iterator,
* \p RandomAccessIterator1 is mutable,
* and \p RandomAccessIterator1's \c value_type is convertible to \p StrictWeakOrdering's
* \c first_argument_type and \c second_argument_type.
* \tparam RandomAccessIterator2 is a model of Random Access Iterator,
* and \p RandomAccessIterator2 is mutable.
* \tparam StrictWeakOrdering is a model of Strict Weak Ordering.
*
* \see http://www.sgi.com/tech/stl/sort.html
* \see \p stable_sort_by_key
* \see \p sort
*/
template
void sort_by_key(RandomAccessKeyIterator keys_first,
RandomAccessKeyIterator keys_last,
RandomAccessValueIterator values_first,
StrictWeakOrdering comp);
/*! \p stable_sort_by_key performs a key-value sort. That is, \p 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 \c i and \c j are any two valid iterators in `[keys_first,
* keys_last)` such that \c i precedes \c j, and \c p and \c q are iterators
* in `[values_first, values_first + (keys_last - keys_first))`
* corresponding to \c i and \c j respectively, then \c *j is not less than
* \c *i.
*
* As the name suggests, \p stable_sort_by_key is stable: it preserves the
* relative ordering of equivalent elements. That is, if \c x and \c y
* are elements in `[keys_first, keys_last)` such that \c x precedes \c y,
* and if the two elements are equivalent (neither `x < y` nor
* `y < x`) then a postcondition of \p stable_sort_by_key is that \c x
* still precedes \c y.
*
* This version of \p stable_sort_by_key compares key objects using \c operator<.
*
* \param keys_first The beginning of the key sequence.
* \param keys_last The end of the key sequence.
* \param values_first The beginning of the value sequence.
*
* \tparam RandomAccessIterator1 is a model of Random Access Iterator,
* \p RandomAccessIterator1 is mutable,
* and \p RandomAccessIterator1's \c value_type is a model of LessThan Comparable,
* and the ordering relation on \p RandomAccessIterator1's \c value_type is a *strict weak ordering*, as defined in the
* LessThan Comparable requirements.
* \tparam RandomAccessIterator2 is a model of Random Access Iterator,
* and \p RandomAccessIterator2 is mutable.
*
* The following code snippet demonstrates how to use \p stable_sort_by_key to sort
* an array of characters using integers as sorting keys.
*
* \code
* #include
* ...
* const int N = 6;
* int keys[N] = { 1, 4, 2, 8, 5, 7};
* char values[N] = {'a', 'b', 'c', 'd', 'e', 'f'};
* thrust::stable_sort_by_key(keys, keys + N, values);
* // keys is now { 1, 2, 4, 5, 7, 8}
* // values is now {'a', 'c', 'b', 'e', 'f', 'd'}
* \endcode
*
* \see http://www.sgi.com/tech/stl/sort.html
* \see \p sort_by_key
* \see \p stable_sort
*/
template
void stable_sort_by_key(RandomAccessKeyIterator keys_first,
RandomAccessKeyIterator keys_last,
RandomAccessValueIterator values_first);
/*! \p stable_sort_by_key performs a key-value sort. That is, \p 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 \c i and \c j are any two valid iterators in `[keys_first,
* keys_last)` such that \c i precedes \c j, and \c p and \c q are iterators
* in `[values_first, values_first + (keys_last - keys_first))`
* corresponding to \c i and \c j respectively, then \c *j is not less than
* \c *i.
*
* As the name suggests, \p stable_sort_by_key is stable: it preserves the
* relative ordering of equivalent elements. That is, if \c x and \c y
* are elements in `[keys_first, keys_last)` such that \c x precedes \c y,
* and if the two elements are equivalent (neither `x < y` nor
* `y < x`) then a postcondition of \p stable_sort_by_key is that \c x
* still precedes \c y.
*
* This version of \p stable_sort_by_key compares key objects using the function
* object \p comp.
*
* \param keys_first The beginning of the key sequence.
* \param keys_last The end of the key sequence.
* \param values_first The beginning of the value sequence.
* \param comp Comparison operator.
*
* \tparam RandomAccessIterator1 is a model of Random Access Iterator,
* \p RandomAccessIterator1 is mutable,
* and \p RandomAccessIterator1's \c value_type is convertible to \p StrictWeakOrdering's
* \c first_argument_type and \c second_argument_type.
* \tparam RandomAccessIterator2 is a model of Random Access Iterator,
* and \p RandomAccessIterator2 is mutable.
* \tparam StrictWeakOrdering is a model of Strict Weak Ordering.
*
* \see http://www.sgi.com/tech/stl/sort.html
* \see \p sort_by_key
* \see \p stable_sort
*/
template
void stable_sort_by_key(RandomAccessKeyIterator keys_first,
RandomAccessKeyIterator keys_last,
RandomAccessValueIterator values_first,
StrictWeakOrdering comp);
/*! \} // end sorting
*/
} // end namespace thrust
#include