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

> C++ Atlas: `cppatlas.com/w/cpp/algorithm/ranges/iota` | Source: https://en.cppreference.com/w/cpp/algorithm/ranges/iota | Domain: Algorithms | Standards: C++11, C++20, C++23

Fills the range [first, last) with sequentially increasing values, starting with value and repetitively evaluating ++value.

## Official Specification Summary (cppreference)

```cpp
// 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:

```cpp
*(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

```cpp
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.

```cpp
#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:

```text
List: 0 1 2 3 4 5 6 7
List viewed via vector: 5 7 6 0 1 3 4 2
```

### See also

- [`fill`](https://en.cppreference.com/w/cpp/algorithm/fill): copy-assigns the given value to every element in a range (function template)
- [`ranges::fill`](https://en.cppreference.com/w/cpp/algorithm/ranges/fill) (C++20): assigns a range of elements a certain value (algorithm function object)
- [`generate`](https://en.cppreference.com/w/cpp/algorithm/generate): assigns the results of successive function calls to every element in a range (function template)
- [`ranges::generate`](https://en.cppreference.com/w/cpp/algorithm/ranges/generate) (C++20): saves the result of a function in a range (algorithm function object)
- [`ranges::iota_view`](https://en.cppreference.com/w/cpp/ranges/iota_view) (C++20), [`views::iota`](https://en.cppreference.com/w/cpp/ranges/iota_view): a `view` consisting of a sequence generated by repeatedly incrementing an initial value (class template) (customization point object)
- [`iota`](https://en.cppreference.com/w/cpp/algorithm/iota) (C++11): fills a range with successive increments of the starting value (function template)

---
Attribution: content from https://en.cppreference.com/w/cpp/algorithm/ranges/iota (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.