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

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.

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
`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).

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);

Boost C++ Libraries