std::generator

From cppreference.com

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros(C++20)
Language support library
Concepts library(C++20)
Diagnostics library
Memory management library
Metaprogramming library(C++11)
General utilities library
Containers library
Iterators library
Ranges library(C++20)
Algorithms library
Strings library
Text processing library
Numerics library
Date and time library
Input/output library
Filesystem library(C++17)
Concurrency support library(C++11)
Execution control library(C++26)
Technical specifications
Symbols index
External libraries

[edit]

Utilities library

Language support

Type support (basic types, RTTI)

Library feature-test macros(C++20)

Program utilities

Variadic functions

initializer_list

(C++11)

is_constant_evaluated

(C++20)

is_within_lifetime

(C++26)

source_location

(C++20)

Coroutine support(C++20)

Contract support(C++26)

Three-way comparison

three_way_comparablethree_way_comparable_with

(C++20)(C++20)

strong_ordering

(C++20)

weak_ordering

(C++20)

partial_ordering

(C++20)

common_comparison_category

(C++20)

compare_three_way_result

(C++20)

(C++20)

(C++20)

(C++20)

(C++20)

compare_strong_order_fallback

(C++20)

compare_weak_order_fallback

(C++20)

compare_partial_order_fallback

(C++20)

is_eqis_ltis_lteq

(C++20)(C++20)(C++20)

is_neqis_gtis_gteq

(C++20)(C++20)(C++20)

General utilities

Function objects
Bit manipulation(C++20)
C-style bit manipulation(C++26)
bitset
hash (C++11)

Relational operators(deprecated in C++20)

rel_ops::operator!=rel_ops::operator>

rel_ops::operator<=rel_ops::operator>=

Integer comparison functions

cmp_equalcmp_lesscmp_less_than

(C++20)(C++20)(C++20)

cmp_not_equalcmp_greatercmp_greater_than

(C++20)(C++20)(C++20)

in_range

(C++20)

Swap andtype operations

swap
ranges::swap (C++20)
exchange (C++14)
declval (C++11)
to_underlying (C++23)

forward (C++11)
forward_like (C++23)
move (C++11)
move_if_noexcept (C++11)
as_const (C++17)

Common vocabulary types

pair
tuple (C++11)
optional (C++17)
any (C++17)
variant (C++17)

tuple_size (C++11)
tuple_element (C++11)
apply (C++17)
make_from_tuple (C++17)
expected (C++23)

[edit]

Coroutine support

Coroutine traits
coroutine_traits (C++20)
Coroutine handle
coroutine_handle (C++20)
No-op coroutines
noop_coroutine_promise (C++20)
noop_coroutine (C++20)
Trivial awaitables
suspend_never (C++20)
suspend_always (C++20)
Range generators
generator (C++23)

[edit]

Ranges library

Range access

begin
cbegin
end
cend

rbegin
crbegin
rend
crend

size
ssize
data
cdata

reserve_hint (C++26)
empty

Range conversions
std::from_range_t std::from_range (C++23)(C++23)
to (C++23)

Dangling iterator handling
dangling
borrowed_iterator_t
borrowed_subrange_t

Range primitives

range_size_trange_difference_trange_value_t
elements_of (C++23)

iterator_tconst_iterator_tsentinel_tconst_sentinel_t

(C++23)(C++23)

range_reference_trange_const_reference_trange_rvalue_reference_trange_common_reference_t

(C++23)

Range concepts

range
borrowed_range
common_range

sized_range
viewable_range
view

input_range
output_range
forward_range

bidirectional_range
random_access_range
contiguous_range

approximately_sized_range (C++26)
constant_range (C++23)

empty_viewviews::empty

single_viewviews::single

basic_istream_viewviews::istream

iota_viewviews::iota

repeat_viewviews::repeat

(C++23)(C++23)

Range adaptors

views::all_tviews::all
as_rvalue_viewviews::as_rvalue (C++23)(C++23)
filter_viewviews::filter
transform_viewviews::transform
take_viewviews::take
take_while_viewviews::take_while
common_viewviews::common
views::counted
to_input_viewviews::to_input (C++26)(C++26)

ref_view
drop_viewviews::drop
drop_while_viewviews::drop_while
lazy_split_viewviews::lazy_split
split_viewviews::split
join_viewviews::join
join_with_viewviews::join_with (C++23)(C++23)
concat_viewviews::concat (C++26)(C++26)
cache_latest_viewviews::cache_latest (C++26)(C++26)

owning_view
reverse_viewviews::reverse
as_const_viewviews::as_const (C++23)(C++23)
elements_viewviews::elements
keys_viewviews::keys
values_viewviews::values
enumerate_viewviews::enumerate (C++23)(C++23)
zip_viewviews::zip (C++23)(C++23)
zip_transform_viewviews::zip_transform (C++23)(C++23)

adjacent_viewviews::adjacent (C++23)(C++23)
views::pairwise (C++23)
adjacent_transform_viewviews::adjacent_transform (C++23)(C++23)
views::pairwise_transform (C++23)
chunk_viewviews::chunk (C++23)(C++23)
slide_viewviews::slide (C++23)(C++23)
chunk_by_viewviews::chunk_by (C++23)(C++23)
stride_viewviews::stride (C++23)(C++23)
cartesian_product_viewviews::cartesian_product (C++23)(C++23)

Range generators
std::generator (C++23)

Range adaptor closure objects
range_adaptor_closure (C++23)

Range adaptor objects

Helper items

copyable-box
movable-box

(until C++23) (C++23)

simple-view
non-propagating-cache

[edit]

std::generator

Member functions
generator::generator
generator::~generator
generator::operator=
generator::begin
generator::end
promise_type
generator::promise_type::get_return_object
generator::promise_type::initial_suspend
generator::promise_type::final_suspend
generator::promise_type::yield_value
generator::promise_type::return_void
generator::promise_type::unhandled_exception
generator::promise_type::operator new
generator::promise_type::operator delete
Iterator
generator::iterator::iterator
generator::iterator::operator=
generator::iterator::operator*
generator::iterator::operator++ generator::iterator::operator++(int)
operator==(generator::iterator, std::default_sentinel_t)

[edit]

Defined in header`<generator>`
template< class Ref, class V=void, class Allocator=void> class generator :publicranges::view_interface<generator<Ref, V, Allocator>>	(1)	(since C++23)
namespace pmr{ template<class Ref,class V=void> using generator= std::generator<Ref, V,std::pmr::polymorphic_allocator<>>; }	(2)	(since C++23)

1) The class templatestd::generator presents aview of the elements yielded by the evaluation of acoroutine.

2) Convenience alias template for thegenerator using thepolymorphic allocator.

Astd::generator generates a sequence of elements by repeatedly resuming the coroutine from which it was returned.Each time aco_yield statement is evaluated, the coroutine produces one element of the sequence.When theco_yield statement is of the formco_yield ranges::elements_of(rng), each element of therangerng is successively produced as an element of the sequence.

std::generator modelsview andinput_range.

The behavior of a program that adds a specialization forstd::generator is undefined.

[edit]Template parameters

Ref	-	the reference type (ranges::range_reference_t) of the generator. If`V` isvoid, both the reference type and the value type are inferred from`Ref`
V	-	the value type (ranges::range_value_t) of the generator, orvoid
Allocator	-	an allocator type orvoid

IfAllocator is notvoid, then the behavior is undefined ifAllocator does not meet theAllocator requirements.

[edit]Member types

Member	Definition
`value`(private)	std::conditional_t<std::is_void_v<V>,std::remove_cvref_t<Ref>, V>; (exposition-only member type*)
`reference`(private)	std::conditional_t<std::is_void_v<V>, Ref&&, Ref>; (exposition-only member type*)
`yielded`	std::conditional_t<std::is_reference_v<`reference` >, `reference`,const `reference` &>

Type requirements
- std::allocator_traits<Allocator>::pointer is a pointer type.
- `value` is a cv-unqualified object type.
- `reference` is either a reference type, or a cv-unqualified object type that models`copy_constructible`.
- Let`RRef` denotestd::remove_reference_t<`reference` >&&, if`reference` is a reference type, and`reference` otherwise. std::common_reference_with<`reference` &&, `value` &> is modeled. std::common_reference_with<`reference` &&, `RRef` &&> is modeled. std::common_reference_with<`RRef` &&,const `value` &> is modeled.

The program is ill-formed if any of these type requirements is not satisfied.

[edit]Data members

Member Definition

active_(private)

Internally, each active instance ofstd::generator is associated with a stack (handled as if by object of typestd::unique_ptr<std::stack<std::coroutine_handle<>>>).

Whenbegin is called, a new stack is created and the generator is added to the stack.
Whenco_yield ranges::elements_of(rng) is evaluated in a generator body,rng is converted to a generator and added to the stack that contains the enclosing generator.
When a generator iterator isincremented, the coroutine at the top of the associated stack is resumed.
When a generator finishes (i.e. whenpromise_type::final_suspend is called), it is removed from the stack.
(exposition-only member object*)

coroutine_(private) a handle of typestd::coroutine_handle<promise_type>
(exposition-only member object*)

[edit]Member functions

(constructor)	constructs a`generator` object (public member function)[edit]
(destructor)	effectively destroys the entire stack of yielded`generator`s (public member function)[edit]
operator=	assigns a`generator` object (public member function)[edit]
begin	resumes the initially suspended coroutine and returns an iterator to its handle (public member function)[edit]
end	returnsstd::default_sentinel (public member function)[edit]
Inherited fromstd::ranges::view_interface
empty	returns whether the derived view is empty, provided only if it satisfies`sized_range` or`forward_range` (public member function of`std::ranges::view_interface<D>`)[edit]
cbegin (C++23)	returns a constant iterator to the beginning of the range (public member function of`std::ranges::view_interface<D>`)[edit]
cend (C++23)	returns a sentinel for the constant iterator of the range (public member function of`std::ranges::view_interface<D>`)[edit]
operator bool	returns whether the derived view is not empty, provided only ifranges::empty is applicable to it (public member function of`std::ranges::view_interface<D>`)[edit]

[edit]Nested classes

promise_type	the promise type (public member class)
iterator	the iterator type (exposition-only member class*)

[edit]Notes

Feature-test macro	Value	Std	Feature
`__cpp_lib_generator`	`202207L`	(C++23)	`std::generator` – synchronouscoroutine generator forranges

[edit]Example

Run this code

#include <generator>#include <iostream> template<typename T>struct Tree{    T value;    Tree*left{},*right{};     std::generator<const T&> traverse_inorder()const{if(left)            co_yield std::ranges::elements_of(left->traverse_inorder());         co_yield value; if(right)            co_yield std::ranges::elements_of(right->traverse_inorder());}}; int main(){    Tree<char> tree[]{{'D', tree+1, tree+2},//                            │//            ┌───────────────┴────────────────┐//            │                                │{'B', tree+3, tree+4},{'F', tree+5, tree+6},//            │                                │//  ┌─────────┴─────────────┐      ┌───────────┴─────────────┐//  │                       │      │                         │{'A'},{'C'},{'E'},{'G'}}; for(char x: tree->traverse_inorder())std::cout<< x<<' ';std::cout<<'\n';}