std::ranges...iota_result(3)

💖 NAME 💖

okay bestie, welcome to the std::ranges...iota_result(3) page from the C++ Standard Libary manual. The main characters are std::ranges::iota and std::ranges::iota_result.

The original NAME line is literally: std::ranges::iota,std::ranges::iota_result - std::ranges::iota,std::ranges::iota_result 💅

---

🌸 Synopsis 🌸

Defined in header <numeric> — periodt.

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&>
(1) (since C++23)
constexpr iota_result<O, T>
    iota( O first, S last, T value );

template< std::weakly_incrementable T, ranges::output_range<const T&> R >
(2) (since C++23)
constexpr iota_result<ranges::borrowed_iterator_t<R>, T>
    iota( R&& r, T value );

Helper types:

template< class O, class T >
(3) (since C++23)
using iota_result = ranges::out_value_result<O, T>;

So what does this iconic thing do? It fills the range [first, last) with sequentially increasing values, starting with value and then repeatedly evaluating ++value 🔥

Equivalent operation, no cap:

*(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 ✨

It returns:

{last, value + ranges::distance(first, last)}

That's the whole return vibe. 🫶

---

🎀 Complexity 🎀

Exactly last - first increments and assignments. Not extra, not less — exactly that. 💅

---

🧚 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. That's the lore, bestie. 🌀

Feature-test macro moment:

• __cpp_lib_ranges_iota — value 202202L, std (C++23), feature 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. Big brain energy, fr fr 🧠✨

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

---

source: http://cppreference.com 💖 version/date: 2024.06.10 💖 page: std::ranges...iota_result(3) — bye bestie, go fill some ranges with sequentially increasing values, slay 🌸💅