...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The library provides a couple of Standard IO Manipulators
allowing to integrate Spirit.Karma output generation
facilities with Standard output streams. These generator manipulators
have two forms. The first form, format
,
concatenates the output generated by the involved components without
inserting any output in between. The second, format_delimited
,
intersperses the output generated by the involved components using the
given delimiter generator. Both versions can take in attributes by (constant)
reference that hold the attribute values to output.
// forwards to <boost/spirit/home/karma/stream/format_manip.hpp> #include <boost/spirit/include/karma_format.hpp>
For variadic attributes:
// forwards to <boost/spirit/home/karma/stream/format_manip_attr.hpp> #include <boost/spirit/include/karma_format_attr.hpp>
The variadic attributes version of the API allows one or more attributes
to be passed into the format
manipulators. The manipulators taking two or more attributes are usable
when the generator expression is a Sequence
(<<
) only.
In this case each of the attributes passed have to match the corresponding
part of the sequence.
For the API functions deducing the correct (matching) generator type from the supplied attribute type:
// forwards to <boost/spirit/home/karma/format_auto.hpp> #include <boost/spirit/include/karma_format_auto.hpp>
Also, see Include Structure.
Name |
---|
|
|
|
|
namespace boost { namespace spirit { namespace karma { template <typename Expr> inline <unspecified> format( Expr const& xpr); template <typename Expr , typename Attr1, typename Attr2, ..., typename AttrN> inline <unspecified> format( Expr const& xpr , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); template <typename Expr, typename Delimiter> inline <unspecified> format_delimited( Expr const& expr , Delimiter const& d , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); template <typename Expr, typename Delimiter , typename Attr1, typename Attr2, ..., typename AttrN> inline <unspecified> format_delimited( Expr const& expr , Delimiter const& d , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); template <typename Expr, typename Delimiter , typename Attr1, typename Attr2, ..., typename AttrN> inline <unspecified> format_delimited( Expr const& expr , Delimiter const& d , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN); }}}
Spirit.Karma generator API functions based on the automatic creation of the matching generator type:
namespace boost { namespace spirit { namespace karma { template <typename Attr, typename Delimiter> inline <unspecified> format_delimited( Attr const& attr , Delimiter const& d , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit); template <typename Attr> inline <unspecified> format( Attr const& xpr); }}}
All functions above return a standard IO stream manipulator instance
(see Manipulators),
which when streamed to an output stream will result in generating the
output as emitted by the embedded Spirit.Karma generator
expression. Any error occurring during the invocation of the Spirit.Karma
generators will be reflected in the streams status flag (std::ios_base::failbit
will be set).
The maximum number of supported arguments is limited by the preprocessor
constant SPIRIT_ARGUMENTS_LIMIT
.
This constant defaults to the value defined by the preprocessor constant
PHOENIX_LIMIT
(which
in turn defaults to 10
).
Note | |
---|---|
The variadic manipulators with two or more attributes internally combine
(constant) references to all passed attributes into a |
The format_delimited
manipulators not taking an explicit delimit_flag
as one of their arguments don't invoke the passed delimiter before starting
to generate output from the generator expression. This can be enabled
by using the other version of that manipulator while passing delimit_flag::predelimit
to the corresponding argument.
Parameter |
Description |
---|---|
|
An expression that can be converted to a Karma generator. |
|
Generator used to delimit the output of the expression components. |
|
An attribute type utilized to create the corresponding generator type from. |
|
One or more attributes. |