home | help 
std::generator(3)	       C++ Standard Libary	       std::generator(3)

NAME
     std::generator - std::generator

Synopsis
	Defined in header <generator>
	template<

	    class Ref,
	    class  V  = void,						     (1)
     (since C++23)
	    class Allocator = void >
	class generator

	    : public ranges::view_interface<generator<Ref, V, Allocator>>
	namespace pmr {

	    template< class Ref, class V = void >
	    using generator  =						     (2)
     (since C++23)
		std::generator<Ref, V, std::pmr::polymorphic_allocator<>>;

	}

	1)  The  class	template  std::generator presents a view of the elements
     yielded by the
	evaluation of a coroutine.
	2) Convenience alias template for the generator  using	the  polymorphic
     allocator.

	A std::generator generates a sequence of elements by repeatedly resuming
     the
	coroutine  from which it was returned. Each time a co_yield statement is
     evaluated,
	the coroutine produces one element of the sequence.  When  the	co_yield
     statement is
	of the form co_yield ranges::elements_of(rng), each element of the range
     rng is
	successively produced as an element of the sequence.

	std::generator models view and input_range.

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

Template parameters
	Ref	  - the reference type (ranges::range_reference_t) of the gener-
     ator. If V is
		    void, both the reference type and the  value  type	are  in-
     ferred from Ref
	V	  - the value type (range_value_t) of the generator, or void
	Allocator - an allocator type or void

	If  Allocator  is  not void, then the behavior is undefined if Allocator
     does not meet
	the Allocator requirements.

Member types
	Member type	 Definition
			 std::conditional_t<std::is_void_v<V>,		std::re-
     move_cvref_t<Ref>,
	value (private)  V>;.
			 (exposition-only member type*)
	reference	 std::conditional_t<std::is_void_v<V>, Ref&&, Ref>;.
	(private)	 (exposition-only member type*)
	yielded 	 std::conditional_t<std::is_reference_v<reference>, ref-
     erence, 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*/ denote:std::remove_reference_t</*reference*/>&&, if  /*ref-
     erence*/ 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 sat-
     isfied.

Member objects
	Member name  Definition
		     Internally, each active instance of std::generator is asso-
     ciated with a
		     stack (handled as if by object of type
		     std::unique_ptr<std::stack<std::coroutine_handle<>>>).

		       * When begin is called, a new stack is  created	and  the
     generator is
			 added to the stack.
	active_ 	* When co_yield ranges::elements_of(rng) is evaluated in
     a generator
	(private)	 body, rng is converted to a generator and added to  the
     stack that
			 contains the enclosing generator.
		       * When a generator iterator is incremented, the coroutine
     at the top
			 of the associated stack is resumed.
		       *  When	a generator finishes (i.e. when final_suspend is
     called), it
			 is removed from the stack.
			 (exposition-only member object*)
	coroutine_   a handle of type std::coroutine_handle<promise_type>
	(private)    (exposition-only member object*)

Member functions
	constructor   constructs a generator object
		      (public member function)
	destructor    effectively destroys the entire stack of	yielded  genera-
     tors
		      (public member function)
	operator=     assigns a generator object
		      (public member function)
		      resumes  the  initially suspended coroutine and returns an
     iterator to
	begin	      its handle
		      (public member function)
	end	      returns std::default_sentinel
		      (public member function)
	      Inherited from std::ranges::view_interface
	empty	      returns whether the derived view is empty. Provided if  it
     satisfies
	(C++20)       sized_range or forward_range.
		      (public member function of std::ranges::view_interface<D>)
	cbegin	      returns a constant iterator to the beginning of the range.
	(C++23)       (public member function of std::ranges::view_interface<D>)
	cend	      returns a sentinel for the constant iterator of the range.
	(C++23)       (public member function of std::ranges::view_interface<D>)
	operator bool returns whether the derived view is not empty. Provided if
	(C++20)       ranges::empty is applicable to it.
		      (public member function of std::ranges::view_interface<D>)

	Nested classes

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

Notes
	Feature-test macro   Value    Std			Feature
	__cpp_lib_generator  202207L (C++23) std::generator a synchronous corou-
     tine generator
					    for ranges

Example
	Can be tried in Compiler Explorer

     // 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)
		  for (const T& x : left->traverse_inorder())
		      co_yield x;

	      co_yield value;
	      if (right)
		  for (const T& x : right->traverse_inorder())
		      co_yield x;
	  }
      };

      int main()
      {
	  Tree<char> tree[]
	  {
					  {'D', tree + 1, tree + 2},
	      //			    a
	      //	    aaaaaaaaaaaaaaaaa'aaaaaaaaaaaaaaaaa
	      //	    a				     a
			  {'B', tree + 3, tree + 4},	   {'F', tree + 5,  tree
     + 6},
	      //	    a				     a
	      //  aaaaaaaaaaa'aaaaaaaaaaaaaa	  aaaaaaaaaaaaa'aaaaaaaaaaaaaa
	      //  a			  a	 a			   a
		{'A'},			{'C'}, {'E'},			 {'G'}
	  };

	  for (char x : tree->traverse_inorder())
	      std::cout << x << ' ';
	  std::cout << '\n';
      }

Output:
      A B C D E F G

References
	  * C++23 standard (ISO/IEC 14882:2023):

	  * 26.8 Range generators [coro.generator]

See also
	noop_coroutine creates a coroutine handle that has no observable effects
     when
	(C++20)        resumed or destroyed
		       (function)

http://cppreference.com 	   2024.06.10		       std::generator(3)
home | help