std::generator<Ref,V,Allocator>::promise_type::yield_value

 

C++

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

 

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) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)     type_order (C++26) 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) 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 and type 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)

 

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)

Coroutine tasks

execution::task (C++26)

 

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) sized-random-access-range (C++26)

Views
view_interface	subrange

Range factories
empty_viewviews::empty	single_viewviews::single	basic_istream_viewviews::istream	iota_viewviews::iota views::indices (C++26)	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 as_input_viewviews::as_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

 

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)

 

std::suspend_always yield_value( yielded val ) noexcept;	(1)	(since C++23)
auto yield_value( const std::remove_reference_t<yielded>& lval ) requires std::is_rvalue_reference_v<yielded> && std::constructible_from<std::remove_cvref_t<yielded>, const std::remove_reference_t<yielded>&>;	(2)	(since C++23)
template< class R2, class V2, class Alloc2, class Unused > requires std::same_as<typename std::generator<T2, V2, Alloc2>::yielded, yielded> auto yield_value( ranges::elements_of<std::generator<T2, V2, Alloc2>&&, Unused> g ) noexcept;	(3)	(since C++23)
template< class R2, class V2, class Alloc2, class Unused > requires std::same_as<typename std::generator<T2, V2, Alloc2>::yielded, yielded> auto yield_value( ranges::elements_of<std::generator<T2, V2, Alloc2>&, Unused> g ) noexcept;	(4)	(since C++23)
template< ranges::input_range R, class Alloc > requires std::convertible_to<ranges::range_reference_t<R>, yielded> auto yield_value( ranges::elements_of<R, Alloc> r );	(5)	(since C++23)

An implementation of coroutine interface functions used internally to support operator co_yield.

(yielded is a reference type defined in std::generator.)

1) Assigns std::addressof(val) to value_. Returns {}.

2) Returns an awaitable object x of an unspecified type that stores an object of type std::remove_cvref_t<yielded>. x is direct-non-list-initialized with lval, whose member functions are configured so that value_ points to that stored object. Then suspends the coroutine.

3, 4) Let x be some generator object.

Returns an awaitable object of an unspecified type into which g.range is moved,

• whose member await_ready returns false,
• whose member await_suspend pushes g.range.coroutine_ into *x.active_ and
• resumes execution of the coroutine referred to by g.range.coroutine_, and
• whose member await_resume evaluates

• std::rethrow_exception(except_) if bool(except_) is true.
• If bool(except_) is false, the await_resume member has no effects.

The coroutine referred to by g.range.coroutine_ must be suspended at its initial suspend point. Otherwise the behavior is undefined.

5) Equivalent to:

auto nested = [](std::allocator_arg_t, Alloc, ranges::iterator_t<R> i,
                 ranges::sentinel_t<R> s) ->
    std::generator<yielded, void, Alloc>
{
    for (; i != s; ++i)
        co_yield static_cast<yielded>(*i);
};

return yield_value(ranges::elements_of(nested(
    allocator_arg, r.allocator, ranges::begin(r.range), ranges::end(r.range))));

2,3) A handle referring to the coroutine whose promise object is *this must be at the top of *active_ of some generator object. Otherwise, the behavior is undefined.

2-5) A yield-expression that calls these overload has the type void.

Parameters

val	-	a value which is a result of the yield-expression evaluation
lval	-	an lvalue which is a result of the yield-expression evaluation
g	-	a range of elements produced by a generator
r	-	a range of elements

Return value

1) The awaitable object of type std::suspend_always.

2-5) An awaitable object of an unspecified type as described above.

Exceptions

2,5) May throw any exception thrown by the initialization of the stored object.

Defect reports

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

DR	Applied to	Behavior as published	Correct behavior
LWG 3899	C++23	yield_value on a range of elements produced by lvalue generator used generic elements_of overload	used special elements_of overload for such generators
LWG 4119	C++23	range_value_t in generator's template argument as part of the return type of nested in (5) may be ill-formed	used void