cpp / latest / algorithm / ranges / iota.html /

std::ranges::iota, std::ranges::iota_result

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&>
constexpr iota_result<O, T> iota( O first, S last, T value );
(1) (since C++23)
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 );
(2) (since C++23)
Helper types
template< class O, class T >
  using iota_result = ranges::out_value_result<O, T>;
(3) (since C++23)

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 testing macro: __cpp_lib_ranges_iota.

Example

The following example applies ranges::shuffle to a vector of std::lists' iterators since ranges::shuffle cannot be applied to a std::list directly. ranges::iota is used to populate both containers.

#include <algorithm>
#include <iostream>
#include <list>
#include <numeric>
#include <random>
#include <vector>
 
int main()
{
    std::list<int> l(10);
    std::ranges::iota(l.begin(), l.end(), -4);
 
    std::vector<std::list<int>::iterator> v(l.size());
    std::ranges::iota(v, l.begin());
 
    std::ranges::shuffle(v, std::mt19937{std::random_device{}()});
 
    std::cout << "Contents of the list: ";
    for(auto n: l) std::cout << n << ' ';
    std::cout << '\n';
 
    std::cout << "Contents of the list, shuffled: ";
    for(auto i: v) std::cout << *i << ' ';
    std::cout << '\n';
}

Possible output:

Contents of the list: -4 -3 -2 -1 0 1 2 3 4 5
Contents of the list, shuffled: 0 -1 3 4 -4 1 -2 -3 2 5

See also

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

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/algorithm/ranges/iota