[/============================================================================== 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 #include 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 #include 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` 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`. If `boost::is_integral::value` is `true` the type `Num` must have defined: * comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=` * numeric operators for: `+`, `-`, `/`, `*`, and `%` If `boost::is_integral::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` 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 #include 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` 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`. If `boost::is_integral::value` is `true` the type `Num` must have defined: * comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=` * numeric operators for: `+`, `-`, `/`, `*`, `%`, and unary `-` If `boost::is_integral::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` 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 #include 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 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`]] ] 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` 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`. 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` 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` 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` and use it as a template parameter to the `real_generator<>` real number generator. For instance: // define a new real number formatting policy template struct scientific_policy : real_policies { // 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 > 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 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 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::digits10 + 1`.]] [ [`` template 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 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 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 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 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 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 #include 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`]] ] [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` 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`. 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` 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` and use it as a template parameter to the `bool_generator<>` boolean generator. For instance: struct special_bool_policy : karma::bool_policies<> { template static bool generate_false(OutputIterator& sink, bool b) { // we want to spell the names of false as eurt (true backwards) return string_inserter::call(sink, "eurt"); } }; typedef karma::bool_generator 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 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 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 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 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]