Generator Directives Controlling the Maximum Field Width (maxwidth[])

| Home | Libraries | People | FAQ | More

##### Generator Directives Controlling the Maximum Field Width (`maxwidth[]`)

###### Description

The `maxwidth[]` directive allows to limit (truncate) the overall length of the output generated by the embedded generator.

###### Header

    // forwards to <boost/spirit/home/karma/directive/maxwidth.hpp>
    #include <boost/spirit/include/karma_maxwidth.hpp>

Also, see Include Structure.

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

###### Model of

> `UnaryGenerator`

Notation

`a`

  A generator object

`A`

  Attribute type of the generator `a`

`num`

  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
--- | ---
`maxwidth[a]` | Limit the overall length of the emitted output of the embedded generator (including characters generated by automatic delimiting) to the number of characters as defined by the preprocessor constant `BOOST_KARMA_DEFAULT_FIELD_MAXWIDTH`. Any additional output is truncated. The directive succeeds as long as the embedded generator succeeded (unless the underlying output stream reports an error).
`maxwidth(num)[a]` | Limit the overall length of the emitted output of the embedded generator (including characters generated by automatic delimiting) to the number of characters as defined by `num`. Any additional output is truncated. The directive succeeds as long as the embedded generator succeeded (unless the underlying output stream reports an error).

| Note
The `maxwidth[]` generator directive does not pad the generated output to fill the specified column width. If the emitted output is shorter than the specified (or implied) column width, the generated output will be more narrow than the column width. If the output needs to always be equal to a specified column width, use one of the alignment directives `left-align[]`, `center[]`, or `right_align[]`, for instance:
    maxwidth(8)[left_align(8)["1234"]]
which will output: `"1234 "` (without the quotes).

###### Attributes

See Compound Attribute Notation.

Expression | Attribute
--- | ---
`maxwidth[a]` |
    a: A --> maxwidth[a]: A
    a: Unused --> maxwidth[a]: Unused
`maxwidth(num)[a]` |
    a: A --> maxwidth(num)[a]: A
    a: Unused --> maxwidth(num)[a]: Unused

###### Complexity

> The overall complexity of the generator directive `maxwidth[]` is defined by the complexity of its embedded generator. The complexity of the directive itself is O(N), where `N` is the number of characters generated by the maxwidth directive.

###### 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 <iostream>
    #include <string>

Some using declarations:

    using boost::spirit::karma::double_;
    using boost::spirit::karma::maxwidth;
    using boost::spirit::karma::left_align;
    using boost::spirit::karma::right_align;

Basic usage of `maxwidth` generator directive:

    test_generator("01234", maxwidth(5)["0123456789"]);
    test_generator("  012", maxwidth(5)[right_align(12)["0123456789"]]);
    test_generator("0123    ", maxwidth(8)[left_align(8)["0123"]]);