std::ranges::iota,std::ranges::iota_result(3)

NAME
std::ranges::iota,std::ranges::iota_result - std::ranges::iota,std::ranges::iota_result

Synopsis
   Defined in header <numeric>
   Call signature
   template< std::input_or_output_iterator O, std::sentinel_for<O> S,
             std::weakly_incrementable T >
   requires std::indirectly_writable<O, const T&> (1) (since C++23)
   constexpr iota_result<O, T>
       iota( O first, S last, T value );
   template< std::weakly_incrementable T, ranges::output_range<const
   T&> R >
                        (2) (since C++23)
   constexpr iota_result<ranges::borrowed_iterator_t<R>, T>
       iota( R&& r, T value );

Helper types
   template< class O, class T > (3) (since C++23)
   using iota_result = ranges::out_value_result<O, T>;
   Fills the range [first, last) with sequentially increasing values, starting with
   value and repetitively evaluating ++value.
   Equivalent operation:
 *(first) = value;
 *(first + 1) = ++value;
 *(first + 2) = ++value;
 *(first + 3) = ++value;
 ...

Parameters
   first, last - the range of elements to fill with sequentially increasing values
                 starting with value
   value - initial value to store; the expression ++value must be well-formed

Return value
   {last, value + ranges::distance(first, last)}

Complexity
   Exactly last - first increments and assignments.

Possible implementation
   struct iota_fn
   {
       template<std::input_or_output_iterator O, std::sentinel_for<O> S,
               std::weakly_incrementable T>
       requires std::indirectly_writable<O, const T&>
       constexpr iota_result<O, T> operator()(O first, S last, T value) const
       {
           while (first != last)
           {
               *first = as_const(value);
               ++first;
               ++value;
           }
           return {std::move(first), std::move(value)};
       }
       template<std::weakly_incrementable T, std::ranges::output_range<const T&> R>
       constexpr iota_result<std::ranges::borrowed_iterator_t<R>, T>
       operator()(R&& r, T value) const
       {
           return (*this)(std::ranges::begin(r), std::ranges::end(r), std::move(value));
       }
   };
   inline constexpr iota_fn iota;

Notes
   The function is named after the integer function ⍳ from the programming language
   APL.
    Feature-test macro Value Std Feature
   __cpp_lib_ranges_iota 202202L (C++23) std::ranges::iota

Example
   Uses the vector of iterators (std::vector<std::list<T>::iterator>) as a proxy to
   shuffle the elements of the std::list, because ranges::shuffle cannot be applied to
   the std::list directly. // Run this code
 #include <algorithm>
 #include <functional>
 #include <iostream>
 #include <list>
 #include <numeric>
 #include <random>
 #include <vector>
 template <typename Proj = std::identity>
 void println(auto comment, std::ranges::input_range auto&& range, Proj proj = {})
 {
     for (std::cout << comment; auto const &element : range)
         std::cout << proj(element) << ' ';
     std::cout << '\n';
 }
 int main()
 {
     std::list<int> list(8);
     // Fill the list with ascending values: 0, 1, 2, ..., 7
     std::ranges::iota(list, 0);
     println("List: ", list);
     // A vector of iterators (see the comment to Example)
     std::vector<std::list<int>::iterator> vec(list.size());
     // Fill with iterators to consecutive list's elements
     std::ranges::iota(vec.begin(), vec.end(), list.begin());
     std::ranges::shuffle(vec, std::mt19937 {std::random_device {}()});
     println("List viewed via vector: ", vec, [](auto it) { return *it; });
 }

Possible output:
 List: 0 1 2 3 4 5 6 7
 List viewed via vector: 5 7 6 0 1 3 4 2

See also
   fill copy-assigns the given value to every element in a range
                     (function template)
   ranges::fill assigns a range of elements a certain value
   (C++20) (niebloid)
                     assigns the results of successive function calls to every element
   generate in a range
                     (function template)
   ranges::generate saves the result of a function in a range
   (C++20) (niebloid)
   ranges::iota_view a view consisting of a sequence generated by repeatedly
   views::iota incrementing an initial value
   (C++20) (class template) (customization point object)
   iota fills a range with successive increments of the starting value
   (C++11) (function template)