std::ranges::iota, std::ranges::iota_result
From cppreference.com
| 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 ranges::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 ranges::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 target range [first, last) or r with sequentially increasing values, starting with value and repetitively evaluating ++value.
Equivalent operation (assuming ++value returns the incremented value):
*(first) = value;
*(first + 1) = ++value;
*(first + 2) = ++value;
*(first + 3) = ++value;
// repeats until “last” is reached
Parameters
| first, last | - | the iterator-sentinel pair defining the target range |
| value | - | initial value to fill |
Return value
A ranges::iota_result object where:
- The data member out holds the past-the-end iterator of the target range.
- The data member value holds the result of
valuebeing incrementedranges::distance(first, last)orranges::distance(r)times.
Complexity
Given N as ranges::distance(first, last) or ranges::distance(r):
1,2) Exactly N increments and assignments.
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
|
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<ranges::range R>
constexpr auto get_end(R&& r)
{
return ranges::end(r);
}
template<ranges::forward_range R>
constexpr auto get_end(R&& r)
{
return ranges::next(ranges::begin(r), ranges::end(r));
}
template<std::weakly_incrementable T, ranges::output_range<const T&> R>
constexpr iota_result<ranges::borrowed_iterator_t<R>, T>
operator()(R&& r, T value) const
{
return (*this)(ranges::begin(r), get_end(r), std::move(value));
}
};
inline constexpr iota_fn 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 <list>
#include <numeric>
#include <print>
#include <random>
#include <ranges>
#include <vector>
int main()
{
std::list<int> list(8);
// Fill the list with ascending values: 0, 1, 2, ..., 7
std::ranges::iota(list, 0);
std::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 {}()});
std::println("List viewed via vector: {}", vec |
std::views::transform([](auto it) { return *it; }));
}
Possible output:
List: [0, 1, 2, 3, 4, 5, 6, 7]
List viewed via vector: [6, 7, 5, 3, 1, 0, 2, 4]
See also
(C++11) |
fills a range with successive increments of the starting value (function template) |
| copy-assigns the given value to every element in a range (function template & algorithm function object) | |
(C++20) |
|
| assigns the results of successive function calls to every element in a range (function template & algorithm function object) | |
(C++20) |
|
(C++20) |
a view consisting of a sequence generated by repeatedly incrementing an initial value (class template) (customization point object) |
(C++26) |
a view that generates a sequence of increasing values from 0 up to n(customization point object) |