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

来自cppreference.com
 
C++
 
工具库
通用工具
关系运算符 (C++20 弃用)
 
协程支持
协程特征
(C++20)
协程句柄
(C++20)
无操作协程
(C++20)
(C++20)
平凡可等待体
(C++20)
(C++20)
范围生成器
(C++23)
 
范围库
范围适配器
 
std::generator
 
std::suspend_always yield_value( yielded val ) noexcept;
 (1) (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) (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) (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) (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) (C++23 起)

一种协程接口函数的实现，内部使用以支持 operator co_yield。

(yielded 是 std::generator 中定义的引用类型。)

1) 赋值 std::addressof(val) 给 value_。返回 {}。
2) 返回未指明类型的可等待对象 x，它存储一个 std::remove_cvref_t<yielded> 类型的对象。x 以 lval 直接非列表初始化，其各成员函数被配置为使得 value_ 指向所存储的对象。然后暂停协程。
3, 4) 令 x 为某个 generator 对象。

返回未指明类型的可等待对象，g.range 被移动如其中，

  • 其成员 await_ready 返回 false，
  • 其成员 await_suspend 将 g.range.coroutine_ 推入 *x.active_ 并
  • 恢复 g.range.coroutine_ 所代表的协程的执行，并且
  • 其成员 await_resume 求值
  • std::rethrow_exception(except_) 若 bool(except_) 为 true。
  • 若 bool(except_) 为 false，则 await_resume 成员没有效果。
g.range.coroutine_ 所代表的协程必须在其初始暂停点暂停。否则其行为未定义。
5) 等价于： 
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) 某个生成器对象的 *active_ 的顶端必须为一个代表以 *this 为承诺对象的协程的句柄，否则，其行为未定义。
2-5) 调用这些重载的 yield-表达式 的类型为 void。

目录

[编辑] 参数

val - yield-表达式 求值结果的值
lval - yield-表达式 求值结果的左值
g - 由生成器产生的元素范围
r - 元素范围

[编辑] 返回值

1) std::suspend_always 类型的可等待对象。
2-5) 如上所述的未指明类型的可等待对象。

[编辑] 异常

2,4) 可能抛出由所存储对象的初始化所抛出的任何异常。

[编辑] 示例

本节未完成
原因：暂无示例

[编辑] 缺陷报告

下列更改行为的缺陷报告追溯地应用于以前出版的 C++ 标准。

缺陷报告 应用于 出版时的行为 正确行为
LWG 3899 C++23 在由左值生成器产生的元素范围上使用 yield_value
使用的是泛型的 elements_of 重载 		为这种生成器使用专门的 elements_of 重载
LWG 4119 C++23 (5) 的 nested 中，作为返回类型一部分
的 generator 的模板实参的 range_value_t 可能非良构 		使用 void
来自“https://zh.cppreference.com/mwiki/index.php?title=cpp/coroutine/generator/promise_type/yield_value&oldid=96537”