diff --git a/docs/source/API/algorithms/std-algorithms/all/StdEqual.md b/docs/source/API/algorithms/std-algorithms/all/StdEqual.md deleted file mode 100644 index 15f01ffdb..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdEqual.md +++ /dev/null @@ -1,130 +0,0 @@ - -# `equal` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -bool equal(const ExecutionSpace& exespace, IteratorType1 first1, - IteratorType1 last1, IteratorType2 first2); (1) - -template -bool equal(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first1, IteratorType1 last1, IteratorType2 first2); (2) - -template -bool equal(const ExecutionSpace& exespace, IteratorType1 first1, (3) - IteratorType1 last1, IteratorType2 first2, - BinaryPredicateType predicate); - -template -bool equal(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first1, IteratorType1 last1, IteratorType2 first2, (4) - BinaryPredicateType predicate); - -template -bool equal(const ExecutionSpace& exespace, - const Kokkos::View& view1, (5) - Kokkos::View& view2); - -template -bool equal(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view1, (6) - Kokkos::View& view2); - -template -bool equal(const ExecutionSpace& exespace, - const Kokkos::View& view1, (7) - Kokkos::View& view2, BinaryPredicate pred); - -template -bool equal(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view1, (8) - Kokkos::View& view2, BinaryPredicate pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- (1,2,3,4): returns true if the range `[first1, last1)` is equal to the range `[first2, first2 + (last1 - first1))`, -and false otherwise -- (5,6,7,8): returns true if `view1` and `view2` are equal and false otherwise - -- for (1,2,5,6) equality is checked via `operator == `, while for (3,4,7,8) equality is checked via -the binary predicate `pred`. - -## Parameters and Requirements - -- `exespace`: - - execution space instance - -- `label`: - - (1,3): The default string is "Kokkos::equal_iterator_api_default" - - (5,7): The default string is "Kokkos::equal_view_api_default" - -- `first1`, `last1`, `first2`: - - range of elements to read and compare - - must be *random access iterators* - - must represent a valid range, i.e., `last1 >= first1` (checked in debug mode) - - must be accessible from `exespace` - -- `view1`, `view2`: - - views to read elements and compare - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` - -- `pred` - ```cpp - template - struct IsEqualFunctor { - KOKKOS_INLINE_FUNCTION - bool operator()(const ValueType1& a, const ValueType2& b) const { - return (a == b); - } - }; - ``` - -## Return - -- `true` or `false` for (1,2,5,6) based on `operator == `. -- `true` or `false` for (3,4,7,8) based on the BinaryPredicate `pred` - -## Example - -```cpp -namespace KE = Kokkos::Experimental; - -template -struct IsEqualFunctor { - - KOKKOS_INLINE_FUNCTION - bool operator()(const ValueType1& a, const ValueType2& b) const { - return (a == b); - } -}; - -auto exespace = Kokkos::DefaultExecutionSpace; -using view_type = Kokkos::View; -view_type a("a", 15); -view_type b("b", 15); -// fill a,b somehow - -// create functor -IsEqualFunctor p(); - -bool isEqual = KE::equal(exespace, KE::begin(a), KE::end(a), KE::begin(b), KE::end(b) p); - -// assuming OpenMP is enabled, then you can also explicitly call -bool isEqual = KE::equal(Kokkos::OpenMP(), KE::begin(a), KE::end(a), KE::begin(b), KE::end(b), p); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdEqual.rst b/docs/source/API/algorithms/std-algorithms/all/StdEqual.rst new file mode 100644 index 000000000..a220256c8 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdEqual.rst @@ -0,0 +1,252 @@ + +``equal`` +========= + +Header: ```` + +Description +----------- + +Returns true if two ranges or two rank-1 ``View`` s are equal. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + bool equal(const ExecutionSpace& exespace, (1) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2); + + template + bool equal(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2); + + template + bool equal(const ExecutionSpace& exespace, (3) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + BinaryPredicateType predicate); + + template + bool equal(const std::string& label, const ExecutionSpace& exespace, (4) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + BinaryPredicateType predicate); + + template + bool equal(const ExecutionSpace& exespace, IteratorType1 first1, (5) + IteratorType1 last1, IteratorType2 first2, + IteratorType2 last2); + + template + bool equal(const std::string& label, const ExecutionSpace& exespace, (6) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, IteratorType2 last2); + + template + bool equal(const ExecutionSpace& exespace, (7) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, IteratorType2 last2, + BinaryPredicateType predicate); + + template + bool equal(const std::string& label, const ExecutionSpace& exespace, (8) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, IteratorType2 last2, + BinaryPredicateType predicate); + + template + bool equal(const ExecutionSpace& exespace, (9) + const Kokkos::View& view1, + const Kokkos::View& view2); + + template + bool equal(const std::string& label, const ExecutionSpace& exespace, (10) + const Kokkos::View& view1, + const Kokkos::View& view2); + + template + bool equal(const ExecutionSpace& exespace, (11) + const Kokkos::View& view1, + const Kokkos::View& view2, + BinaryPredicate pred); + + template + bool equal(const std::string& label, const ExecutionSpace& exespace, (12) + const Kokkos::View& view1, + const Kokkos::View& view2, + BinaryPredicate pred); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + bool equal(const TeamHandleType& teamHandle, (13) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2); + + template + KOKKOS_FUNCTION + bool equal(const TeamHandleType& teamHandle, (14) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, + BinaryPredicateType predicate); + + template + KOKKOS_FUNCTION + bool equal(const TeamHandleType& teamHandle, (15) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, IteratorType2 last2); + + template + KOKKOS_FUNCTION + bool equal(const TeamHandleType& teamHandle, (16) + IteratorType1 first1, IteratorType1 last1, + IteratorType2 first2, IteratorType2 last2, + BinaryPredicateType predicate); + + template + KOKKOS_FUNCTION + bool equal(const TeamHandleType& teamHandle, (17) + const Kokkos::View& view1, + const Kokkos::View& view2); + + template + KOKKOS_FUNCTION + bool equal(const TeamHandleType& teamHandle, (18) + const Kokkos::View& view1, + const Kokkos::View& view2, + BinaryPredicate pred); + + +Overload Set Detailed Description +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- (1,2,3,4,13,14): returns true if the range ``[first1, last1)`` is equal to the + range ``[first2, first2 + (last1 - first1))``, and false otherwise + +- (5,6,7,8,15,16): returns true if the range ``[first1, last1)`` is equal + to the range ``[first2, last2)``, and false otherwise + +- (9,10,11,12,17,18): returns true if ``view1`` and ``view2`` are equal and false otherwise + +- where applicable, the binary predicate ``pred`` is used to check equality between + two elements, otherwise ``operator ==`` is used + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - (1,3,5,7): The default string is "Kokkos::equal_iterator_api_default" + + - (9,11): The default string is "Kokkos::equal_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first1``, ``last1``, ``first2``, ``last2``: iterators defining the ranges to read and compare + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last1 >= first1`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view1``, ``view2``: views to compare + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``pred``: *binary* functor returning ``true`` if two arguments should be considered "equal". + + ``pred(a,b)`` must be valid to be called from the execution space passed, or + the execution space associated with the team handle, and convertible to bool + for every pair of arguments ``a,b`` of type ``ValueType1`` and ``ValueType2``, + respectively, ``ValueType1`` and ``ValueType{1,2}`` are the value types of + ``IteratorType{1,2}`` or ``view{1,2}``, and must not modify ``a,b``. + + - must conform to: + + .. code-block:: cpp + + template + struct IsEqualFunctor { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType1& a, const ValueType2& b) const { + return (a == b); + } + }; + +Return Value +~~~~~~~~~~~~ + +If the elements of the two ranges or Views are equal, returns ``true``, otherwise ``false``. + +Corner cases when ``false`` is returned: + +- if ``view1.extent(0) != view2.extent(1)`` for all overloads accepting Views + +- if the lenght of the range ``[first1, last)`` is not equal to lenght of ``[first2,last2)`` + + +Example +------- + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + + template + struct IsEqualFunctor { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType1& a, const ValueType2& b) const { + return (a == b); + } + }; + + auto exespace = Kokkos::DefaultExecutionSpace; + using view_type = Kokkos::View; + view_type a("a", 15); + view_type b("b", 15); + // fill a,b somehow + + // create functor + IsEqualFunctor p(); + + bool isEqual = KE::equal(exespace, KE::begin(a), KE::end(a), + KE::begin(b), KE::end(b) p); + + // To run explicitly on the host (assuming a and b are accessible on Host) + bool isEqual = KE::equal(Kokkos::DefaultHostExecutionSpace(), KE::begin(a), KE::end(a), + KE::begin(b), KE::end(b), p); diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFind.md b/docs/source/API/algorithms/std-algorithms/all/StdFind.md deleted file mode 100644 index 476798de6..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdFind.md +++ /dev/null @@ -1,78 +0,0 @@ - -# `find` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -InputIterator find(const ExecutionSpace& exespace, (1) - InputIterator first, InputIterator last, - const T& value); - -template -InputIterator find(const std::string& label, const ExecutionSpace& exespace, (2) - InputIterator first, InputIterator last, - const T& value); - -template -auto find(const ExecutionSpace& exespace, (3) - const ::Kokkos::View& view, - const T& value); - -template -auto find(const std::string& label, const ExecutionSpace& exespace, (4) - const ::Kokkos::View& view, - const T& value); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Returns an iterator to the *first* element in `[first, last)` (1,2) or ``view`` (3,4) -that equals `value`. Equality is checked using `operator==`. - -## Parameters and Requirements - -- `exespace`: - - execution space instance - -- `label`: - - string forwarded to all implementation kernels for debugging purposes - - for 1, the default string is: "Kokkos::find_iterator_api_default" - - for 3, the default string is: "Kokkos::find_view_api_default" - -- `first, last`: - - range of elements to search in - - must be *random access iterators*, e.g., returned from `Kokkos::Experimental::(c)begin/(c)end` - - must represent a valid range, i.e., `last >= first` (this condition is checked in debug mode) - - must be accessible from `exespace` - -- `view`: - - must be rank-1, and have `LayoutLeft`, `LayoutRight`, or `LayoutStride` - - must be accessible from `exespace` - -## Return - -- (1,2): `InputIterator` instance pointing to the first element that equals `value`, or `last` if no elements is found -- (2,3): iterator to the first element that equals `value`, or `Kokkos::Experimental::end(view)` if none is found - -## Example - -```cpp -namespace KE = Kokkos::Experimental; -auto exespace = Kokkos::DefaultExecutionSpace; -using view_type = Kokkos::View; -view_type a("a", 15); -// fill "a" somehow - -auto exespace = Kokkos::DefaultExecutionSpace; -auto it1 = KE::find(exespace, KE::cbegin(a), KE::cend(a), 5); - -// assuming OpenMP is enabled and "a" is host-accessible, you can also do -auto it2 = KE::find(Kokkos::OpenMP(), KE::begin(a), KE::end(a), 5); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFind.rst b/docs/source/API/algorithms/std-algorithms/all/StdFind.rst new file mode 100644 index 000000000..ced0071e1 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFind.rst @@ -0,0 +1,117 @@ + +``find`` +======== + +Header: ```` + +Description +----------- + +Returns an iterator to the *first* element in a range or rank-1 ``View`` +that equals a target value. Equality is checked using ``operator==``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + InputIterator find(const ExecutionSpace& exespace, (1) + InputIterator first, InputIterator last, + const T& value); + + template + InputIterator find(const std::string& label, const ExecutionSpace& exespace, (2) + InputIterator first, InputIterator last, + const T& value); + + template + auto find(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + const T& value); + + template + auto find(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + const T& value); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + InputIterator find(const TeamHandleType& teamHandle, (5) + InputIterator first, InputIterator last, + const T& value); + + template + KOKKOS_FUNCTION + auto find(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + const T& value); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - for 1, the default string is: "Kokkos::find_iterator_api_default" + + - for 3, the default string is: "Kokkos::find_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to search in + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last >= first`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view``: view to search in + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +Return Value +~~~~~~~~~~~~ + +- (1,2,5): ``InputIterator`` instance pointing to the first element that equals ``value``, + or ``last`` if no element is found + +- (3,4,6): iterator to the first element that equals ``value``, + or ``Kokkos::Experimental::end(view)`` if no elememt is found + + +Example +------- + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + auto exespace = Kokkos::DefaultExecutionSpace; + using view_type = Kokkos::View; + view_type a("a", 15); + // fill "a" somehow + + auto exespace = Kokkos::DefaultExecutionSpace; + auto it1 = KE::find(exespace, KE::cbegin(a), KE::cend(a), 5); + + // assuming OpenMP is enabled and "a" is host-accessible, you can also do + auto it2 = KE::find(Kokkos::OpenMP(), KE::begin(a), KE::end(a), 5); diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindEnd.md b/docs/source/API/algorithms/std-algorithms/all/StdFindEnd.md deleted file mode 100644 index 539efbc12..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdFindEnd.md +++ /dev/null @@ -1,80 +0,0 @@ - -# `find_end` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -IteratorType1 find_end(const ExecutionSpace& exespace, IteratorType1 first, - IteratorType1 last, IteratorType2 s_first, (1) - IteratorType2 s_last); - -template -IteratorType1 find_end(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first, IteratorType1 last, (2) - IteratorType2 s_first, IteratorType2 s_last); - -template -auto find_end(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (3) - const ::Kokkos::View& s_view); - -template -auto find_end(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (4) - const ::Kokkos::View& s_view); - -// overload set 2: binary predicate passed -template -IteratorType1 find_end(const ExecutionSpace& exespace, IteratorType1 first, - IteratorType1 last, IteratorType2 s_first, (5) - IteratorType2 s_last, const BinaryPredicateType& pred); - -template -IteratorType1 find_end(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first, IteratorType1 last, (6) - IteratorType2 s_first, IteratorType2 s_last, - const BinaryPredicateType& pred); - -template -auto find_end(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (7) - const ::Kokkos::View& s_view, - const BinaryPredicateType& pred); - -template -auto find_end(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (8) - const ::Kokkos::View& s_view, - const BinaryPredicateType& pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- 1,2,5,6: searches for the last occurrence of the sequence `[s_first, s_last)` -in the range `[first, last)` comparing elements via `operator ==` (1,2) or via `pred` (5,6) - -- 3,4,7,8: searches for the last occurrence of the `s_view` in `view` -comparing elements via `operator ==` (3,4 or via `pred` (7,8) - -## Parameters and Requirements - -- `exespace`, `s_first`, `s_last`, `first`, `last`, `s_view` and `view` similar to [`search`](./StdSearch). - -- `label`: - - 1,5: The default string is "Kokkos::find_end_iterator_api_default". - - 3,7: The default string is "Kokkos::find_end_view_api_default". - -- `pred` - similar to [`equal`](./StdEqual) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindEnd.rst b/docs/source/API/algorithms/std-algorithms/all/StdFindEnd.rst new file mode 100644 index 000000000..600bfc2da --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFindEnd.rst @@ -0,0 +1,180 @@ + +``find_end`` +============ + +Header: ```` + +Description +----------- + +Searches a given range or rank-1 ``View`` for the *last* occurrence +of a target sequence or ``View`` of values. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + IteratorType1 find_end(const ExecutionSpace& exespace, (1) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + IteratorType1 find_end(const std::string& label, const ExecutionSpace& exespace, + IteratorType1 first, IteratorType1 last, (2) + IteratorType2 s_first, IteratorType2 s_last); + + template + auto find_end(const ExecutionSpace& exespace, + const ::Kokkos::View& view, (3) + const ::Kokkos::View& s_view); + + template + auto find_end(const std::string& label, const ExecutionSpace& exespace, + const ::Kokkos::View& view, (4) + const ::Kokkos::View& s_view); + + template + IteratorType1 find_end(const ExecutionSpace& exespace, (5) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + IteratorType1 find_end(const std::string& label, const ExecutionSpace& exespace, (6) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + auto find_end(const ExecutionSpace& exespace, (7) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + + template + auto find_end(const std::string& label, const ExecutionSpace& exespace, (8) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + IteratorType1 find_end(const TeamHandleType& teamHandle, (9) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + KOKKOS_FUNCTION + auto find_end(const TeamHandleType& teamHandle, (10) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view); + + template + KOKKOS_FUNCTION + IteratorType1 find_end(const TeamHandleType& teamHandle, (11) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + KOKKOS_FUNCTION + auto find_end(const TeamHandleType& teamHandle, (12) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + +Overload Set Detailed Description +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 1,2,5,6: searches for the last occurrence of the sequence ``[s_first, s_last)`` + in the range ``[first, last)`` comparing elements via ``operator ==`` (1,2) or via ``pred`` (5,6) + +- 3,4,7,8: searches for the last occurrence of the ``s_view`` in ``view`` + comparing elements via ``operator ==`` (3,4 or via ``pred`` (7,8) + +Parameters and Requirements +--------------------------- + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1,5: The default string is "Kokkos::find_end_iterator_api_default". + + - 3,7: The default string is "Kokkos::find_end_view_api_default". + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to search in + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last >= first`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``s_first, s_last``: range of elements that you want to search for + + - same requirements as ``first, last`` + +- ``view``, ``s_view``: views to search in and for, respectively + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``pred``: *binary* functor returning ``true`` if two arguments should be considered "equal". + + ``pred(a,b)`` must be valid to be called from the execution space passed, or + the execution space associated with the team handle, and convertible to bool + for every pair of arguments ``a,b`` of type ``ValueType1`` and ``ValueType2``, + respectively, where ``ValueType1`` and ``ValueType{1,2}`` are the value types of + ``IteratorType{1,2}`` or ``(s_)view``, and must not modify ``a,b``. + + - must conform to: + + .. code-block:: cpp + + template + struct IsEqualFunctor { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType1& a, const ValueType2& b) const { + return (a == b); + } + }; + + +Return Value +~~~~~~~~~~~~ + +Iterator to the beginning of the last occurrence of the sequence ``[s_first, s_last)`` +in range ``[first, last)``, or the last occurence of ``s_view`` in ``view``. + +If ``[s_first, s_last)`` or ``[first, last)`` is empty, ``last`` is returned. + +If ``view`` or ``s_view`` is empty, ``Kokkos::Experimental::end(view)`` is returned. diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindFirstOf.md b/docs/source/API/algorithms/std-algorithms/all/StdFindFirstOf.md deleted file mode 100644 index aca2debd7..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdFindFirstOf.md +++ /dev/null @@ -1,81 +0,0 @@ - -# `find_first_of` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -IteratorType1 find_first_of(const ExecutionSpace& exespace, IteratorType1 first, - IteratorType1 last, IteratorType2 s_first, (1) - IteratorType2 s_last); - -template -IteratorType1 find_first_of(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first, IteratorType1 last, (2) - IteratorType2 s_first, IteratorType2 s_last); - -template -auto find_first_of(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (3) - const ::Kokkos::View& s_view); - -template -auto find_first_of(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (4) - const ::Kokkos::View& s_view); - -// overload set 2: binary predicate passed -template -IteratorType1 find_first_of(const ExecutionSpace& exespace, IteratorType1 first, - IteratorType1 last, IteratorType2 s_first, (5) - IteratorType2 s_last, - const BinaryPredicateType& pred); - -template -IteratorType1 find_first_of(const std::string& label, const ExecutionSpace& exespace, - IteratorType1 first, IteratorType1 last, (6) - IteratorType2 s_first, IteratorType2 s_last, - const BinaryPredicateType& pred); - -template -auto find_first_of(const ExecutionSpace& exespace, - const ::Kokkos::View& view, (7) - const ::Kokkos::View& s_view, - const BinaryPredicateType& pred); - -template -auto find_first_of(const std::string& label, const ExecutionSpace& exespace, - const ::Kokkos::View& view, (8) - const ::Kokkos::View& s_view, - const BinaryPredicateType& pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -- 1,2,5,6: searches the range `[first, last)` for any of the elements in the range `[s_first, s_last)` -comparing elements via `operator ==` (1,2) or via `pred` (5,6) - -- 3,4,7,8: searches `view` for any of the elements in `s_view` -comparing elements via `operator ==` (3,4) or via `pred` (7,8) - -## Parameters and Requirements - -- `exespace`, `first`, `last`, `view` and `count` similar to [`for_each_n`](./StdForEachN). - -- `label`: - - 1,5: The default string is "Kokkos::find_first_of_iterator_api_default". - - 3,7: The default string is ""Kokkos::find_first_of_view_api_default". - -- `pred` - similar to [`equal`](./StdEqual) diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindFirstOf.rst b/docs/source/API/algorithms/std-algorithms/all/StdFindFirstOf.rst new file mode 100644 index 000000000..0ef188f3e --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFindFirstOf.rst @@ -0,0 +1,171 @@ + +``find_first_of`` +================= + +Header: ```` + +Description +----------- + +Searches a range or a ``View`` for any of the elements in a target range or ``View``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + IteratorType1 find_first_of(const ExecutionSpace& exespace, (1) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + IteratorType1 find_first_of(const std::string& label, const ExecutionSpace& exespace, (2) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + auto find_first_of(const ExecutionSpace& exespace, (3) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view); + + template + auto find_first_of(const std::string& label, const ExecutionSpace& exespace, (4) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view); + + // overload set 2: binary predicate passed + template + IteratorType1 find_first_of(const ExecutionSpace& exespace, (5) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + IteratorType1 find_first_of(const std::string& label, const ExecutionSpace& exespace, (6) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + auto find_first_of(const ExecutionSpace& exespace, (7) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + + template + auto find_first_of(const std::string& label, const ExecutionSpace& exespace, (8) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + IteratorType1 find_first_of(const TeamHandleType& teamHandle, (9) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last); + + template + KOKKOS_FUNCTION + auto find_first_of(const TeamHandleType& teamHandle, (10) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view); + + // overload set 2: binary predicate passed + template + KOKKOS_FUNCTION + IteratorType1 find_first_of(const TeamHandleType& teamHandle, (11) + IteratorType1 first, IteratorType1 last, + IteratorType2 s_first, IteratorType2 s_last, + const BinaryPredicateType& pred); + + template + KOKKOS_FUNCTION + auto find_first_of(const TeamHandleType& teamHandle, (12) + const ::Kokkos::View& view, + const ::Kokkos::View& s_view, + const BinaryPredicateType& pred); + +Detailed Description +~~~~~~~~~~~~~~~~~~~~ + +- 1,2,5,6,9,10: searches the range ``[first, last)`` for any of the elements + in the range ``[s_first, s_last)`` comparing elements + via ``operator ==`` or via ``pred`` + +- 3,4,7,8,11,12: searches ``view`` for any of the elements in ``s_view`` + comparing elements via ``operator ==`` or via ``pred`` + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - 1,5: The default string is "Kokkos::find_first_of_iterator_api_default". + + - 3,7: The default string is ""Kokkos::find_first_of_view_api_default". + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to search in + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last >= first`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``s_first, s_last``: range of elements that you want to search for + + - same requirements as ``first, last`` + +- ``view``, ``s_view``: views to search in and for, respectively + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``pred``: *binary* functor returning ``true`` if two arguments should be considered "equal". + + ``pred(a,b)`` must be valid to be called from the execution space passed, or + the execution space associated with the team handle, and convertible to bool + for every pair of arguments ``a,b`` of type ``ValueType1`` and ``ValueType2``, + respectively, where ``ValueType1`` and ``ValueType{1,2}`` are the value types of + ``IteratorType{1,2}`` or ``(s_)view``, and must not modify ``a,b``. + + - must conform to: + + .. code-block:: cpp + + template + struct IsEqualFunctor { + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType1& a, const ValueType2& b) const { + return (a == b); + } + }; diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindIf.md b/docs/source/API/algorithms/std-algorithms/all/StdFindIf.md deleted file mode 100644 index d02c574b8..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdFindIf.md +++ /dev/null @@ -1,99 +0,0 @@ - -# `find_if` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -InputIterator find_if(const ExecutionSpace& exespace, (1) - InputIterator first, InputIterator last, - PredicateType pred); - -template -InputIterator find_if(const std::string& label, const ExecutionSpace& exespace, (2) - InputIterator first, InputIterator last, - PredicateType pred); - -template -auto find_if(const ExecutionSpace& exespace, - const Kokkos::View& view, (3) - PredicateType pred); - -template -auto find_if(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view, (4) - PredicateType pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Returns an iterator to the *first* element in `[first, last)` (1,2) or `view` (3,4) -for which the predicate returns `true`. - -## Parameters and Requirements - -- `exespace`, `first, last`, `view`: same as in [`find`](./StdFind) - -- `label`: - - for 1, the default string is: "Kokkos::find_if_iterator_api_default" - - for 3, the default string is: "Kokkos::find_if_view_api_default" - -- `pred`: - - unary predicate which returns `true` for the required element; `pred(v)` must be valid to be called from the execution space passed, and convertible to bool for every - argument `v` of type (possible const) `value_type`, where `value_type` is the value type of `InputIterator`, and must not modify `v`. - - must conform to: - ```cpp - struct Predicate - { - KOKKOS_INLINE_FUNCTION - bool operator()(const /*type needed */ & operand) const { return /* ... */; } - - // or, also valid - - KOKKOS_INLINE_FUNCTION - bool operator()(/*type needed */ operand) const { return /* ... */; } - }; - ``` - -## Return - -- (1,2): `InputIterator` instance pointing to the first element where the predicate is evaluated to true, or `last` if no such element is found -- (3,4): iterator to the first element where the predicate is evaluated to `true`, -or `Kokkos::Experimental::end(view)` if no such element is found - -## Example - -```cpp -namespace KE = Kokkos::Experimental; - -template -struct EqualsValue -{ - const ValueType m_value; - EqualsValFunctor(ValueType value) : m_value(value){} - - KOKKOS_INLINE_FUNCTION - bool operator()(const ValueType & operand) const { - return operand == m_value; - } -}; - -auto exespace = Kokkos::DefaultExecutionSpace; -using view_type = Kokkos::View; -view_type a("a", 15); -// fill "a" somehow - -// create predicate -EqualsValue p(5); - -auto it1 = KE::find_if(exespace, KE::begin(a), KE::end(a), p); - -// assuming OpenMP is enabled, then you can also explicitly call -auto it2 = KE::find_if(Kokkos::OpenMP(), KE::begin(a), KE::end(a), p); -``` diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindIf.rst b/docs/source/API/algorithms/std-algorithms/all/StdFindIf.rst new file mode 100644 index 000000000..d636d6ced --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFindIf.rst @@ -0,0 +1,152 @@ + +``find_if`` +=========== + +Header: ```` + +Description +----------- + +Returns an iterator to the *first* element in a range or a ``View`` that satisfies a custom predicate. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + InputIterator find_if(const ExecutionSpace& exespace, (1) + InputIterator first, InputIterator last, + PredicateType pred); + + template + InputIterator find_if(const std::string& label, const ExecutionSpace& exespace, (2) + InputIterator first, InputIterator last, + PredicateType pred); + + template + auto find_if(const ExecutionSpace& exespace, + const Kokkos::View& view, (3) + PredicateType pred); + + template + auto find_if(const std::string& label, const ExecutionSpace& exespace, + const Kokkos::View& view, (4) + PredicateType pred); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + InputIterator find_if(const TeamHandleType& teamHandle, (5) + InputIterator first, InputIterator last, + PredicateType pred); + + template + KOKKOS_FUNCTION + auto find_if(const TeamHandleType& teamHandle, + const Kokkos::View& view, (6) + PredicateType pred); + + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - for 1, the default string is: "Kokkos::find_if_iterator_api_default" + + - for 3, the default string is: "Kokkos::find_if_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to search in + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last >= first`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view``: view to search in + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``pred``: unary predicate which returns ``true`` for the required element; + + ``pred(a)`` must be valid to be called from the execution space passed, or + the execution space associated with the team handle, and convertible to bool for every + argument ``a`` of type (possible const) ``value_type``, where ``value_type`` is the value + type of ``InputIterator`` or ``view``, and must not modify ``a``. + + - must conform to: + + .. code-block:: cpp + + struct Predicate + { + KOKKOS_INLINE_FUNCTION + bool operator()(const /*type needed */ & operand) const { return /* ... */; } + + // or, also valid + + KOKKOS_INLINE_FUNCTION + bool operator()(/*type needed */ operand) const { return /* ... */; } + }; + +Return Value +~~~~~~~~~~~~ + +- (1,2,5): ``InputIterator`` instance pointing to the first element + where the predicate evaluates to true, or ``last`` if no such element is found + +- (3,4,6): iterator to the first element where the predicate evaluates to ``true``, + or ``Kokkos::Experimental::end(view)`` if no such element is found + +Example +------- + +.. code-block:: cpp + + namespace KE = Kokkos::Experimental; + + template + struct EqualsValue + { + const ValueType m_value; + EqualsValFunctor(ValueType value) : m_value(value){} + + KOKKOS_INLINE_FUNCTION + bool operator()(const ValueType & operand) const { + return operand == m_value; + } + }; + + auto exespace = Kokkos::DefaultExecutionSpace; + using view_type = Kokkos::View; + view_type a("a", 15); + // fill "a" somehow + + // create predicate + EqualsValue p(5); + + auto it1 = KE::find_if(exespace, KE::begin(a), KE::end(a), p); + + // assuming OpenMP is enabled, then you can also explicitly call + auto it2 = KE::find_if(Kokkos::OpenMP(), KE::begin(a), KE::end(a), p); diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindIfNot.md b/docs/source/API/algorithms/std-algorithms/all/StdFindIfNot.md deleted file mode 100644 index c88ed4fc2..000000000 --- a/docs/source/API/algorithms/std-algorithms/all/StdFindIfNot.md +++ /dev/null @@ -1,45 +0,0 @@ - -# `find_if_not` - -Header File: `Kokkos_StdAlgorithms.hpp` - -```cpp -namespace Kokkos{ -namespace Experimental{ - -template -InputIterator find_if_not(const ExecutionSpace& exespace, (1) - InputIterator first, InputIterator last, - PredicateType pred); - -template -InputIterator find_if_not(const std::string& label, const ExecutionSpace& exespace, (2) - InputIterator first, InputIterator last, - PredicateType pred); - -template -auto find_if_not(const ExecutionSpace& exespace, - const Kokkos::View& view, (3) - PredicateType pred); - -template -auto find_if_not(const std::string& label, const ExecutionSpace& exespace, - const Kokkos::View& view, (4) - PredicateType pred); - -} //end namespace Experimental -} //end namespace Kokkos -``` - -## Description - -Returns an iterator to the *first* element in `[first, last)` (1,2) or `view` (3,4) -for which the predicate returns `false`. - -## Parameters and Requirements - -- `exespace`, `first, last`, `view`, `pred`: same as in [`find_if`](./StdFindIf) - -- `label`: - - for 1, the default string is: "Kokkos::find_if_not_iterator_api_default" - - for 3, the default string is: "Kokkos::find_if_not_view_api_default" diff --git a/docs/source/API/algorithms/std-algorithms/all/StdFindIfNot.rst b/docs/source/API/algorithms/std-algorithms/all/StdFindIfNot.rst new file mode 100644 index 000000000..6d7a049b7 --- /dev/null +++ b/docs/source/API/algorithms/std-algorithms/all/StdFindIfNot.rst @@ -0,0 +1,121 @@ + +``find_if_not`` +=============== + +Header: ```` + +Description +----------- + +Returns an iterator to the *first* element in a range or a View for +which a custom predicate returns ``false``. + +Interface +--------- + +.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace. + +Overload set accepting execution space +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: cpp + + template + InputIterator find_if_not(const ExecutionSpace& exespace, (1) + InputIterator first, InputIterator last, + PredicateType pred); + + template + InputIterator find_if_not(const std::string& label, const ExecutionSpace& exespace, (2) + InputIterator first, InputIterator last, + PredicateType pred); + + template + auto find_if_not(const ExecutionSpace& exespace, (3) + const Kokkos::View& view, + PredicateType pred); + + template + auto find_if_not(const std::string& label, const ExecutionSpace& exespace, (4) + const Kokkos::View& view, + PredicateType pred); + +Overload set accepting a team handle +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 4.2 + +.. code-block:: cpp + + template + KOKKOS_FUNCTION + InputIterator find_if_not(const TeamHandleType& teamHandle, (5) + InputIterator first, InputIterator last, + PredicateType pred); + + template + KOKKOS_FUNCTION + auto find_if_not(const TeamHandleType& teamHandle, (6) + const Kokkos::View& view, + PredicateType pred); + +Parameters and Requirements +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- ``exespace``: execution space instance + +- ``teamHandle``: team handle instance given inside a parallel region when using a TeamPolicy + +- ``label``: string forwarded to internal parallel kernels for debugging purposes + + - for 1, the default string is: "Kokkos::find_if_not_iterator_api_default" + + - for 3, the default string is: "Kokkos::find_if_not_view_api_default" + + - NOTE: overloads accepting a team handle do not use a label internally + +- ``first, last``: range of elements to search in + + - must be *random access iterators*, e.g., returned from ``Kokkos::Experimental::(c)begin/(c)end`` + + - must represent a valid range, i.e., ``last >= first`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``view``: view to search in + + - must be rank-1, and have ``LayoutLeft``, ``LayoutRight``, or ``LayoutStride`` + + - must be accessible from ``exespace`` or from the execution space associated with the team handle + +- ``pred``: unary predicate which returns ``false`` for the required element; + + ``pred(a)`` must be valid to be called from the execution space passed, or + the execution space associated with the team handle, and convertible to bool for every + argument ``a`` of type (possible const) ``value_type``, where ``value_type`` is the value + type of ``InputIterator`` or ``view``, and must not modify ``a``. + + - must conform to: + + .. code-block:: cpp + + struct Predicate + { + KOKKOS_INLINE_FUNCTION + bool operator()(const /*type needed */ & operand) const { return /* ... */; } + + // or, also valid + + KOKKOS_INLINE_FUNCTION + bool operator()(/*type needed */ operand) const { return /* ... */; } + }; + + +Return Value +~~~~~~~~~~~~ + +- (1,2,5): ``InputIterator`` instance pointing to the first element + where the predicate evaluates to ``false``, or ``last`` if no such element is found + +- (3,4,6): iterator to the first element where the predicate evaluates to ``false``, + or ``Kokkos::Experimental::end(view)`` if no such element is found