The list generator is used to repeat the execution of an embedded generator
and interspace it with the output of another generator one or more times.
It succeeds if the embedded generator has been successfully executed
at least once.

Semantics of an expression is defined only where it differs from, or
is not defined in BinaryGenerator.

Expression

Semantics

a%b

The generator a
is executed one or more times depending on the availability
of an attribute. The output generated by a
is interspaced with the output generated by b.
The list generator succeeds if its first embedded generator
has been successfully executed at least once (unless the underlying
output stream reports an error).

The list expression a%b
is a shortcut for a<<*(b<<a).
It is almost semantically equivalent, except for the attribute of b, which gets ignored in the case of
the list generator.

Note

All failing iterations of the embedded generator will consume one element
from the supplied attribute. The overall a%b
will succeed as long as at least one invocation of the embedded generator,
a, will succeed (unless
the underlying output stream reports an error).

The table above uses vector<A> as a placeholder only. The notation
of vector<A>
stands for any STL container holding elements
of type A.

The list generator will execute its embedded generator once for each
element in the provided container attribute and as long as the embedded
generator succeeds. The output generated by its first generator will
be interspaced by the output generated by the second generator. On each
iteration it will pass the next consecutive element from the container
attribute to the first embedded generator. The second embedded generator
does not get passed any attributes (it gets invoked using an unused_type as its attribute). Therefore
the number of iterations will not be larger than the number of elements
in the container passed as its attribute. An empty container will make
the list generator fail.

Tip

If you want to use the list generator and still allow for an empty
attribute, you can use the optional operator (see Optional
(unary -)):

-(a%b)

which will succeed even if the provided container attribute does not
contain any elements.

The overall complexity of the list generator is defined by the complexity
of its embedded generators multiplied by the number of executed iterations.
The complexity of the list generator itself is O(N), where N is the
number of elements in the container passed as its attribute.