Merge updates from the upstream

source/elements/oneDPL/source/parallel_api.rst

@@ -24,6 +24,18 @@ Iterators
 The oneDPL iterators are defined in the ``<oneapi/dpl/iterator>`` header,
 in ``namespace oneapi::dpl``.
 
+Let us define a named requirement, ``AdaptingIteratorSource``, to describe valid random access iterator-like
+types that can be used as source for oneDPL iterators as described below.
+The type ``Iter`` satisfies the ``AdaptingIteratorSource`` named requirement if it is any of the following:
+
+ * A random access iterator
+ * The unspecified iterator-like type returned by ``oneapi::dpl::begin`` or ``oneapi::dpl::end``
+ * A ``permutation_iterator``
+ * A ``transform_iterator``
+ * A ``counting_iterator``
+ * A ``discard_iterator``
+ * A ``zip_iterator``
+
 .. code:: cpp
 
     template <typename Integral>
@@ -153,7 +165,19 @@ defined by the source iterator provided, and whose iteration order over the dere
 is defined by either another iterator or a functor that maps the ``permutation_iterator`` index
 to the index of the source iterator. The arithmetic and comparison operators of
 ``permutation_iterator`` behave as if applied to integer counter values maintained by the
-iterator instances to determine their position in the index map.
+iterator instances to determine their position in the index map. ``SourceIterator`` must satisfy
+``AdaptingIteratorSource``.
+
+The type ``IndexMap`` must be one of the following:
+
+ * A random access iterator
+ * The unspecified iterator-like type returned by ``oneapi::dpl::begin`` or ``oneapi::dpl::end``
+ * A ``permutation_iterator``
+ * A ``transform_iterator``
+ * A ``counting_iterator``
+ * A functor with a signature equivalent to ``T operator()(const T&) const`` where ``T`` is a
+   ``std::iterator_traits<SourceIterator>::difference_type``
+
 
 ``permutation_iterator::operator*`` uses the counter value of the instance on which
 it is invoked to index into the index map. The corresponding value in the map is then used
@@ -222,7 +246,8 @@ defined by the unary function and source iterator provided. When dereferenced,
 element of the source iterator; dereference operations cannot be used to modify the elements of
 the source iterator unless the unary function result includes a reference to the element. The
 arithmetic and comparison operators of ``transform_iterator`` behave as if applied to the
-source iterator itself.
+source iterator itself. The template type ``Iterator`` must satisfy
+``AdaptingIteratorSource``.
 
 .. code:: cpp
 
@@ -280,7 +305,8 @@ using the source iterator and unary function object provided.
 the value returned from ``zip_iterator`` is a tuple of the values returned by dereferencing the
 source iterators over which the ``zip_iterator`` is defined. The arithmetic operators of
 ``zip_iterator`` update the source iterators of a ``zip_iterator`` instance as though the
-operation were applied to each of these iterators.
+operation were applied to each of these iterators. The types ``T`` within the template pack 
+``Iterators...`` must satisfy ``AdaptingIteratorSource``.
 
 .. code:: cpp
 
@@ -451,6 +477,38 @@ than an element in the range being searched.
 
 The elements of ``[start, end)`` must be partitioned with respect to the comparator used.
 
+.. code:: cpp
+
+  template <typename Policy, typename InputIt, typename OutputIt, typename UnaryOp,
+      typename UnaryPredicate>
+  OutputIt
+  transform_if(Policy&& policy, InputIt start, InputIt end, OutputIt result, UnaryOp op,
+      UnaryPredicate pred);                                                               // (1)
+
+  template <typename Policy, typename InputIt1, typename InputIt2, typename OutputIt, 
+      typename BinaryOp, typename BinaryPredicate>
+  OutputIt
+  transform_if(Policy&& policy, InputIt1 start1, InputIt1 end1, InputIt2 start2, OutputIt result,
+      BinaryOp op, BinaryPredicate pred);                                                 // (2)
+
+``oneapi::dpl::transform_if`` applies a given function to the elements of the input sequence(s) that
+satisfy a given predicate, and stores the result to the output. Depending on the arguments, the algorithm:
+
+1. Evaluates the unary predicate ``pred`` for each position ``i`` of the sequence
+   ``[start, end)`` and if ``pred(start[i]) == true``, it performs the unary operation
+   ``op(start[i])`` and stores the result into ``result[i]``. If
+   ``pred(start[i]) == false``, the data element ``result[i]`` is not modified from its
+   initial value. The return value is an iterator targeting past the last considered element of
+   the output sequence, that is, ``result + (end - start)``.
+
+2. Evaluates the binary predicate ``pred`` for each position ``i`` of the sequence
+   ``[start1, end1)`` and if ``pred(start1[i], start2[i]) == true``, it performs the
+   binary operation ``op(start1[i], start2[i])`` and stores the result into ``result[i]``.
+   If ``pred(start1[i], start2[i]) == false``, the data element ``result[i]`` is not
+   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)``.
+
+
 .. toctree::
 
    parallel_api/parallel_range_api.rst