[oneDPL] Add sorting-by-key algorithms (#564)

Signed-off-by: Dmitriy Sobolev <[email protected]>
Co-authored-by: Alexey Kukanov <[email protected]>

Author: dmitriy-sobolev

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<typename Policy, typename KeyIt, typename ValueIt,
+        typename Comparator = std::less<typename std::iterator_traits<KeyIt>::value_type>>
+    void
+    sort_by_key(Policy&& policy, KeyIt keys_first, KeyIt keys_last,
+        ValueIt values_first,
+        Comparator comp = std::less<typename std::iterator_traits<KeyIt>::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<typename Policy, typename KeyIt, typename ValueIt,
+        typename Comparator = std::less<typename std::iterator_traits<KeyIt>::value_type>>
+    void
+    stable_sort_by_key(Policy&& policy, KeyIt keys_first, KeyIt keys_last,
+        ValueIt values_first,
+        Comparator comp = std::less<typename std::iterator_traits<KeyIt>::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