std::ranges::iota() algorithm

since C++20

Simplified

// (1)
constexpr iota_result<O, T> iota( O first, S last, T value );

// (2)
constexpr iota_result<ranges::borrowed_iterator_t<R>, T> iota( R&& r, T value );

The type of arguments are generic and have the following constraints:

• I - std::input_or_output_iterator
• S - std::sentinel_for<O>
• R - ranges::output_range<const T&>
• T - std::weakly_incrementable

Additionally, each overload has the following constraints:

• (1) - std::indirectly_writable<O, const T&>

Detailed

// (1)
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> iota( O first, S last, T value );

// (2)
template<std::weakly_incrementable T, ranges::output_range<const T&> R>
constexpr iota_result<ranges::borrowed_iterator_t<R>, T> iota( R&& r, T value );

With the helper types defined as follows:

template< class O, class T >
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;
...

The function-like entities described on this page are niebloids.

Parameters

first second	The range of elements to fill with sequentially increasing values starting from value.
value	Initial value to store.

Return value

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

Complexity

Exactly last - first increments and assignments.

Exceptions

(none)

Possible implementation

iota(1) and iota(2)

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. It was one of the STL components that were not included in C++98, but made it into the standard library in C++11.

Examples

Main.cpp

#include <algorithm>
#include <functional>
#include <iostream>
#include <list>
#include <numeric>
#include <random>
#include <vector>

template <typename Proj = std::identity>
inline void print(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);
    print("Contents of the 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 {}()});
    print("Contents of the list viewed via vector: ", vec, [](auto it) { return *it; });
}

Output

Contents of the list: 0 1 2 3 4 5 6 7
Contents of the list viewed via vector: 5 7 6 0 1 3 4 2