std::ranges...s::iota_view(3)

🦋 std::ranges::views::iota, std::ranges::iota_view — C++ Standard Libary 🦋

okay bestie, this is the manual page for std::ranges...s::iota_view(3) from the C++ Standard Libary, and it is genuinely iconic. it’s giving “make me a range by just… incrementing forever,” and honestly? slay.

💖 NAME 💖

std::ranges::views::iota, std::ranges::iota_view — the range factory duo that keeps on incrementing, no cap.

✨ Synopsis ✨

Defined in header <ranges> 🫶

template< std::weakly_incrementable W,
          std::semiregular Bound = std::unreachable_sentinel_t >
    requires __WeaklyEqualityComparableWith<W, Bound> &&
             std::copyable<W>
class iota_view
    : public ranges::view_interface<iota_view<W, Bound>>

That’s (1) — (since C++20) 💅

namespace views {
    inline constexpr /* unspecified */ iota = /* unspecified */;
}

That’s (2) — (since C++20) ✨

📞 Call signature 📞

template< class W >
    requires /* see below */
constexpr /* see below */ iota( W&& value );

(since C++20)

template< class W, class Bound >
    requires /* see below */
constexpr /* see below */ iota( W&& value, Bound&& bound );

(since C++20)

1. A range factory that generates a sequence of elements by repeatedly incrementing an initial value. Can be either bounded or unbounded (infinite). 🔥
2. views::iota(e) and views::iota(e, f) are expression-equivalent to iota_view(e) and iota_view(e, f) respectively for any suitable subexpressions e and f. periodt.

🌸 Member functions 🌸

• constructor (C++20) — creates an iota_view (public member function)
• begin (C++20) — obtains the beginning iterator of an iota_view (public member function)
• end (C++20) — obtains the sentinel denoting the end of an iota_view (public member function)
• empty (C++20) — tests whether the iota_view is empty, i.e. the iterator and the sentinel compare equal (public member function)
• size (C++20) — obtains the size of an iota_view if it is sized (public member function)

💜 Inherited from std::ranges::view_interface 💜

• cbegin (C++23) — returns a constant iterator to the beginning of the range. (public member function of std::ranges::view_interface<D>)
• cend (C++23) — returns a sentinel for the constant iterator of the range. (public member function of std::ranges::view_interface<D>)
• operator bool (C++20) — returns whether the derived view is not empty. Provided if ranges::empty is applicable to it. (public member function of std::ranges::view_interface<D>)
• front (C++20) — returns the first element in the derived view. Provided if it satisfies forward_range. (public member function of std::ranges::view_interface<D>)
• back (C++20) — returns the last element in the derived view. Provided if it satisfies bidirectional_range and common_range. (public member function of std::ranges::view_interface<D>)
• operator[] (C++20) — returns the n^th element in the derived view. Provided if it satisfies random_access_range. (public member function of std::ranges::view_interface<D>)

🧚 std::ranges::iota_view::iota_view 🧚

iota_view() requires std::default_initializable<W> = default;

(1) (since C++20)

constexpr explicit iota_view( W value );

(2) (since C++20)

constexpr explicit iota_view( std::type_identity_t<W> value,
                              std::type_identity_t<Bound> bound );

(3) (since C++20)

constexpr explicit iota_view( /* iterator */ first, /* see below */ last );

(4) (since C++20)

1. Value-initializes value_ and bound_ via their default member initializers (= W() and = Bound()). 🎀
2. Initializes value_ with value and value-initializes bound_. This constructor is used to create unbounded iota_views, e.g. iota(0) yields numbers 0,1,2..., infinitely. 🌀
3. Initializes value_ with value and bound_ with bound. The behavior is undefined if std::totally_ordered_with<W, Bound> is modeled and bool(value <= bound) is false. This constructor is used to create bounded iota views, e.g. iota(10, 20) yields numbers from 10 to 19. 🌈
4. Same as (3), except that value_ is initialized with the W value stored in first, and
   • if W and Bound are the same type, then the type of last is /* iterator */ and bound_ initialized with the W value stored in last,
   • otherwise, if the iota_view is unbounded (i.e. Bound is std::unreachable_sentinel_t), then the type of last is std::unreachable_sentinel_t and bound_ initialized with std::unreachable_sentinel.
   • otherwise, the type of last is /* sentinel */ and bound_ initialized with the Bound value stored in last. In any case, the type of last is same as decltype(end()). 💫

For (2), (3), and (4), the behavior is undefined if the iota_view is bounded (i.e. Bound is not std::unreachable_sentinel_t) and bound_ is initialized to a value unreachable from value_.

⚠️ bestie, that last sentence is real: unreachable bound_ means undefined behavior. do not test it for fun. 😭

🍓 Parameters 🍓

• value — the starting value
• bound — the bound
• first — the iterator denoting the starting value
• last — the iterator or sentinel denoting the bound

🌟 std::ranges::iota_view::begin 🌟

constexpr /* iterator */ begin() const;

(since C++20)

Returns an iterator initialized with value_. 🫶

🌙 std::ranges::iota_view::end 🌙

constexpr auto end() const;

(1) (since C++20)

constexpr /* iterator */ end() const requires std::same_as<W, Bound>;

(2) (since C++20)

1. Returns a sentinel of a specific type (shown as /* sentinel */ here) initialized with bound_ if this view is bounded, or std::unreachable_sentinel if this view is unbounded. ✨
2. Returns an iterator initialized with bound_. 💅

🦋 std::ranges::iota_view::empty 🦋

constexpr bool empty() const;

(since C++20)

Equivalent to return value_ == bound_;. simple, clean, iconic.

👑 std::ranges::iota_view::size 👑

constexpr auto size() const
    requires (std::same_as<W, Bound> && /* advanceable */<W>)
        || (/* is-integer-like */<W> && /* is-integer-like */<Bound>)
        || std::sized_sentinel_for<Bound, W>
{
    if constexpr (/* is-integer-like */<W> && /* is-integer-like */<Bound>)
        return (value_ < 0)
            ? ((bound_ < 0)
                ? /* to-unsigned-like */(-value_)
                    - /* to-unsigned-like */(-bound_)
                : /* to-unsigned-like */(bound_)
                    + /* to-unsigned-like */(-value_))
            : /* to-unsigned-like */(bound_) - /* to-unsigned-like */(value_);
    else
        return /* to-unsigned-like */(bound_ - value_);
}

(since C++20)

Returns the size of the view if the view is bounded. 🔥

The exposition-only concept advanceable is described in this page.

The exposition-only function template to-unsigned-like converts its argument (which must be integer-like) to the corresponding unsigned version of the argument type.

🎀 Deduction guides 🎀

template< class W, class Bound >
    requires (!/* is-integer-like */<W>
        || !/* is-integer-like */<Bound>
        || /* is-signed-integer-like */<W>
            == /* is-signed-integer-like */<Bound>)
  iota_view( W, Bound ) -> iota_view<W, Bound>;

(since C++20)

For any type T, /* is-integer-like */<T> is true if and only if T is integer-like, and /* is-signed-integer-like */<T> is true if and only if T is integer-like and capable of representing negative values.

Note that the guide protects itself against signed/unsigned mismatch bugs, like views::iota(0, v.size()), where 0 is a (signed) int and v.size() is an (unsigned) std::size_t. 💀

🧚 Nested classes 🧚

• iterator (C++20) — the iterator type (exposition-only member class*)
• sentinel (C++20) — the sentinel type used when the iota_view is bounded and Bound and W are not the same type (exposition-only member class*)

💜 Helper templates 💜

template< std::weakly_incrementable W, std::semiregular Bound >
inline constexpr bool enable_borrowed_range<ranges::iota_view<W, Bound>> = true;

(since C++20)

This specialization of std::ranges::enable_borrowed_range makes iota_view satisfy borrowed_range. 🌈

🌸 Example 🌸

// Run this code

#include <algorithm>
#include <iostream>
#include <ranges>

struct Bound
{
    int bound;
    bool operator==(int x) const { return x == bound; }
};

int main()
{
    for (int i : std::ranges::iota_view{1, 10})
        std::cout << i << ' ';
    std::cout << '\n';

    for (int i : std::views::iota(1, 10))
        std::cout << i << ' ';
    std::cout << '\n';

    for (int i : std::views::iota(1, Bound{10}))
        std::cout << i << ' ';
    std::cout << '\n';

    for (int i : std::views::iota(1) | std::views::take(9))
        std::cout << i << ' ';
    std::cout << '\n';

    std::ranges::for_each(std::views::iota(1, 10), [](int i)
    {
        std::cout << i << ' ';
    });
    std::cout << '\n';
}

⭐ Output ⭐

1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9
1 2 3 4 5 6 7 8 9

💅 Defect reports 💅

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 3523 — Applied to: C++20. Behavior as published: iterator-sentinel pair constructor might use wrong sentinel type. Correct behavior: corrected.
• LWG 3610 — Applied to: C++20. Behavior as published: size might reject integer-class types. Correct behavior: accept if possible.
• LWG 4001 — Applied to: C++20. Behavior as published: the inherited member empty function was not always valid. Correct behavior: empty is always provided.
• P2325R3 — Applied to: C++20. Behavior as published: iota_view required that W is semiregular as view required default_initializable. Correct behavior: only requires that W is copyable.
• P2711R1 — Applied to: C++20. Behavior as published: the multi-parameter constructors were not explicit. Correct behavior: made explicit.

👀 See also 👀

okay bestie, here's the little “go look at these too” corner — lowkey useful, ngl:

• iota — fills a range with successive increments of the starting value · (C++11) · (function template)
• ranges::iota — fills a range with successive increments of the starting value · (C++23) · (niebloid)
• ranges::repeat_view — a view consisting of a generated sequence by repeatedly producing the same value · (C++23) · (class template)
• views::repeat — same “a view consisting of a generated sequence by repeatedly producing the same value” energy · (C++23) · (customization point object)

---

that’s the whole see-also situation, bestie 🫶 source/version + date: http://cppreference.com · 2024.06.10 · page: std::ranges...s::iota_view(3) 💖