Iterator Based Generate API

| Home | Libraries | People | FAQ | More

##### Iterator Based Generate API

###### Description

The library provides a couple of free functions to make generating a snap. These generator functions have two forms. The first form, `generate`, concatenates the output generated by the involved components without inserting any output in between. The second `generate_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.

###### Header

    // forwards to <boost/spirit/home/karma/generate.hpp>
    #include <boost/spirit/include/karma_generate.hpp>

For variadic attributes:

    // forwards to <boost/spirit/home/karma/generate_attr.hpp>
    #include <boost/spirit/include/karma_generate_attr.hpp>

The variadic attributes version of the API allows one or more attributes to be passed into the `generate` functions. The functions 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.

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::karma::generate`
`boost::spirit::karma::generate_delimited`
`boost::spirit::karma::delimit_flag::predelimit`
`boost::spirit::karma::delimit_flag::dont_predelimit`

###### Synopsis

    template <typename OutputIterator, typename Expr>
    inline bool
    generate(
        OutputIterator& sink
      , Expr const& expr);

    template <typename OutputIterator, typename Expr
      , typename Attr1, typename Attr2, ..., typename AttrN>
    inline bool
    generate(
        OutputIterator& sink
      , Expr const& expr
      , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);

    template <typename OutputIterator, typename Expr, typename Delimiter>
    inline bool
    generate_delimited(
        OutputIterator& sink
      , Expr const& expr
      , Delimiter const& delimiter
      , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit = delimit_flag::dont_predelimit);

    template <typename OutputIterator, typename Expr, typename Delimiter
      , typename Attr1, typename Attr2, ..., typename AttrN>
    inline bool
    generate_delimited(
        OutputIterator& sink
      , Expr const& expr
      , Delimiter const& delimiter
      , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);

    template <typename OutputIterator, typename Expr, typename Delimiter
      , typename Attr1, typename Attr2, ..., typename AttrN>
    inline bool
    generate_delimited(
        OutputIterator& sink
      , Expr const& expr
      , Delimiter const& delimiter
      , BOOST_SCOPED_ENUM(delimit_flag) pre_delimit
      , Attr1 const& attr1, Attr2 const& attr2, ..., AttrN const& attrN);

All functions above return `true` if none of the involved generator components failed, and `false` otherwise. If during the process of the output generation the underlying output stream reports an error, the return value will be `false` as well.

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 function with two or more attributes internally combine (constant) references to all passed attributes into a `fusion::vector` and forward this as a combined attribute to the corresponding function taking one attribute.

The `generate_delimited` functions 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 function while passing `delimit_flag::predelimit` to the corresponding argument.

###### Template parameters

Parameter | Description
--- | ---
`OutputIterator` | `OutputIterator` receiving the generated output.
`Expr` | An expression that can be converted to a Karma generator.
`Delimiter` | Generator used to delimit the output of the expression components.
`Attr1`, `Attr2`, ..., `AttrN` | One or more attributes.