# std::iota

> C++ Atlas: `cppatlas.com/w/cpp/algorithm/iota` | Source: https://en.cppreference.com/w/cpp/algorithm/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>

template< class ForwardIt, class T >
void iota( ForwardIt first, ForwardIt last, T value ); // (since C++11) (constexpr since C++20)
```

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

Equivalent operation (assuming `++value` returns the incremented value):

```cpp
*first   = value;
*++first = ++value;
*++first = ++value;
*++first = ++value;
// repeats until “last” is reached
```

If any of the following conditions is satisfied, the program is ill-formed:

- `T` is not convertible to the value type of `ForwardIt`.
- The expression `++val` is ill-formed, where `val` is a variable of type `T`.

### Parameters

- `first, last` - the range of elements to fill with sequentially increasing values starting with `value`
- `value` - initial value to store

### Complexity

Exactly `std::distance(first, last)` increments and assignments.

### Possible implementation

```cpp
template<class ForwardIt, class T>
constexpr // since C++20
void iota(ForwardIt first, ForwardIt last, T value)
{
    for (; first != last; ++first, ++value)
        *first = value;
}
```

### 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.

### Example

The following example applies `std::shuffle` to a `vector` of `std::list`s' iterators. `std::iota` is used to populate containers.

```cpp
#include <algorithm>
#include <iomanip>
#include <iostream>
#include <list>
#include <numeric>
#include <random>
#include <vector>

class BigData // inefficient to copy
{
    int data[1024]; /* some raw data */
public:
    explicit BigData(int i = 0) { data[0] = i; /* ... */ }
    operator int() const { return data[0]; }
    BigData& operator=(int i) { data[0] = i; return *this; }
    /* ... */
};

int main()
{
    std::list<BigData> l(10);
    std::iota(l.begin(), l.end(), -4);

    std::vector<std::list<BigData>::iterator> v(l.size());
    std::iota(v.begin(), v.end(), l.begin());
    // Vector of iterators (to original data) is used to avoid expensive copying,
    // and because std::shuffle (below) cannot be applied to a std::list directly.

    std::shuffle(v.begin(), v.end(), std::mt19937{std::random_device{}()});

    std::cout << "Original contents of the list l:\t";
    for (const auto& n : l)
        std::cout << std::setw(2) << n << ' ';
    std::cout << '\n';

    std::cout << "Contents of l, viewed via shuffled v:\t";
    for (const auto i : v)
        std::cout << std::setw(2) << *i << ' ';
    std::cout << '\n';
}
```

Possible output:

```text
Original contents of the list l:	-4 -3 -2 -1  0  1  2  3  4  5
Contents of l, viewed via shuffled v:	-1  5 -4  0  2  1  4 -2  3 -3
```

### See also

- [`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)
- [`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`](https://en.cppreference.com/w/cpp/algorithm/ranges/iota) (C++23): fills a range with successive increments of the starting value (algorithm function object)

---
Attribution: content from https://en.cppreference.com/w/cpp/algorithm/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.