libs/spirit/doc/karma/numeric.qbk
[/==============================================================================
Copyright (C) 2001-2011 Hartmut Kaiser
Copyright (C) 2001-2011 Joel de Guzman
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
===============================================================================/]
[section:numeric Numeric Generators]
The library includes a couple of predefined objects for generating booleans,
signed and unsigned integers, and real numbers. These generators are fully
parametric. Most of the important aspects of numeric generation can be
finely adjusted to suit. This includes the radix base, the exponent, the
fraction etc. Policies control the real number generators' behavior. There are
some predefined policies covering the most common real number formats but the
user can supply her own when needed.
The numeric parsers are fine tuned (employing loop unrolling and
extensive template metaprogramming) with exceptional performance that
rivals the low level C functions such as `ltoa`, `ssprintf`, and `_gcvt`.
Benchmarks reveal up to 2X speed over the C counterparts (see here:
__sec_karma_numeric_performance__). This goes to show that you can write
extremely tight generic C++ code that rivals, if not surpasses C.
[heading Module Header]
// forwards to <boost/spirit/home/karma/numeric.hpp>
#include <boost/spirit/include/karma_numeric.hpp>
Also, see __include_structure__.
[/////////////////////////////////////////////////////////////////////////////]
[section:unsigned_int Unsigned Integer Number Generators (`uint_`, etc.)]
[heading Description]
The `uint_generator` class is the simplest among the members of the
numerics package. The `uint_generator` can generate unsigned integers of
arbitrary length and size. The `uint_generator` generator can be used to
generate ordinary primitive C/C++ integers or even user defined scalars such as
bigints (unlimited precision integers) if the type follows
certain expression requirements (for more information about the requirements, see
[link spirit.karma.reference.numeric.unsigned_int.additional_requirements below])).
The `uint_generator` is a template class. Template parameters fine tune its behavior.
[heading Header]
// forwards to <boost/spirit/home/karma/numeric/uint.hpp>
#include <boost/spirit/include/karma_uint.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::lit // alias: boost::spirit::karma::lit`]]
[[`boost::spirit::bin // alias: boost::spirit::karma::bin`]]
[[`boost::spirit::oct // alias: boost::spirit::karma::oct`]]
[[`boost::spirit::hex // alias: boost::spirit::karma::hex`]]
[[`boost::spirit::ushort_ // alias: boost::spirit::karma::ushort_`]]
[[`boost::spirit::ulong_ // alias: boost::spirit::karma::ulong_`]]
[[`boost::spirit::uint_ // alias: boost::spirit::karma::uint_`]]
[[`boost::spirit::ulong_long // alias: boost::spirit::karma::ulong_long`]]
]
[note The generators `ulong_long` and `ulong_long(num)` are only available on
platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
defined (i.e. on platforms having native support for `unsigned long long`
(64 bit) unsigned integer types).]
[note `lit` is reused by the [karma_string String Generators], the
__karma_char__, and the Numeric Generators. In
general, a char generator is created when you pass in a
character, a string generator is created when you pass in a string, and a
numeric generator is created when you use a numeric literal.]
[heading Synopsis]
template <
typename Num
, unsigned Radix>
struct uint_generator;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`Num`] [The numeric base type of the
numeric generator.] [`unsigned int`]]
[[`Radix`] [The radix base. This can be
any value in the (inclusive) range from `2` .. `36`.] [`10`]]
]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`num`] [Numeric literal, any unsigned integer value, or
a __karma_lazy_argument__ that evaluates to an
unsigned integer value of type `Num`]]
[[`Num`] [Type of `num`: any unsigned integer type, or in case
of a __karma_lazy_argument__, its return value]]
[[`Radix`] [An integer literal specifying the required radix for
the output conversion. Valid values are from the
(inclusive) range `2` .. `36`.]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.
[table
[[Expression] [Semantics]]
[[`lit(num)`] [Generate the unsigned integer literal `num` using the
default formatting (radix is `10`). This generator never
fails (unless the underlying output stream reports
an error).]]
[
[``ushort_
uint_
ulong_
ulong_long``] [Generate the unsigned integer provided by a mandatory
attribute using the default formatting (radix is `10`).
This generator never fails (unless the underlying
output stream reports an error).]]
[
[``ushort_(num)
uint_(num)
ulong_(num)
ulong_long(num)``] [Generate the unsigned integer provided by the
immediate literal value the generator is initialized
from using the default formatting (radix is `10`). If
this generator has an associated attribute it succeeds
only if the attribute is equal to the
immediate literal (unless the underlying output
stream reports an error). Otherwise this generator
fails and does not generate any output.]]
[
[``bin
oct
hex``] [Generate the unsigned integer provided by a mandatory
attribute using the default formatting and the
corresponding radix (`bin`: radix is `2`, `oct`: radix is `8`,
`hex`: radix is `16`). This generator never fails (unless
the underlying output stream reports an error).]]
[
[``bin(num)
oct(num)
hex(num)``] [Generate the unsigned integer provided by the
immediate literal value the generator is initialized
from using the default formatting and the
corresponding radix (`bin`: radix is `2`, `oct`:
radix is `8`, `hex`: radix is `16`). If
this generator has an associated attribute it succeeds
only if the attribute is equal to the
immediate literal (unless the underlying output
stream reports an error). Otherwise this generator
fails and does not generate any output.]]
]
All generators listed in the table above (except `lit(num)`) are predefined
specializations of the `uint_generator<Num, Radix>` basic unsigned integer
number generator type described below. It is possible to directly use this
type to create unsigned integer generators using a wide range of formatting
options.
[table
[[Expression] [Semantics]]
[
[``uint_generator<
Num, Radix
>()``]
[Generate the unsigned integer of type `Num` provided
by a mandatory attribute using the specified `Radix`
(allowed values are from the (inclusive) range from
`2` .. `36`, the
default value is `10`).This generator never fails
(unless the underlying output stream reports an
error).]]
[
[``uint_generator<
Num, Radix
>()(num)``]
[Generate the unsigned integer of type `Num` provided
by the immediate literal value the generator is
initialized from, using the specified `Radix`
(allowed values are from the (inclusive) range from
`2` .. `36`, the
default value is `10`). If this generator has an
associated attribute it succeeds only if the
attribute is equal to the immediate literal (unless
the underlying output stream reports an error).
Otherwise this generator fails and does not generate
any output.]]
]
[heading Additional Requirements]
The following lists enumerate the requirements which must be met in order to
use a certain type `Num` to instantiate and use a
`uint_generator<Num, Radix>`.
If `boost::is_integral<Num>::value` is `true` the type `Num` must have defined:
* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=`
* numeric operators for: `+`, `-`, `/`, `*`, and `%`
If `boost::is_integral<Num>::value` is `false` the type `Num` must have defined:
* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=`
* numeric operators for: `+`, `-`, `/`, `*`, and `%`
* helper functions implementing the interface and the semantics of: `std::fmod`,
`std::pow`, `std::lround`, `std::ltrunc`, `std::floor`, and `std::ceil`.
These need to be defined in a way so that they will be found using argument
dependent lookup (ADL).
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`lit(num)`] [__unused__]]
[[`ushort_`] [`unsigned short`, attribute is mandatory (otherwise
compilation will fail)]]
[[`ushort_(num)`] [`unsigned short`, attribute is optional, if it is
supplied, the generator compares the attribute with
`num` and succeeds only if both are equal, failing
otherwise.]]
[[`uint_`] [`unsigned int`, attribute is mandatory (otherwise
compilation will fail)]]
[[`uint_(num)`] [`unsigned int`, attribute is optional, if it is
supplied, the generator compares the attribute with
`num` and succeeds only if both are equal, failing
otherwise.]]
[[`ulong_`] [`unsigned long`, attribute is mandatory (otherwise
compilation will fail)]]
[[`ulong_(num)`] [`unsigned long`, attribute is optional, if it is
supplied, the generator compares the attribute with
`num` and succeeds only if both are equal, failing
otherwise.]]
[[`ulong_long`] [`unsigned long long`, attribute is mandatory
(otherwise compilation will fail)]]
[[`ulong_long(num)`][`unsigned long long`, attribute is optional, if it is
supplied, the generator compares the attribute with
`num` and succeeds only if both are equal, failing
otherwise.]]
[
[``bin
oct
hex``] [`unsigned int`, attribute is mandatory
(otherwise compilation will fail)]]
[
[``bin(num)
oct(num)
hex(num)``] [`unsigned int`, attribute is optional, if it is
supplied, the generator compares the attribute with
`num` and succeeds only if both are equal, failing
otherwise.]]
[
[``uint_generator<
Num, Radix
>()``] [`Num`, attribute is mandatory (otherwise compilation
will fail)]]
[
[``uint_generator<
Num, Radix
>()(num)``] [`Num`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
]
[note In addition to their usual attribute of type `Num` all listed generators
accept an instance of a `boost::optional<Num>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Num` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Complexity]
[:O(N), where `N` is the number of digits needed to represent the generated
integer number]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes]
Some using declarations:
[reference_karma_using_declarations_uint]
Basic usage of an `uint` generator:
[reference_karma_uint]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:signed_int Signed Integer Number Generators (`int_`, etc.)]
[heading Description]
The `int_generator` can generate signed integers of arbitrary length and size.
This is almost the same as the `uint_generator`. The only difference is the
additional task of generating the `'+'` or `'-'` sign preceding the number.
The class interface is the same as that of the `uint_generator`.
The `int_generator` generator can be used to emit ordinary primitive C/C++
integers or even user defined scalars such as bigints (unlimited
precision integers) if the type follows certain expression
requirements (for more information about the requirements, see
[link spirit.karma.reference.numeric.signed_int.additional_requirements below]).
[heading Header]
// forwards to <boost/spirit/home/karma/numeric/int.hpp>
#include <boost/spirit/include/karma_int.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::lit // alias: boost::spirit::karma::lit`]]
[[`boost::spirit::short_ // alias: boost::spirit::karma::short_`]]
[[`boost::spirit::int_ // alias: boost::spirit::karma::int_`]]
[[`boost::spirit::long_ // alias: boost::spirit::karma::long_`]]
[[`boost::spirit::long_long // alias: boost::spirit::karma::long_long`]]
]
[note The generators `long_long` and `long_long(num)` are only available on
platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is
defined (i.e. on platforms having native support for `long long`
(64 bit) integer types).]
[note `lit` is reused by the [karma_string String Generators], the
__karma_char__, and the Numeric Generators. In
general, a char generator is created when you pass in a
character, a string generator is created when you pass in a string, and a
numeric generator is created when you use a numeric literal.]
[heading Synopsis]
template <
typename T
, unsigned Radix
, bool force_sign>
struct int_generator;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`T`] [The numeric base type of the
numeric parser.] [`int`]]
[[`Radix`] [The radix base. This can be
either 2: binary, 8: octal,
10: decimal and 16: hexadecimal.] [`10`]]
[[`force_sign`] [If `true`, all numbers will
have a sign (space for zero)] [`false`]]
]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`num`] [Numeric literal, any signed integer value, or
a __karma_lazy_argument__ that evaluates to a signed
integer value of type `Num`]]
[[`Num`] [Type of `num`: any signed integer type]]
[[`Radix`] [A constant integer literal specifying the required
radix for the output conversion. Valid values are `2`,
`8`, `10`, and `16`.]]
[[`force_sign`] [A constant boolean literal specifying whether the
generated number should always have a sign (`'+'` for
positive numbers, `'-'` for negative numbers and a
'` `' for zero).]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.
[table
[[Expression] [Semantics]]
[[`lit(num)`] [Generate the integer literal `num` using the default
formatting (radix is `10`, sign is only printed for
negative literals). This generator never fails (unless
the underlying output stream reports an error).]]
[
[``short_
int_
long_
long_long``] [Generate the integer provided by a mandatory attribute
using the default formatting (radix is `10`, sign is
only printed for negative literals). This generator
never fails (unless the underlying output stream
reports an error).]]
[
[``short_(num)
int_(num)
long_(num)
long_long(num)``] [Generate the integer provided by the immediate literal
value the generator is initialized from using the
default formatting (radix is `10`, sign is only printed
for negative literals). If this generator has an
associated attribute it succeeds only if the
attribute is equal to the immediate literal (unless
the underlying output stream reports an error).
Otherwise this generator fails and does not generate
any output.]]
]
All generators listed in the table above (except `lit(num)`) are predefined
specializations of the `int_generator<Num, Radix, force_sign>` basic integer
number generator type described below. It is possible to directly use this
type to create integer generators using a wide range of formatting options.
[table
[[Expression] [Semantics]]
[
[``int_generator<
Num, Radix, force_sign
>()``]
[Generate the integer of type `Num` provided by a
mandatory attribute using the specified `Radix`
(possible values are `2`, `8`, `10`, and `16`, the
default value is `10`). If `force_sign` is `false`
(the default), a sign is only printed for negative
literals. If `force_sign` is `true`, all numbers will
be printed using a sign, i.e. `'-'` for negative
numbers, `'+'` for positive numbers, and `' '` for
zeros. This generator never fails (unless the
underlying output stream reports an error).]]
[
[``int_generator<
Num, Radix, force_sign
>()(num)``]
[Generate the integer of type `Num` provided by the
immediate literal value the generator is initialized
from, using the specified `Radix` (possible values are
`2`, `8`, `10`, and `16`, the default value is `10`).
If `force_sign` is `false` (the default), a sign is
only printed for negative literals. If `force_sign` is
`true`, all numbers will be printed using a sign, i.e.
`'-'` for negative numbers, `'+'` for positive numbers,
and `' '` for zeros. If this generator has an
associated attribute it succeeds only if the
attribute is equal to the immediate literal (unless
the underlying output stream reports an error).
Otherwise this generator fails and does not generate
any output.]]
]
[heading Additional Requirements]
The following lists enumerate the requirements which must be met in order to
use a certain type `Num` to instantiate and use a
`int_generator<Num, Radix, force_sign>`.
If `boost::is_integral<Num>::value` is `true` the type `Num` must have defined:
* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=`
* numeric operators for: `+`, `-`, `/`, `*`, `%`, and unary `-`
If `boost::is_integral<Num>::value` is `false` the type `Num` must have defined:
* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=`
* numeric operators for: `+`, `-`, `/`, `*`, `%`, and unary `-`
* helper functions implementing the interface and the semantics of: `std::fmod`,
`std::fabs`, `std::pow`, `std::lround`, `std::ltrunc`, `std::floor`, and
`std::ceil`. These need to be defined in a way so that they will be found
using argument dependent lookup (ADL).
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`lit(num)`] [__unused__]]
[[`short_`] [`short`, attribute is mandatory (otherwise compilation
will fail)]]
[[`short_(num)`] [`short`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
[[`int_`] [`int`, attribute is mandatory (otherwise compilation
will fail)]]
[[`int_(num)`] [`int`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
[[`long_`] [`long`, attribute is mandatory (otherwise compilation
will fail)]]
[[`long_(num)`] [`long`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
[[`long_long`] [`long long`, attribute is mandatory (otherwise compilation
will fail)]]
[[`long_long(num)`] [`long long`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
[
[``int_generator<
Num, Radix, force_sign
>()``] [`Num`, attribute is mandatory (otherwise compilation
will fail)]]
[
[``int_generator<
Num, Radix, force_sign
>()(num)``] [`Num`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
]
[note In addition to their usual attribute of type `Num` all listed generators
accept an instance of a `boost::optional<Num>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Num` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Complexity]
[:O(N), where `N` is the number of digits needed to represent the generated
integer number]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes]
Some using declarations:
[reference_karma_using_declarations_int]
Basic usage of an `int_` generator:
[reference_karma_int]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:real_number Real Number Generators (`float_`, `double_`, etc.)]
[heading Description]
The `real_generator` can generate real numbers of arbitrary length and size
limited by its template parameter, `Num`. The numeric base type `Num` can be
a user defined numeric type such as fixed_point (fixed point reals) and
bignum (unlimited precision numbers) if the type follows certain
expression requirements (for more information about the requirements, see
[link spirit.karma.reference.numeric.real_number.additional_requirements below]).
[heading Header]
// forwards to <boost/spirit/home/karma/numeric/real.hpp>
#include <boost/spirit/include/karma_real.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::lit // alias: boost::spirit::karma::lit`]]
[[`boost::spirit::float_ // alias: boost::spirit::karma::float_`]]
[[`boost::spirit::double_ // alias: boost::spirit::karma::double_`]]
[[`boost::spirit::long_double // alias: boost::spirit::karma::long_double`]]
]
[note `lit` is reused by the [karma_string String Generators], the
__karma_char__, and the Numeric Generators. In
general, a char generator is created when you pass in a
character, a string generator is created when you pass in a string, and a
numeric generator is created when you use a numeric literal.]
[heading Synopsis]
template <typename Num, typename RealPolicies>
struct real_generator;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`Num`] [The type of the real number to generate.] [`double`]]
[[`RealPolicies`] [The policies to use while
converting the real number.] [`real_policies<Num>`]]
]
For more information about the type `RealPolicies` see
[link spirit.karma.reference.numeric.real_number.real_number_formatting_policies below].
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`num`] [Numeric literal, any real number value, or
a __karma_lazy_argument__ that evaluates to a real
number value of type `Num`]]
[[`Num`] [Type of `num`: any real number type]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.
[table
[[Expression] [Semantics]]
[[`lit(num)`] [Generate the real number literal `num` using the
default formatting (no trailing zeros, `fixed`
representation for numbers `fabs(n) <= 1e5 && fabs(n) > 1e-3`,
scientific representation otherwise, 3 fractional digits,
sign is only printed for negative literals). This
generator never fails (unless the underlying output
stream reports an error).]]
[
[``float_
double_
long_double``] [Generate the real number provided by a
mandatory attribute using the default formatting (no
trailing zeros, `fixed` representation for numbers
`fabs(n) <= 1e5 && fabs(n) > 1e-3`, scientific
representation otherwise, 3 fractional digits,
sign is only printed for negative literals). This
generator never fails (unless the underlying output
stream reports an error).]]
[
[``float_(num)
double_(num)
long_double(num)``] [Generate the real point number provided by the
immediate literal value the generator is initialized
from using the default formatting (no trailing zeros,
`fixed` representation for numbers
`fabs(n) <= 1e5 && fabs(n) > 1e-3`, scientific
representation otherwise, 3 fractional digits, sign is
only printed for negative literals). If this generator
has an associated attribute it succeeds only if
the attribute is equal to the immediate literal (unless
the underlying output stream reports an error).
Otherwise this generator fails and does not generate
any output.]]
]
All generators listed in the table above (except `lit(num)`) are predefined
specializations of the `real_generator<Num, RealPolicies>` basic real
number generator type described below. It is possible to directly use this
type to create real number generators using a wide range of formatting
options.
[table
[[Expression] [Semantics]]
[
[``real_generator<
Num, RealPolicies
>()``]
[Generate the real number of type `Num`
provided by a mandatory attribute using the specified
`RealPolicies`. This generator never fails
(unless the underlying output stream reports an
error).]]
[
[``real_generator<
Num, RealPolicies
>()(num)``]
[Generate the real number of type `Num` provided by the
immediate literal value the generator is initialized
from using the specified `RealPolicies`.
If this generator has an associated attribute it
succeeds only if the attribute is equal to the
immediate literal (unless the underlying output stream
reports an error). Otherwise this generator fails and
does not generate any output.]]
]
[heading Additional Requirements]
The following list enumerates the requirements which must be met in order to
use a certain type `Num` to instantiate a `real_generator<Num, Policies>`.
In order to be usable as the first template parameter for `real_generator<>`
the type `Num` must have defined:
* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=`
* numeric operators for: `+`, `-`, `/`, `*`, and `%`
* functions implementing the interface and the semantics of: `std::fmod`,
`std::pow`, `std::log10`, `std::lround`, `std::ltrunc`, `std::modf`,
`std::floor`, and `std::ceil`. These need to be defined in a way so that they
will be found using argument dependent lookup (ADL).
* a valid specialization of the type `std::numeric_limits<Num>` allowing for
numeric property inspection.
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`lit(num)`] [__unused__]]
[[`float_`] [`float`, attribute is mandatory (otherwise compilation
will fail)]]
[[`float_(num)`] [`float_`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
[[`double_`] [`double`, attribute is mandatory (otherwise compilation
will fail)]]
[[`double_(num)`] [`double`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
[[`long_double`] [`long double`, attribute is mandatory (otherwise
compilation will fail)]]
[[`long_double(num)`][`long double`, attribute is optional, if it is supplied,
the generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
[
[``real_generator<
Num, Policies
>()``] [`Num`, attribute is mandatory (otherwise compilation
will fail)]]
[
[``real_generator<
Num, Policies
>()(num)``] [`Num`, attribute is optional, if it is supplied, the
generator compares the attribute with `num` and
succeeds only if both are equal, failing otherwise.]]
]
[note In addition to their usual attribute of type `Num` all listed generators
accept an instance of a `boost::optional<Num>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `Num` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Real Number Formatting Policies]
If special formatting of a real number is needed, overload
the policy class `real_policies<Num>` and use it as a template
parameter to the `real_generator<>` real number generator. For instance:
// define a new real number formatting policy
template <typename Num>
struct scientific_policy : real_policies<Num>
{
// we want the numbers always to be in scientific format
static int floatfield(Num n) { return fmtflags::scientific; }
};
// define a new generator type based on the new policy
typedef real_generator<double, scientific_policy<double> > science_type;
science_type const scientific = science_type();
// use the new generator
generate(sink, science_type(), 1.0); // will output: 1.0e00
generate(sink, scientific, 0.1); // will output: 1.0e-01
The template parameter `Num` should be the type to be formatted using the
overloaded policy type. At the same time `Num` will be used as the attribute
type of the created real number generator.
[heading Real Number Formatting Policy Expression Semantics]
A real number formatting policy should expose the following variables and
functions:
[table
[[Expression][Description]]
[ [``
template <typename Inserter
, typename OutputIterator
, typename Policies>
bool call (OutputIterator& sink, Num n
, Policies const& p);
``]
[This is the main function used to generate the output for a real
number. It is called by the real generator in order to perform the
conversion. In theory all of the work can be implemented here, but the
easiest way is to use existing functionality provided by the type specified
by the template parameter `Inserter`. The default implementation of this
functions is:
``
template <typename Inserter, typename OutputIterator
, typename Policies>
static bool
call (OutputIterator& sink, Num n, Policies const& p)
{
return Inserter::call_n(sink, n, p);
}
``
`sink` is the output iterator to use for generation
`n` is the real number to convert
`p` is the instance of the policy type used to instantiate this real
number generator.
]]
[ [``
bool force_sign(Num n);
``]
[The default behavior is to not to require generating a sign. If the function
`force_sign()` returns true, then all generated numbers will have a
sign (`'+'` or `'-'`, zeros will have a space instead of a sign).
`n` is the real number to output. This can be used to
adjust the required behavior depending on the value of this number.]]
[ [``
bool trailing_zeros(Num n);
``]
[Return whether trailing zero digits have to be emitted in the fractional
part of the output. If set, this flag instructs the real number
generator to emit trailing zeros up to the required precision digits (as
returned by the `precision()` function).
`n` is the real number to output. This can be used to
adjust the required behavior depending on the value of this number.]]
[ [``
int floatfield(Num n);
``]
[Decide, which representation type to use in the generated output.
By default all numbers having an absolute value of zero or in between
`0.001` and `100000` will be generated using the fixed format, all others
will be generated using the scientific representation.
The `trailing_zeros()` can be used to force the output of trailing zeros
in the fractional part up to the number of digits returned by the
`precision()` member function. The default is not to generate the trailing
zeros.
`n` is the real number to output. This can be used to
adjust the formatting flags depending on the value of
this number.
The return value has to be either `fmtflags::scientific` (generate real
number values in scientific notation) or `fmtflags::fixed` (generate
real number values in fixed-point notation).
]]
[ [``
unsigned precision(Num n);
``]
[Return the maximum number of decimal digits to generate in the
fractional part of the output.
`n` is the real number to output. This can be used to
adjust the required precision depending on the value of this number. If
the trailing zeros flag is specified the fractional part of the output will
be 'filled' with zeros, if appropriate.
*Note:* If the trailing_zeros flag is not in effect additional semantics
apply. See the description for the `fraction_part()` function below.
Moreover, this precision will be limited to the value of
`std::numeric_limits<T>::digits10 + 1`.]]
[ [``
template <typename OutputIterator>
bool integer_part(OutputIterator& sink
, Num n, bool sign, bool force_sign);
``]
[This function is called to generate the integer part of the real
number.
`sink` is the output iterator to use for generation
`n` is the absolute value of the integer part of the real
number to convert (always non-negative)
`sign` is the sign of the overall real number to convert.
`force_sign` is a flag indicating whether a sign has to be generated even for
non-negative numbers (this is the same as has been returned
from the function `force_sign()` described above)
The return value defines the outcome of the whole generator. If it is
`false`, no further output is generated, immediately returning `false` from
the calling `real_generator` as well. If it is `true`, normal output
generation continues.]]
[ [``
template <typename OutputIterator>
bool dot(OutputIterator& sink, Num n,
unsigned precision);
``]
[This function is called to generate the decimal point.
`sink` is the output iterator to use for generation
`n` is the fractional part of the real number to convert. Note
that this number is scaled such, that it represents the number of units
which correspond to the value returned from the `precision()` function
earlier. I.e. a fractional part of `0.01234` is represented as `1234`
when the function `precision()` returned `5`.
`precision` is the number of digits to emit as returned by the function
`precision()` described above
This is given to allow to decide, whether a decimal point has to be
generated at all.
*Note:* If the `trailing_zeros` flag is not in effect additional comments
apply. See the description for the `fraction_part()` function below.
The return value defines the outcome of the whole generator. If it is
`false`, no further output is generated, immediately returning `false` from
the calling `real_generator` as well. If it is `true`, normal output
generation continues.]]
[ [``
template <typename OutputIterator>
bool fraction_part(OutputIterator& sink, Num n
, unsigned adjprec, unsigned precision);
``]
[This function is called to generate the fractional part of the number.
`sink` is the output iterator to use for generation
`n` is the fractional part of the real number to convert. Note
that this number is scaled such, that it represents the number of units
which correspond to the value returned from the `precision()` function
earlier. I.e. a fractional part of `0.01234` is represented as `1234`
when the function `precision()` returned `5`.
`adjprec` is the corrected number of digits to emit (see note below)
`precision` is the number of digits to emit as returned by the function
`precision()` described above
*Note:* If `trailing_zeros()` returns `false` the `adjprec`
parameter will have been corrected from the value the `precision()`
function returned earlier (defining the maximal number of fractional
digits) in the sense, that it takes into account trailing zeros. I.e. a
real number `0.0123` and a value of `5` returned from
`precision()` will result in:
`trailing_zeros()` returned `false`: `n` will be `123`, and `adjprec`
will be `4` (as we need to print `0123`)
`trailing_zeros()` returned `true`: `n` will be `1230`, and `adjprec`
will be `5` (as we need to print `01230`)
The missing preceding zeros in the fractional part have to be supplied
by the implementation of this policy function.
The return value defines the outcome of the whole generator. If it is
`false`, no further output is generated, immediately returning `false` from
the calling `real_generator` as well. If it is `true`, normal output
generation continues.]]
[ [``
template <typename CharEncoding,
typename Tag, typename OutputIterator>
bool exponent(
OutputIterator& sink, long n);
``]
[This function is called to generate the exponential part of the number
(this is called only if the `floatfield()` function returned the
`fmtflags::scientific` flag).
`sink` is the output iterator to use for generation
`n` is the (signed) exponential part of the real number to convert.
The template parameters `CharEncoding` and `Tag` are either of the type
`unused_type` or describe the character class and conversion to be
applied to any output possibly influenced by either the `lower[]` or
`upper[]` directives.
The return value defines the outcome of the whole generator. If it is
`false`, no further output is generated, immediately returning `false` from
the calling `real_generator` as well. If it is `true`, normal output
generation continues.]]
[ [``
template <typename CharEncoding
, typename Tag, typename OutputIterator>
bool nan (OutputIterator& sink, Num n
, bool force_sign);
``]
[This function is called whenever the number to print is a non-normal
real number of type `NaN`.
`sink` is the output iterator to use for generation
`n` is the (signed) real number to convert
`force_sign` is a flag indicating whether a sign has to be generated even for
non-negative numbers (this is the same as has been returned from
the function `force_sign()` described above)
The template parameters `CharEncoding` and `Tag` are either of the type
`unused_type` or describe the character class and conversion to be
applied to any output possibly influenced by either the `lower[]` or
`upper[]` directives.
The return value defines the outcome of the whole generator. If it is
`false`, no further output is generated, immediately returning `false` from
the calling `real_generator` as well. If it is `true`, normal output
generation continues.]]
[ [``
template <typename CharEncoding
, typename Tag, typename OutputIterator>
bool inf (OutputIterator& sink, Num n
, bool force_sign);
``]
[This function is called whenever the number to print is a non-normal
real number of type `Inf`.
`sink` is the output iterator to use for generation
`n` is the (signed) real number to convert
`force_sign` is a flag indicating whether a sign has to be generated even for
non-negative numbers (this is the same as has been returned from
the function `force_sign()` described above)
The template parameters `CharEncoding` and `Tag` are either of the type
`unused_type` or describe the character class and conversion to be
applied to any output possibly influenced by either the `lower[]` or
`upper[]` directives.
The return value defines the outcome of the whole generator. If it is
`false`, no further output is generated, immediately returning `false` from
the calling `real_generator` as well. If it is `true`, normal output
generation continues.]]
]
[tip The easiest way to implement a proper real number formatting policy is
to derive a new type from the type `real_policies<>` while overriding
the aspects of the formatting which need to be changed.]
[heading Complexity]
[:O(N), where `N` is the number of digits needed to represent the generated
real number.]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes]
Some using declarations:
[reference_karma_using_declarations_real]
Basic usage of an `double_` generator:
[reference_karma_real]
[endsect]
[/////////////////////////////////////////////////////////////////////////////]
[section:boolean Boolean Generators (`bool_`)]
[heading Description]
As you might expect, the `bool_generator` can generate output from boolean
values. The `bool_generator` generator can be used to generate output from
ordinary primitive C/C++ `bool` values or user defined boolean types if
the type follows certain expression requirements (for more information about
the requirements, see
[link spirit.karma.reference.numeric.boolean.additional_requirements below])).
The `bool_generator` is a template class. Template parameters fine tune its
behavior.
[heading Header]
// forwards to <boost/spirit/home/karma/numeric/bool.hpp>
#include <boost/spirit/include/karma_bool.hpp>
Also, see __include_structure__.
[heading Namespace]
[table
[[Name]]
[[`boost::spirit::lit // alias: boost::spirit::karma::lit`]]
[[`boost::spirit::bool_ // alias: boost::spirit::karma::bool_`]]
[[`boost::spirit::true_ // alias: boost::spirit::karma::true_`]]
[[`boost::spirit::false_ // alias: boost::spirit::karma::false_`]]
]
[note `lit` is reused by the [karma_string String Generators], the
__karma_char__, and the Numeric Generators. In
general, a char generator is created when you pass in a
character, a string generator is created when you pass in a string, and a
numeric generator is created when you use a numeric (boolean) literal.]
[heading Synopsis]
template <
typename B
, unsigned Policies>
struct bool_generator;
[heading Template parameters]
[table
[[Parameter] [Description] [Default]]
[[`B`] [The boolean base type of the
boolean generator.] [`bool`]]
[[`Policies`] [The policies to use while
converting the boolean.] [`bool_policies<B>`]]
]
[heading Model of]
[:__primitive_generator_concept__]
[variablelist Notation
[[`b`] [Boolean literal, or a __karma_lazy_argument__ that
evaluates to a boolean value of type `B`]]
[[`B`] [Type of `b`: any type usable as a boolean, or in case
of a __karma_lazy_argument__, its return value]]
]
[heading Expression Semantics]
Semantics of an expression is defined only where it differs from, or is
not defined in __primitive_generator_concept__.
[table
[[Expression] [Semantics]]
[[`lit(b)`] [Generate the boolean literal `b` using the default
formatting (`false` is generated as `"false"`, and
`true` is generated as `"true"`). This generator never
fails (unless the underlying output stream reports an error).]]
[[`bool_`] [Generate the boolean value provided by a mandatory
attribute using the default formatting (`false` is
generated as `"false"`, and `true` is generated as
`"true"`). This generator never fails (unless the
underlying output stream reports an error).]]
[[`bool_(b)`] [Generate the boolean value provided by the
immediate literal value the generator is initialized
from using the default formatting (`false` is
generated as `"false"`, and `true` is generated as
`"true"`). If this generator has an associated
attribute it succeeds only if the attribute
is equal to the immediate literal (unless the
underlying output stream reports an error). Otherwise
this generator fails and does not generate any output.]]
[[`true_`] [Generate `"true"`. If this generator has an associated
attribute it succeeds only if the attribute
is `true` as well (unless the underlying output stream
reports an error).]]
[[`false_`] [Generate `"false"`. If this generator has an associated
attribute it succeeds only if the attribute
is `false` as well (unless the underlying output stream
reports an error).]]
]
All generators listed in the table above (except `lit(num)`) are predefined
specializations of the `bool_generator<B, Policies>` basic boolean generator
type described below. It is possible to directly use this type to create
boolean generators using a wide range of formatting options.
[table
[[Expression] [Semantics]]
[
[``bool_generator<
B, Policies
>()``] [Generate the boolean of type `B` provided
by a mandatory attribute using the specified `Policies`
This generator never fails (unless the underlying
output stream reports an error).]]
[
[``bool_generator<
B, Policies
>()(b)``] [Generate the boolean of type `B` provided
by the immediate literal value the generator is
initialized from, using the specified `Policies`. If
this generator has an associated attribute it succeeds
only if the attribute is equal to the
immediate literal (unless the underlying output
stream reports an error). Otherwise this generator
fails and does not generate any output.]]
]
[note All boolean generators properly respect the [karma_upperlower `upper`]
and [karma_upperlower `lower`] directives.]
[heading Additional Requirements]
The following lists enumerate the requirements which must be met in order to
use a certain type `B` to instantiate and use a `bool_generator<B, Policies>`.
The type `B`:
* must be (safely) convertible to `bool`
[heading Attributes]
[table
[[Expression] [Attribute]]
[[`bool_(b)`] [__unused__]]
[[`bool_`] [`bool`, attribute is mandatory (otherwise
compilation will fail)]]
[[`bool_(b)`] [`bool`, attribute is optional, if it is
supplied, the generator compares the attribute with
`b` and succeeds only if both are equal, failing
otherwise.]]
[
[``bool_generator<
B, Policies
>()``] [`B`, attribute is mandatory (otherwise compilation
will fail)]]
[
[``bool_generator<
B, Policies
>()(b)``] [`B`, attribute is optional, if it is supplied, the
generator compares the attribute with `b` and
succeeds only if both are equal, failing otherwise.]]
]
[note In addition to their usual attribute of type `B` all listed generators
accept an instance of a `boost::optional<B>` as well. If the
`boost::optional<>` is initialized (holds a value) the generators behave
as if their attribute was an instance of `B` and emit the value stored
in the `boost::optional<>`. Otherwise the generators will fail.]
[heading Boolean Formatting Policies]
If special formatting of a boolean is needed, overload
the policy class `bool_policies<B>` and use it as a template
parameter to the `bool_generator<>` boolean generator. For instance:
struct special_bool_policy : karma::bool_policies<>
{
template <typename CharEncoding, typename Tag
, typename OutputIterator>
static bool generate_false(OutputIterator& sink, bool b)
{
// we want to spell the names of false as eurt (true backwards)
return string_inserter<CharEncoding, Tag>::call(sink, "eurt");
}
};
typedef karma::bool_generator<special_bool_policy> backwards_bool_type;
backwards_bool_type const backwards_bool;
karma::generate(sink, backwards_bool, true); // will output: true
karma::generate(sink, backwards_bool(false)); // will output: uert
The template parameter `B` should be the type to be formatted using the
overloaded policy type. At the same time `B` will be used as the attribute
type of the created real number generator. The default for `B` is `bool`.
[heading Boolean Formatting Policy Expression Semantics]
A boolean formatting policy should expose the following:
[table
[[Expression][Description]]
[ [``
template <typename Inserter
, typename OutputIterator
, typename Policies>
bool call (OutputIterator& sink, Num n
, Policies const& p);
``]
[This is the main function used to generate the output for a boolean.
It is called by the boolean generator in order to perform the
conversion. In theory all of the work can be implemented here, but the
easiest way is to use existing functionality provided by the type specified
by the template parameter `Inserter`. The default implementation of this
functions is:
``
template <typename Inserter, typename OutputIterator
, typename Policies>
static bool
call (OutputIterator& sink, B b, Policies const& p)
{
return Inserter::call_n(sink, b, p);
}
``
`sink` is the output iterator to use for generation
`b` is the boolean to convert
`p` is the instance of the policy type used to instantiate this real
number generator.
]]
[ [``
template <typename CharEncoding,
typename Tag, typename OutputIterator>
bool generate_false(
OutputIterator& sink, B b);
``]
[This function is called to generate the boolean if it is `false`.
`sink` is the output iterator to use for generation
`b` is the boolean to convert (the value is `false`).
The template parameters `CharEncoding` and `Tag` are either of the type
`unused_type` or describe the character class and conversion to be
applied to any output possibly influenced by either the `lower[]` or
`upper[]` directives.
The return value defines the outcome of the whole generator. ]]
[ [``
template <typename CharEncoding,
typename Tag, typename OutputIterator>
bool generate_true(
OutputIterator& sink, B b);
``]
[This function is called to generate the boolean if it is `true`.
`sink` is the output iterator to use for generation
`b` is the boolean to convert (the value is `true`).
The template parameters `CharEncoding` and `Tag` are either of the type
`unused_type` or describe the character class and conversion to be
applied to any output possibly influenced by either the `lower[]` or
`upper[]` directives.
The return value defines the outcome of the whole generator. ]]
]
[heading Complexity]
[:O(N), where `N` is the number of characters needed to represent the generated
boolean.]
[heading Example]
[note The test harness for the example(s) below is presented in the
__karma_basics_examples__ section.]
Some includes:
[reference_karma_includes]
Some using declarations:
[reference_karma_using_declarations_bool]
Basic usage of an `bool_` generator:
[reference_karma_bool]
[endsect]
[endsect]
