Alignment Generator Directives (left_align[], center[], right_align[])

| Home | Libraries | People | FAQ | More

##### Alignment Generator Directives (`left_align[]`, `center[]`, `right_align[]`)

###### Description

The alignment directives allow to left align, right align or center output emitted by other generators into columns of a specified width while using an arbitrary generator to create the padding.

###### Header

For the `left_align[]` directive:

    // forwards to <boost/spirit/home/karma/directive/left_alignment.hpp>
    #include <boost/spirit/include/karma_left_alignment.hpp>

For the `center[]` directive:

    // forwards to <boost/spirit/home/karma/directive/center_alignment.hpp>
    #include <boost/spirit/include/karma_center_alignment.hpp>

For the `right_align[]` directive:

    // forwards to <boost/spirit/home/karma/directive/right_alignment.hpp>
    #include <boost/spirit/include/karma_right_alignment.hpp>

Also, see Include Structure.

###### Namespace

Name
`boost::spirit::left_align // alias: boost::spirit::karma::left_align`
`boost::spirit::center // alias: boost::spirit::karma::center`
`boost::spirit::right_align // alias: boost::spirit::karma::right_align`

###### Model of

> `UnaryGenerator`

Notation

`a`

  A generator object

`pad`

  A generator object, or a Lazy Argument that evaluates to a generator object

`A`, `Pad`

  Attribute types of the generators `a` and `pad`

`width`

  Numeric literal, any unsigned integer value, or a Lazy Argument that evaluates to an unsigned integer value

###### Expression Semantics

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

Expression | Semantics
--- | ---
`left_align[a]` | Generate `a` left aligned in a column of width as defined by the preprocessor constant `BOOST_KARMA_DEFAULT_FIELD_LENGTH` (default: 10), while using `space` to emit the necessary padding. This generator succeeds as long as its embedded generator `a` does not fail (unless the underlying output stream reports an error).
`left_align(width)[a]` | Generate `a` left aligned in a column of the given `width`, while using `space` to emit the necessary padding. This generator succeeds as long as its embedded generator `a` does not fail (unless the underlying output stream reports an error).
`left_align(pad)[a]` | Generate `a` left aligned in a column of width as defined by the preprocessor constant `BOOST_KARMA_DEFAULT_FIELD_LENGTH` (default: 10), while using the generator `pad` to emit the necessary padding. This generator succeeds as long as its embedded and padding generators `a` and `pad` do not fail (except if the underlying output stream reports an error).
`left_align(width, pad)[a]` | Generate `a` left aligned in a column of the given `width`, while using the generator `pad` to emit the necessary padding. This generator succeeds as long as its embedded and padding generators `a` and `pad` do not fail (unless the underlying output stream reports an error).
`center[a]` | Generate `a` centered in a column of width as defined by the preprocessor constant `BOOST_KARMA_DEFAULT_FIELD_LENGTH` (default: 10), while using `space` to emit the necessary padding. This generator succeeds as long as its embedded generator `a` does not fail (unless the underlying output stream reports an error).
`center(width)[a]` | Generate `a` centered in a column of the given `width`, while using `space` to emit the necessary padding. This generator succeeds as long as its embedded generator `a` does not fail (unless the underlying output stream reports an error).
`center(pad)[a]` | Generate `a` centered in a column of width as defined by the preprocessor constant `BOOST_KARMA_DEFAULT_FIELD_LENGTH` (default: 10), while using the generator `pad` to emit the necessary padding. This generator succeeds as long as its embedded and padding generators `a` and `pad` do not fail (except if the underlying output stream reports an error).
`center(width, pad)[a]` | Generate `a` centered in a column of the given `width`, while using the generator `pad` to emit the necessary padding. This generator succeeds as long as its embedded and padding generators `a` and `pad` do not fail (unless the underlying output stream reports an error).
`right_align[a]` | Generate `a` right aligned in a column of width as defined by the preprocessor constant `BOOST_KARMA_DEFAULT_FIELD_LENGTH` (default: 10), while using `space` to emit the necessary padding. This generator succeeds as long as its embedded generator `a` does not fail (unless the underlying output stream reports an error).
`right_align(width)[a]` | Generate `a` right aligned in a column of the given `width`, while using `space` to emit the necessary padding. This generator succeeds as long as its embedded generator `a` does not fail (unless the underlying output stream reports an error).
`right_align(pad)[a]` | Generate `a` right aligned in a column of width as defined by the preprocessor constant `BOOST_KARMA_DEFAULT_FIELD_LENGTH` (default: 10), while using the generator `pad` to emit the necessary padding. This generator succeeds as long as its embedded and padding generators `a` and `pad` do not fail (except if the underlying output stream reports an error).
`right_align(width, pad)[a]` | Generate `a` right aligned in a column of the given `width`, while using the generator `pad` to emit the necessary padding. This generator succeeds as long as its embedded and padding generators `a` and `pad` do not fail (unless the underlying output stream reports an error).

| Note
None of the generator directives listed above limits the emitted output to the respective column width. If the emitted output is longer than the specified (or implied) column width, the generated output overruns the column to the right. If the output needs to be limited to a specified column width, use the `maxwidth[]` directive, for instance:
    maxwidth(8)[right_align(12)["1234567890"]]
which will output (without the quotes):
    "  123456"

###### Attributes

See Compound Attribute Notation.

Expression | Attribute
--- | ---
`left_align[]` |
    a: A --> left_align[a]: A
    a: Unused --> left_align[a]: Unused
`left_align(width)[]` |
    a: A --> left_align(width)[a]: A
    a: Unused --> left_align(width)[a]: Unused
`left_align(pad)[]` |
    a: A, pad: Pad --> left_align(pad)[a]: A
    a: Unused, pad: Pad --> left_align(pad)[a]: Unused
`left_align(pad, width)[]` |
    a: A, pad: Pad --> left_align(pad, width)[a]: A
    a: Unused, pad: Pad --> left_align(pad, width)[a]: Unused
`center[]` |
    a: A --> center[a]: A
    a: Unused --> center[a]: Unused
`center(width)[]` |
    a: A --> center(width)[a]: A
    a: Unused --> center(width)[a]: Unused
`center(pad)[]` |
    a: A, pad: Pad --> center(pad)[a]: A
    a: Unused, pad: Pad --> center(pad)[a]: Unused
`center(pad, width)[]` |
    a: A, pad: Pad --> center(pad, width)[a]: A
    a: Unused, pad: Pad --> center(pad, width)[a]: Unused
`right_align[]` |
    a: A --> right_align[a]: A
    a: Unused --> right_align[a]: Unused
`right_align(width)[]` |
    a: A --> right_align(width)[a]: A
    a: Unused --> right_align(width)[a]: Unused
`right_align(pad)[]` |
    a: A, pad: Pad --> right_align(pad)[a]: A
    a: Unused, pad: Pad --> right_align(pad)[a]: Unused
`right_align(pad, width)[]` |
    a: A, pad: Pad --> right_align(pad, width)[a]: A
    a: Unused, pad: Pad --> right_align(pad, width)[a]: Unused

###### Complexity

> The overall complexity of an alignment generator directive is defined by the complexity of its embedded and padding generator. The complexity of the left alignment directive generator itself is O(1). The complexity of the center and right alignment directive generators is O(N), where `N` is the number of characters emitted by the embedded and padding generators.

###### 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/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::left_align;
    using boost::spirit::karma::center;
    using boost::spirit::karma::right_align;

Basic usage of the alignment generators:

    std::pair<double, double> p (1.0, 2.0);
    test_generator_attr("1.0     |2.0", left_align(8)[double_] << '|' << double_, p);
    test_generator_attr("   1.0  |2.0", center(8)[double_] << '|' << double_, p);
    test_generator_attr("     1.0|2.0", right_align(8)[double_] << '|' << double_, p);