Cherry-pick doc updates to 2022.4 (#1336)

* [oneDPL][doc] + limitation for permutation_iterator using

* A limitation about algorithms which work with an uninitialized storage added to introduction.rst

* Adding documentation for transform_if to guide (#1317)
---------
Signed-off-by: Dan Hoeflinger <[email protected]>
Co-authored-by: MikeDvorskiy <[email protected]>

Author: timmiesmith

documentation/library_guide/introduction.rst

@@ -138,6 +138,9 @@ Known Limitations
   the dereferenced value type of the provided iterators should satisfy the ``DefaultConstructible`` requirements.
 * For ``remove``, ``remove_if``, ``unique`` the dereferenced value type of the provided
   iterators should be ``MoveConstructible``.
+* The algorithms which process uninitialized storage: ``uninitialized_copy``, ``uninitialized_copy_n``, ``uninitialized_fill``, ``uninitialized_fill_n``, ``uninitialized_fill_n``, ``uninitialized_move``, ``uninitialized_move_n``, ``uninitialized_default_construct``, ``uninitialized_default_construct_n``, ``uninitialized_value_construct``, ``uninitialized_value_construct_n``
+  should be called with a device policy when using device data and should be called with a host policy when using host data.  Otherwise, the result is undefined.
+  * The algorithms which destroy data: ``destroy``, ``destroy_n``, should be called with a host policy when using host data which was initialized on the host, and should be called with a device policy when using device data which was initialized on the device. Otherwise, the result is undefined.
 
 
 Build Your Code with |onedpl_short|

documentation/library_guide/parallel_api/additional_algorithms.rst

@@ -86,3 +86,28 @@ header.  All algorithms are implemented in the ``oneapi::dpl`` namespace.
     values: ['a', 'b', 'c', 'd', 'e', 'f']
     output_keys:   [0,    0,   3,   3,   4,   5]
     output_values: ['c', 'f', 'a', 'e', 'd', 'b']
+
+* ``transform_if``: performs a transform on the input sequence(s) elements and stores the result into the
+  corresponding position in the output sequence at each position for which the predicate applied to the 
+  element(s) evaluates to ``true``. If the predicate evaluates to ``false``, the transform is not applied for
+  the elements(s), and the output sequence's corresponding position is left unmodified. There are two overloads
+  of this function, one for a single input sequence with a unary transform and a unary predicate, and another
+  for two input sequences and a binary transform and a binary predicate.
+
+  Unary example::
+
+    unary predicate: [](auto i){return i % 2 == 0;} // is even
+    unary transform: [](auto i){return i * 2;}      // double element
+    input sequence:           [0, 1, 2, 3, 3, 3, 4, 4, 7, 6]
+    original output sequence: [9, 8, 7, 6, 5, 4, 3, 2, 1, 0]
+    final output sequence:    [0, 8, 4, 6, 5, 4, 8, 8, 1, 12]
+
+
+  Binary example::
+
+    binary predicate: [](auto a, auto b){return a == b;} // are equal
+    unary transform:  [](auto a, auto b){return a + b;}  // sum values
+    input sequence1:           [0, 1, 2, 3, 3, 3, 4, 4, 7, 6]
+    input sequence2:           [5, 1, 3, 4, 3, 3, 4, 4, 7, 9]
+    original output sequence:  [9, 9, 9, 9, 9, 9, 9, 9, 9, 9]
+    final output sequence:     [9, 2, 9, 9, 6, 6, 8, 8, 14, 9]

documentation/library_guide/parallel_api/iterators.rst

@@ -92,7 +92,8 @@ header.  All iterators are implemented in the ``oneapi::dpl`` namespace.
   a functor whose index operator defines the mapping from the ``permutation_iterator`` index to the index of the
   source iterator. The ``permutation_iterator`` is useful in implementing applications where noncontiguous
   elements of data represented by an iterator need to be processed by an algorithm as though they were contiguous.
-  An example is copying every other element to an output iterator.
+  An example is copying every other element to an output iterator. The source iterator cannot be a host-side iterator
+  in cases of algorithms executed with device policies.
 
   The ``make_permutation_iterator`` is provided to simplify construction of iterator instances. The function
   receives the source iterator and the iterator or function object representing the index map::