``generate_n``
==============

Header: ``<Kokkos_StdAlgorithms.hpp>``

Description
-----------

Assigns the value generated by the functor ``g`` in a range of ``count`` iterators
or each of the first ``count`` elements in a rank-1 ``View``.

Interface
---------

.. warning:: This is currently inside the ``Kokkos::Experimental`` namespace.


Overload set accepting execution space
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: cpp

   template <class ExecutionSpace, class IteratorType, class Size, class Generator>
   IteratorType generate_n(const ExecutionSpace& exespace,                           (1)
                           IteratorType first, Size count,
                           Generator g);

   template <class ExecutionSpace, class IteratorType, class Size, class Generator>
   IteratorType generate_n(const std::string& label, const ExecutionSpace& exespace, (2)
                           IteratorType first, Size count,
                           Generator g);

   template <class ExecutionSpace, class DataType, class... Properties, class Size,
             class Generator>
   auto generate_n(const ExecutionSpace& exespace,                                   (3)
                   const ::Kokkos::View<DataType, Properties...>& view, Size count,
                   Generator g);

   template <class ExecutionSpace, class DataType, class... Properties, class Size,
             class Generator>
   auto generate_n(const std::string& label, const ExecutionSpace& ex,               (4)
                   const ::Kokkos::View<DataType, Properties...>& view, Size count,
                   Generator g);

Overload set accepting a team handle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 4.2

.. code-block:: cpp

   template <class TeamHandleType, class IteratorType, class Size, class Generator>
   KOKKOS_FUNCTION
   IteratorType generate_n(const TeamHandleType& teamHandle,                         (5)
                           IteratorType first, Size count,
                           Generator g);

   template <class TeamHandleType, class DataType, class... Properties, class Size,
             class Generator>
   KOKKOS_FUNCTION
   auto generate_n(const TeamHandleType& teamHandle,                                 (6)
                   const ::Kokkos::View<DataType, Properties...>& view, Size count,
                   Generator g);

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::generate_n_iterator_api_default"

  - for 3, the default string is: "Kokkos::generate_n_view_api_default"

  - NOTE: overloads accepting a team handle do not use a label internally

- ``count``: number of elements to assign (must be non-negative)

- ``first``: iterator defining the beginning of range

  - must be *random access iterator*

  - ``[first, first+count)`` must represent a valid range

  - must be accessible from ``exespace`` or from the execution space associated with the team handle

- ``view``:

  - 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

- ``g``: function object called on the all the elements

  - functor of the following form, where ``return_type`` must be assignable to
    ``value_type``, with ``value_type`` being the value type of ``IteratorType``
    (for 1,2,5) or of ``view`` (for 3,4,6)

  - must conform to:

  .. code-block:: cpp

     struct Generate
     {
        KOKKOS_INLINE_FUNCTION
        return_type operator()() const{ return /* ... */; }
     };

Return Value
~~~~~~~~~~~~

- 1,2,5: an iterator equal to ``first + count``

- 3,4,6: an iterator equal to ``Kokkos::Experimental::begin(view) + count``