List Generator (a % b)

| Home | Libraries | People | FAQ | More

##### List Generator (`a % b`)

###### Description

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

###### Header

    // forwards to <boost/spirit/home/karma/operator/list.hpp>
    #include <boost/spirit/include/karma_list.hpp>

Also, see Include Structure.

###### Model of

> `BinaryGenerator`

###### Expression Semantics

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 interspersed 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).

###### Attributes

See Compound Attribute Notation.

Expression | Attribute
--- | ---
`a % b` (list) |
    a: A, b: B --> (a % b): vector<A>
    a: Unused, b: B --> (a % b): Unused

| Important
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 interspersed 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.

###### Complexity

> 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.

###### Example

| Note
The test harness for the example(s) below is presented in the Basics Examples section.

Some includes:

    #include <boost/spirit/include/karma.hpp>
    #include <boost/spirit/include/support_utree.hpp>
    #include <boost/phoenix/core.hpp>
    #include <boost/phoenix/operator.hpp>
    #include <boost/fusion/include/std_pair.hpp>
    #include <boost/proto/deep_copy.hpp>
    #include <iostream>
    #include <string>

Some using declarations:

    using boost::spirit::karma::double_;

Basic usage of a list generator:

    std::vector<double> v1;
    v1.push_back(1.0);
    test_generator_attr("1.0", double_ % ',', v1);

    v1.push_back(2.0);
    test_generator_attr("1.0,2.0", double_ % ',', v1);