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

From cppreference.com
< cpp‎ | algorithm‎ | ranges

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-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 (C++20) | assigns a range of elements a certain value (algorithm function object)
generate | assigns the results of successive function calls to every element in a range (function template)
ranges::generate (C++20) | saves the result of a function in a range (algorithm function object)
ranges::iota_viewviews::iota (C++20) | a `view` consisting of a sequence generated by repeatedly incrementing an initial value (class template) (customization point object)
iota (C++11) | fills a range with successive increments of the starting value (function template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/algorithm/ranges/iota&oldid=171204"