std::generator

Определено в заголовке <generator>

Определено в заголовке `<generator>`
template< class Ref, class V = void, class Allocator = void > class generator : public ranges::view_interface<generator<Ref, V, Allocator>>	(1)	(с C++23)
namespace pmr { template< class Ref, class V = void > using generator = std::generator<Ref, V, std::pmr::polymorphic_allocator<>>; }	(2)	(с C++23)

template<
    class Ref,
    class V = void,
    class Allocator = void >
class generator
    : public ranges::view_interface<generator<Ref, V, Allocator>>

(1)

(с C++23)

namespace pmr {
    template< class Ref, class V = void >
    using generator =
        std::generator<Ref, V, std::pmr::polymorphic_allocator<>>;
}

(2)

(с C++23)

1) Шаблон класса std::generator представляет view элементов, возвращаемых результатом вычисления корутины.

2) Удобный псевдоним-шаблон для generator с использованием полиморфного аллокатора.

Объект типа std::generator генерирует последовательность элементов, многократно возобновляя корутину, из которой он был возвращён. Каждый раз, когда вычисляется оператор co_yield, корутина производит один элемент последовательности. Когда оператор co_yield имеет вид co_yield ranges::elements_of(rng), каждый элемент range rng поочерёдно генерируется в качестве элемента последовательности.

std::generator моделирует view и input_range.

Поведение программы, добавляющей специализацию для std::generator является неопределённым.

Члены данных

Имя Описание

Имя	Описание
`active_` (приватный)	Внутри, каждый активный экземпляр `std::generator` ассоциирован со стеком (обрабатывается как объект типа `std::unique_ptr<std::stack<std::coroutine_handle<>>>`). При вызове `begin` создаётся новый стек, и генератор добавляется в стек. При вычислении `co_yield ranges::elements_of(rng)` в теле генератора, `rng` преобразуется в генератор и добавляется в стек, содержащий окружающий генератор. При инкрементировании итератора генератора, корутина в верхней части связанного стека возобновляется. Когда генератор завершается (т. е. когда вызывается `final_suspend`), он удаляется из стека. (член объекта — только для экспозиции*)
`coroutine_` (приватный)	`std::coroutine_handle<promise_type>` (член объекта — только для экспозиции*)

active_ (приватный)

Внутри, каждый активный экземпляр std::generator ассоциирован со стеком (обрабатывается как объект типа std::unique_ptr<std::stack<std::coroutine_handle<>>>).

При вызове begin создаётся новый стек, и генератор добавляется в стек.
При вычислении co_yield ranges::elements_of(rng) в теле генератора, rng преобразуется в генератор и добавляется в стек, содержащий окружающий генератор.
При инкрементировании итератора генератора, корутина в верхней части связанного стека возобновляется.
Когда генератор завершается (т. е. когда вызывается final_suspend), он удаляется из стека.
(член объекта — только для экспозиции*)

coroutine_ (приватный) std::coroutine_handle<promise_type>
(член объекта — только для экспозиции*)

Параметры шаблона

Ref	-	тип ссылки (`ranges::range_reference_t`) генератора. Если `V` является `void`, то тип ссылки и тип значения выводятся из `Ref`
V	-	тип значения (`range_value_t`) генератора, или `void`
Allocator	-	тип аллокатора или `void`

Если Allocator не void, то:

std::allocator_traits<Allocator>::pointer — тип указателя;
Allocator удовлетворяет требованиям аллокатора.

Типы членов

Тип члена	Определение
`value` (приватный)	`std::conditional_t<std::is_void_v<V>, std::remove_cvref_t<Ref>, V>;`. `value` — тип объекта без квалификаторов cv. (член типа — только для экспозиции*)
`reference` (приватный)	`std::conditional_t<std::is_void_v<V>, Ref&&, Ref>;`. `reference` — либо тип ссылки, либо тип объекта без квалификаторов cv, который моделирует `copy_constructible`. (член типа — только для экспозиции*)
`yielded`	`std::conditional_t<std::is_reference_v<reference>, reference, const reference&>`.

Пусть /*RRef*/ обозначает:

std::remove_reference_t</*reference*/>&&, если /*reference*/ — тип ссылки, и
/*reference*/ в противном случае.

Моделируются следующие концепции:

std::common_reference_with</*reference*/&&, /*value*/&>,
std::common_reference_with</*reference*/&&, /*RRef*/&&>, и
std::common_reference_with</*RRef*/&&, const /*value*/&>.

Члены-функции

(конструктор)	создаёт объект `generator` (публичная функция-член)
(деструктор)	фактически уничтожает весь стек возвращаемых `generator` (публичная функция-член)
operator=	присваивает объект `generator` (публичная функция-член)
begin	возобновляет первоначально приостановленную корутину и возвращает итератор на её дескриптор (публичная функция-член)
end	возвращает `std::default_sentinel` (публичная функция-член)
Унаследовано от `std::ranges::view_interface`
empty (C++20)	возвращает, пуст ли производный вид. Предоставляется, если он удовлетворяет `sized_range` или `forward_range`. (публичная функция-член `std::ranges::view_interface<D>`)
cbegin (C++23)	возвращает постоянный итератор к началу диапазона. (публичная функция-член `std::ranges::view_interface<D>`)
cend (C++23)	возвращает конечный маркер постоянного итератора диапазона. (публичная функция-член `std::ranges::view_interface<D>`)
operator bool (C++20)	возвращает, пуст ли производный вид. Предоставляется, если `ranges::empty` применимо к нему. (публичная функция-член `std::ranges::view_interface<D>`)

Вложенные классы

promise_type	тип обещания (публичный вложенный класс)
iterator	тип итератора (вложенный класс — только для экспозиции*)

Примечания

Макрокоманда проверки наличия функции	Значение	Стандарт	Функция
`__cpp_lib_generator`	202207L	(C++23)	`std::generator` – синхронный генератор корутины для диапазонов

Пример

#include <generator>
#include <iostream>
#include <ranges>
 
std::generator<char> letters(char first)
{
    for (;; co_yield first++);
}
 
int main()
{
    for (const char ch : letters('a') | std::views::take(26))
        std::cout << ch << ' ';
    std::cout << '\n';
}

Вывод:

a b c d e f g h i j k l m n o p q r s t u v w x y z

Ссылки

Стандарт C++23 (ISO/IEC 14882:2023):

26.8 Генераторы диапазонов [coro.generator]

См. также

noop_coroutine

(C++20)

создает дескриптор корутины, у которой нет наблюдаемых эффектов при возобновлении или уничтожении
(функция)

© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/coroutine/generator