From 13362b4fed7975dd9395632772c0bd851c0a492b Mon Sep 17 00:00:00 2001 From: Dmitriy Sobolev Date: Wed, 4 Sep 2024 11:02:28 -0500 Subject: [PATCH] [oneDPL] Add sorting-by-key algorithms (#564) Signed-off-by: Dmitriy Sobolev Co-authored-by: Alexey Kukanov --- .../elements/oneDPL/source/parallel_api.rst | 53 +++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/source/elements/oneDPL/source/parallel_api.rst b/source/elements/oneDPL/source/parallel_api.rst index 4ef0f89282..e211af31f9 100644 --- a/source/elements/oneDPL/source/parallel_api.rst +++ b/source/elements/oneDPL/source/parallel_api.rst @@ -508,6 +508,59 @@ satisfy a given predicate, and stores the result to the output. Depending on the modified from its initial value. The return value is an iterator targeting past the last considered element of the output sequence, that is, ``result + (end1 - start1)``. +.. code:: cpp + + template::value_type>> + void + sort_by_key(Policy&& policy, KeyIt keys_first, KeyIt keys_last, + ValueIt values_first, + Comparator comp = std::less::value_type>()); + +``oneapi::dpl::sort_by_key`` sorts the sequence of keys ``[keys_first, keys_last)`` +and simultaneously permutes associated values at the same positions in the range +``[values_first, values_first + std::distance(keys_first, keys_last))`` +to match the order of the sorted keys. That is, a key and its associated value +will have the same index in their respective sequences after sorting. + +Keys are sorted with respect to the provided comparator object ``comp``. That means, for any +two iterators ``i`` and ``j`` to the sorted sequence of keys such that ``i`` precedes ``j``, +``comp(*j, *i) == false``. +If no ``comp`` object is provided, keys are sorted with respect to ``std::less``. + +Sorting is unstable. That means, keys which do not precede one another with respect to the given +comparator and their associated values might be ordered arbitrarily relative to each other. + +``KeyIt`` and ``ValueIt`` must satisfy the requirements of ``ValueSwappable``, +and ``Comparator`` must satisfy the requirements for the ``Compare`` parameter of ``std::sort``, +as defined by the `C++ Standard`_. + +.. code:: cpp + + template::value_type>> + void + stable_sort_by_key(Policy&& policy, KeyIt keys_first, KeyIt keys_last, + ValueIt values_first, + Comparator comp = std::less::value_type>()); + +``oneapi::dpl::stable_sort_by_key`` sorts the sequence of keys ``[keys_first, keys_last)`` +and simultaneously permutes associated values at the same positions in the range +``[values_first, values_first + std::distance(keys_first, keys_last))`` +to match the order of the sorted keys. That is, a key and its associated value +will have the same index in their respective sequences after sorting. + +Keys are sorted with respect to the provided comparator object ``comp``. That means, for any +two iterators ``i`` and ``j`` to the sorted sequence of keys such that ``i`` precedes ``j``, +``comp(*j, *i) == false``. +If no ``comp`` object is provided, keys are sorted with respect to ``std::less``. + +Sorting is stable. That means, keys which do not precede one another with respect to the given +comparator and their associated values maintain the relative order as in the original sequences. + +``KeyIt`` and ``ValueIt`` must satisfy the requirements of ``ValueSwappable``, +and ``Comparator`` must satisfy the requirements for the ``Compare`` parameter of ``std::sort``, +as defined by the `C++ Standard`_. .. _`C++ Standard`: https://isocpp.org/std/the-standard .. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html