Separate Output Into Columns (columns[])

| Home | Libraries | People | FAQ | More

##### Separate Output Into Columns (`columns[]`)

###### Description

The `columns[]` directive separates the output emitted by the embedded generator by inserting special column separators.

###### Header

    // forwards to <boost/spirit/home/karma/directive/columns.hpp>
    #include <boost/spirit/include/karma_columns.hpp>

Also, see Include Structure.

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

###### Model of

> `UnaryGenerator`

Notation

`a`

  A generator object

`g`

  A generator object, or a Lazy Argument that evaluates to a generator object, will be used to emit column separators

`A`

  Attribute type of generator `a`

  [`num`

  Numeric literal, any unsigned integer value, or a Lazy Argument that evaluates to an unsigned integer value defining the number of items to emit in between the column separators

###### Expression Semantics

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

Expression | Semantics
--- | ---
`columns[a]` | The `columns` directive invokes a generator after each N-th element of the embedded generator has been emitted. The number of columns is defined by the preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`. The column separator used will be `karma::eol`.
`columns(num)[a]` | The `columns` directive invokes a generator after each N-th element of the embedded generator has been emitted. The number of columns is defined by the argument to the directive `num`. The column separator used will be `karma::eol`.
`columns(g)[a]` | The `columns` directive invokes a generator after each N-th element of the embedded generator has been emitted. The number of columns is defined by the preprocessor constant `BOOST_KARMA_DEFAULT_COLUMNS`. The column separator used will be `g`.
`columns(num, g)[a]` | The `columns` directive invokes a generator after each N-th element of the embedded generator has been emitted. The number of columns is defined by the argument to the directive `num`. The column separator used will be `g`.

###### Attributes

See Compound Attribute Notation.

Expression | Attribute
--- | ---

`columns[a]`

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

`columns(num)[a]`

    a: A --> columns(num)[a]: A
    a: Unused --> columns(num)[a]: Unused

`columns(g)[a]`

    a: A --> columns(g)[a]: A
    a: Unused --> columns(g)[a]: Unused

`columns(num, g)[a]`

    a: A --> columns(num, g)[a]: A
    a: Unused --> columns(num, g)[a]: Unused

###### Complexity

> The overall complexity of the `columns` generator directive depends on the complexity of the embeddded generator. The complexitz of the `columns` generator directive itself is O(N), where `N` is the number of inserted column separators.

###### 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/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_;
    using boost::spirit::karma::columns;
    using boost::spirit::karma::space;

Basic usage of the `columns` generators:

    std::vector<double> v;
    v.push_back(1.0);
    v.push_back(2.0);
    v.push_back(3.0);
    test_generator_attr("1.0\n2.0\n3.0\n", columns(1)[*double_], v);
    test_generator_attr_delim("1.0 2.0 \n3.0 \n", columns(2)[*double_], space, v);