...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
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.
// forwards to <boost/spirit/home/karma/operator/list.hpp> #include <boost/spirit/include/karma_list.hpp>
Also, see Include Structure.
Semantics of an expression is defined only where it differs from, or
is not defined in BinaryGenerator
.
Expression |
Semantics |
---|---|
|
The generator |
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 |
See Compound Attribute Notation.
Expression |
Attribute |
---|---|
|
a: A, b: B --> (a % b): vector<A> a: Unused, b: B --> (a % b): Unused
|
Important | |
---|---|
The table above uses |
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.
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/phoenix_core.hpp> #include <boost/spirit/include/phoenix_operator.hpp> #include <boost/fusion/include/std_pair.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);