Generator Directive for Temporary Output Buffering (buffer[])

Generator Directive for Temporary Output Buffering (`buffer[]`)

Description

All generator components (except the Alternative (|) generator) pass their generated output directly to the underlying output stream. If a generator fails halfway through, the output generated so far is not 'rolled back'. The buffering generator directive allows to avoid this unwanted output to be generated. It temporarily redirects the output produced by the embedded generator into a buffer. This buffer is flushed to the underlying stream only after the embedded generator succeeded, but is discarded otherwise.

Header

// forwards to <boost/spirit/home/karma/directive/buffer.hpp>
#include <boost/spirit/include/karma_buffer.hpp>

Also, see Include Structure.

Name
`boost::spirit::buffer // alias: boost::spirit::karma::buffer`

Model of

UnaryGenerator

Notation

a: A generator object
A: Attribute type of generator a

Expression Semantics

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

Expression	Semantics
`buffer[a]`	The embedded generator `a` is invoked but its output is temporarily intercepted and stored in an internal buffer. If `a` succeeds the buffer content is flushed to the underlying output stream, otherwise the buffer content is discarded. The buffer directive succeeds as long as the embedded generator succeeded (unless the underlying output stream reports an error).

	Tip
	If you want to make the buffered generator succeed regardless of the outcome of the embedded generator, simply wrap the `buffer[a]` into an additional optional: `-buffer[a]` (see Optional (unary `-`)).

Attributes

See Compound Attribute Notation.

Expression	Attribute
`buffer[a]`	a: A --> buffer[a]: A a: Unused --> buffer[a]: Unused

Expression

Attribute

buffer[a]

a: A --> buffer[a]: A
a: Unused --> buffer[a]: Unused

Complexity

The overall complexity of the buffering generator directive is defined by the complexity of its embedded generator. The complexity of the buffering directive generator itself is O(N), where N is the number of characters buffered.

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_;
using boost::spirit::karma::buffer;

Basic usage of a buffering generator directive. It shows how the partial output generated in the first example does not show up in the generated output as the plus generator fails (no data is available, see Plus (unary +)).

std::vector<double> v;                // empty container
test_generator_attr("", -buffer['[' << +double_ << ']'], v);

v.push_back(1.0);                     // now, fill the container
v.push_back(2.0);
test_generator_attr("[1.02.0]", buffer['[' << +double_ << ']'], v);