1[/============================================================================== 2 Copyright (C) 2001-2011 Hartmut Kaiser 3 Copyright (C) 2001-2011 Joel de Guzman 4 5 Distributed under the Boost Software License, Version 1.0. (See accompanying 6 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 7===============================================================================/] 8 9[section:numeric Numeric Generators] 10 11The library includes a couple of predefined objects for generating booleans, 12signed and unsigned integers, and real numbers. These generators are fully 13parametric. Most of the important aspects of numeric generation can be 14finely adjusted to suit. This includes the radix base, the exponent, the 15fraction etc. Policies control the real number generators' behavior. There are 16some predefined policies covering the most common real number formats but the 17user can supply her own when needed. 18 19The numeric parsers are fine tuned (employing loop unrolling and 20extensive template metaprogramming) with exceptional performance that 21rivals the low level C functions such as `ltoa`, `ssprintf`, and `_gcvt`. 22Benchmarks reveal up to 2X speed over the C counterparts (see here: 23__sec_karma_numeric_performance__). This goes to show that you can write 24extremely tight generic C++ code that rivals, if not surpasses C. 25 26[heading Module Header] 27 28 // forwards to <boost/spirit/home/karma/numeric.hpp> 29 #include <boost/spirit/include/karma_numeric.hpp> 30 31Also, see __include_structure__. 32 33[/////////////////////////////////////////////////////////////////////////////] 34[section:unsigned_int Unsigned Integer Number Generators (`uint_`, etc.)] 35 36[heading Description] 37 38The `uint_generator` class is the simplest among the members of the 39numerics package. The `uint_generator` can generate unsigned integers of 40arbitrary length and size. The `uint_generator` generator can be used to 41generate ordinary primitive C/C++ integers or even user defined scalars such as 42bigints (unlimited precision integers) if the type follows 43certain expression requirements (for more information about the requirements, see 44[link spirit.karma.reference.numeric.unsigned_int.additional_requirements below])). 45The `uint_generator` is a template class. Template parameters fine tune its behavior. 46 47[heading Header] 48 49 // forwards to <boost/spirit/home/karma/numeric/uint.hpp> 50 #include <boost/spirit/include/karma_uint.hpp> 51 52Also, see __include_structure__. 53 54[heading Namespace] 55 56[table 57 [[Name]] 58 [[`boost::spirit::lit // alias: boost::spirit::karma::lit`]] 59 [[`boost::spirit::bin // alias: boost::spirit::karma::bin`]] 60 [[`boost::spirit::oct // alias: boost::spirit::karma::oct`]] 61 [[`boost::spirit::hex // alias: boost::spirit::karma::hex`]] 62 [[`boost::spirit::ushort_ // alias: boost::spirit::karma::ushort_`]] 63 [[`boost::spirit::ulong_ // alias: boost::spirit::karma::ulong_`]] 64 [[`boost::spirit::uint_ // alias: boost::spirit::karma::uint_`]] 65 [[`boost::spirit::ulong_long // alias: boost::spirit::karma::ulong_long`]] 66] 67 68[note The generators `ulong_long` and `ulong_long(num)` are only available on 69 platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is 70 defined (i.e. on platforms having native support for `unsigned long long` 71 (64 bit) unsigned integer types).] 72 73[note `lit` is reused by the [karma_string String Generators], the 74 __karma_char__, and the Numeric Generators. In 75 general, a char generator is created when you pass in a 76 character, a string generator is created when you pass in a string, and a 77 numeric generator is created when you use a numeric literal.] 78 79[heading Synopsis] 80 81 template < 82 typename Num 83 , unsigned Radix> 84 struct uint_generator; 85 86[heading Template parameters] 87 88[table 89 [[Parameter] [Description] [Default]] 90 [[`Num`] [The numeric base type of the 91 numeric generator.] [`unsigned int`]] 92 [[`Radix`] [The radix base. This can be 93 any value in the (inclusive) range from `2` .. `36`.] [`10`]] 94] 95 96[heading Model of] 97 98[:__primitive_generator_concept__] 99 100[variablelist Notation 101 [[`num`] [Numeric literal, any unsigned integer value, or 102 a __karma_lazy_argument__ that evaluates to an 103 unsigned integer value of type `Num`]] 104 [[`Num`] [Type of `num`: any unsigned integer type, or in case 105 of a __karma_lazy_argument__, its return value]] 106 [[`Radix`] [An integer literal specifying the required radix for 107 the output conversion. Valid values are from the 108 (inclusive) range `2` .. `36`.]] 109] 110 111[heading Expression Semantics] 112 113Semantics of an expression is defined only where it differs from, or is 114not defined in __primitive_generator_concept__. 115 116[table 117 [[Expression] [Semantics]] 118 [[`lit(num)`] [Generate the unsigned integer literal `num` using the 119 default formatting (radix is `10`). This generator never 120 fails (unless the underlying output stream reports 121 an error).]] 122 [ 123[``ushort_ 124uint_ 125ulong_ 126ulong_long``] [Generate the unsigned integer provided by a mandatory 127 attribute using the default formatting (radix is `10`). 128 This generator never fails (unless the underlying 129 output stream reports an error).]] 130 [ 131[``ushort_(num) 132uint_(num) 133ulong_(num) 134ulong_long(num)``] [Generate the unsigned integer provided by the 135 immediate literal value the generator is initialized 136 from using the default formatting (radix is `10`). If 137 this generator has an associated attribute it succeeds 138 only if the attribute is equal to the 139 immediate literal (unless the underlying output 140 stream reports an error). Otherwise this generator 141 fails and does not generate any output.]] 142 [ 143[``bin 144oct 145hex``] [Generate the unsigned integer provided by a mandatory 146 attribute using the default formatting and the 147 corresponding radix (`bin`: radix is `2`, `oct`: radix is `8`, 148 `hex`: radix is `16`). This generator never fails (unless 149 the underlying output stream reports an error).]] 150 [ 151[``bin(num) 152oct(num) 153hex(num)``] [Generate the unsigned integer provided by the 154 immediate literal value the generator is initialized 155 from using the default formatting and the 156 corresponding radix (`bin`: radix is `2`, `oct`: 157 radix is `8`, `hex`: radix is `16`). If 158 this generator has an associated attribute it succeeds 159 only if the attribute is equal to the 160 immediate literal (unless the underlying output 161 stream reports an error). Otherwise this generator 162 fails and does not generate any output.]] 163] 164 165All generators listed in the table above (except `lit(num)`) are predefined 166specializations of the `uint_generator<Num, Radix>` basic unsigned integer 167number generator type described below. It is possible to directly use this 168type to create unsigned integer generators using a wide range of formatting 169options. 170 171[table 172 [[Expression] [Semantics]] 173 [ 174[``uint_generator< 175 Num, Radix 176>()``] 177 [Generate the unsigned integer of type `Num` provided 178 by a mandatory attribute using the specified `Radix` 179 (allowed values are from the (inclusive) range from 180 `2` .. `36`, the 181 default value is `10`).This generator never fails 182 (unless the underlying output stream reports an 183 error).]] 184 [ 185[``uint_generator< 186 Num, Radix 187>()(num)``] 188 [Generate the unsigned integer of type `Num` provided 189 by the immediate literal value the generator is 190 initialized from, using the specified `Radix` 191 (allowed values are from the (inclusive) range from 192 `2` .. `36`, the 193 default value is `10`). If this generator has an 194 associated attribute it succeeds only if the 195 attribute is equal to the immediate literal (unless 196 the underlying output stream reports an error). 197 Otherwise this generator fails and does not generate 198 any output.]] 199] 200 201[heading Additional Requirements] 202 203The following lists enumerate the requirements which must be met in order to 204use a certain type `Num` to instantiate and use a 205`uint_generator<Num, Radix>`. 206 207If `boost::is_integral<Num>::value` is `true` the type `Num` must have defined: 208 209* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=` 210* numeric operators for: `+`, `-`, `/`, `*`, and `%` 211 212If `boost::is_integral<Num>::value` is `false` the type `Num` must have defined: 213 214* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=` 215* numeric operators for: `+`, `-`, `/`, `*`, and `%` 216* helper functions implementing the interface and the semantics of: `std::fmod`, 217 `std::pow`, `std::lround`, `std::ltrunc`, `std::floor`, and `std::ceil`. 218 These need to be defined in a way so that they will be found using argument 219 dependent lookup (ADL). 220 221[heading Attributes] 222 223[table 224 [[Expression] [Attribute]] 225 [[`lit(num)`] [__unused__]] 226 [[`ushort_`] [`unsigned short`, attribute is mandatory (otherwise 227 compilation will fail)]] 228 [[`ushort_(num)`] [`unsigned short`, attribute is optional, if it is 229 supplied, the generator compares the attribute with 230 `num` and succeeds only if both are equal, failing 231 otherwise.]] 232 233 [[`uint_`] [`unsigned int`, attribute is mandatory (otherwise 234 compilation will fail)]] 235 [[`uint_(num)`] [`unsigned int`, attribute is optional, if it is 236 supplied, the generator compares the attribute with 237 `num` and succeeds only if both are equal, failing 238 otherwise.]] 239 240 [[`ulong_`] [`unsigned long`, attribute is mandatory (otherwise 241 compilation will fail)]] 242 [[`ulong_(num)`] [`unsigned long`, attribute is optional, if it is 243 supplied, the generator compares the attribute with 244 `num` and succeeds only if both are equal, failing 245 otherwise.]] 246 247 [[`ulong_long`] [`unsigned long long`, attribute is mandatory 248 (otherwise compilation will fail)]] 249 [[`ulong_long(num)`][`unsigned long long`, attribute is optional, if it is 250 supplied, the generator compares the attribute with 251 `num` and succeeds only if both are equal, failing 252 otherwise.]] 253 254 [ 255[``bin 256oct 257hex``] [`unsigned int`, attribute is mandatory 258 (otherwise compilation will fail)]] 259 [ 260[``bin(num) 261oct(num) 262hex(num)``] [`unsigned int`, attribute is optional, if it is 263 supplied, the generator compares the attribute with 264 `num` and succeeds only if both are equal, failing 265 otherwise.]] 266 267 [ 268[``uint_generator< 269 Num, Radix 270>()``] [`Num`, attribute is mandatory (otherwise compilation 271 will fail)]] 272 [ 273[``uint_generator< 274 Num, Radix 275>()(num)``] [`Num`, attribute is optional, if it is supplied, the 276 generator compares the attribute with `num` and 277 succeeds only if both are equal, failing otherwise.]] 278] 279 280[note In addition to their usual attribute of type `Num` all listed generators 281 accept an instance of a `boost::optional<Num>` as well. If the 282 `boost::optional<>` is initialized (holds a value) the generators behave 283 as if their attribute was an instance of `Num` and emit the value stored 284 in the `boost::optional<>`. Otherwise the generators will fail.] 285 286[heading Complexity] 287 288[:O(N), where `N` is the number of digits needed to represent the generated 289 integer number] 290 291[heading Example] 292 293[note The test harness for the example(s) below is presented in the 294 __karma_basics_examples__ section.] 295 296Some includes: 297 298[reference_karma_includes] 299 300Some using declarations: 301 302[reference_karma_using_declarations_uint] 303 304Basic usage of an `uint` generator: 305 306[reference_karma_uint] 307 308[endsect] 309 310[/////////////////////////////////////////////////////////////////////////////] 311[section:signed_int Signed Integer Number Generators (`int_`, etc.)] 312 313[heading Description] 314 315The `int_generator` can generate signed integers of arbitrary length and size. 316This is almost the same as the `uint_generator`. The only difference is the 317additional task of generating the `'+'` or `'-'` sign preceding the number. 318The class interface is the same as that of the `uint_generator`. 319 320The `int_generator` generator can be used to emit ordinary primitive C/C++ 321integers or even user defined scalars such as bigints (unlimited 322precision integers) if the type follows certain expression 323requirements (for more information about the requirements, see 324[link spirit.karma.reference.numeric.signed_int.additional_requirements below]). 325 326[heading Header] 327 328 // forwards to <boost/spirit/home/karma/numeric/int.hpp> 329 #include <boost/spirit/include/karma_int.hpp> 330 331Also, see __include_structure__. 332 333[heading Namespace] 334 335[table 336 [[Name]] 337 [[`boost::spirit::lit // alias: boost::spirit::karma::lit`]] 338 [[`boost::spirit::short_ // alias: boost::spirit::karma::short_`]] 339 [[`boost::spirit::int_ // alias: boost::spirit::karma::int_`]] 340 [[`boost::spirit::long_ // alias: boost::spirit::karma::long_`]] 341 [[`boost::spirit::long_long // alias: boost::spirit::karma::long_long`]] 342] 343 344[note The generators `long_long` and `long_long(num)` are only available on 345 platforms where the preprocessor constant `BOOST_HAS_LONG_LONG` is 346 defined (i.e. on platforms having native support for `long long` 347 (64 bit) integer types).] 348 349[note `lit` is reused by the [karma_string String Generators], the 350 __karma_char__, and the Numeric Generators. In 351 general, a char generator is created when you pass in a 352 character, a string generator is created when you pass in a string, and a 353 numeric generator is created when you use a numeric literal.] 354 355[heading Synopsis] 356 357 template < 358 typename T 359 , unsigned Radix 360 , bool force_sign> 361 struct int_generator; 362 363[heading Template parameters] 364 365[table 366 [[Parameter] [Description] [Default]] 367 [[`T`] [The numeric base type of the 368 numeric parser.] [`int`]] 369 [[`Radix`] [The radix base. This can be 370 either 2: binary, 8: octal, 371 10: decimal and 16: hexadecimal.] [`10`]] 372 [[`force_sign`] [If `true`, all numbers will 373 have a sign (space for zero)] [`false`]] 374] 375 376[heading Model of] 377 378[:__primitive_generator_concept__] 379 380[variablelist Notation 381 [[`num`] [Numeric literal, any signed integer value, or 382 a __karma_lazy_argument__ that evaluates to a signed 383 integer value of type `Num`]] 384 [[`Num`] [Type of `num`: any signed integer type]] 385 [[`Radix`] [A constant integer literal specifying the required 386 radix for the output conversion. Valid values are `2`, 387 `8`, `10`, and `16`.]] 388 [[`force_sign`] [A constant boolean literal specifying whether the 389 generated number should always have a sign (`'+'` for 390 positive numbers, `'-'` for negative numbers and a 391 '` `' for zero).]] 392 ] 393 394[heading Expression Semantics] 395 396Semantics of an expression is defined only where it differs from, or is 397not defined in __primitive_generator_concept__. 398 399[table 400 [[Expression] [Semantics]] 401 [[`lit(num)`] [Generate the integer literal `num` using the default 402 formatting (radix is `10`, sign is only printed for 403 negative literals). This generator never fails (unless 404 the underlying output stream reports an error).]] 405 [ 406[``short_ 407int_ 408long_ 409long_long``] [Generate the integer provided by a mandatory attribute 410 using the default formatting (radix is `10`, sign is 411 only printed for negative literals). This generator 412 never fails (unless the underlying output stream 413 reports an error).]] 414 [ 415[``short_(num) 416int_(num) 417long_(num) 418long_long(num)``] [Generate the integer provided by the immediate literal 419 value the generator is initialized from using the 420 default formatting (radix is `10`, sign is only printed 421 for negative literals). If this generator has an 422 associated attribute it succeeds only if the 423 attribute is equal to the immediate literal (unless 424 the underlying output stream reports an error). 425 Otherwise this generator fails and does not generate 426 any output.]] 427] 428 429All generators listed in the table above (except `lit(num)`) are predefined 430specializations of the `int_generator<Num, Radix, force_sign>` basic integer 431number generator type described below. It is possible to directly use this 432type to create integer generators using a wide range of formatting options. 433 434[table 435 [[Expression] [Semantics]] 436 [ 437[``int_generator< 438 Num, Radix, force_sign 439>()``] 440 [Generate the integer of type `Num` provided by a 441 mandatory attribute using the specified `Radix` 442 (possible values are `2`, `8`, `10`, and `16`, the 443 default value is `10`). If `force_sign` is `false` 444 (the default), a sign is only printed for negative 445 literals. If `force_sign` is `true`, all numbers will 446 be printed using a sign, i.e. `'-'` for negative 447 numbers, `'+'` for positive numbers, and `' '` for 448 zeros. This generator never fails (unless the 449 underlying output stream reports an error).]] 450 [ 451[``int_generator< 452 Num, Radix, force_sign 453>()(num)``] 454 [Generate the integer of type `Num` provided by the 455 immediate literal value the generator is initialized 456 from, using the specified `Radix` (possible values are 457 `2`, `8`, `10`, and `16`, the default value is `10`). 458 If `force_sign` is `false` (the default), a sign is 459 only printed for negative literals. If `force_sign` is 460 `true`, all numbers will be printed using a sign, i.e. 461 `'-'` for negative numbers, `'+'` for positive numbers, 462 and `' '` for zeros. If this generator has an 463 associated attribute it succeeds only if the 464 attribute is equal to the immediate literal (unless 465 the underlying output stream reports an error). 466 Otherwise this generator fails and does not generate 467 any output.]] 468] 469 470[heading Additional Requirements] 471 472The following lists enumerate the requirements which must be met in order to 473use a certain type `Num` to instantiate and use a 474`int_generator<Num, Radix, force_sign>`. 475 476If `boost::is_integral<Num>::value` is `true` the type `Num` must have defined: 477 478* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=` 479* numeric operators for: `+`, `-`, `/`, `*`, `%`, and unary `-` 480 481If `boost::is_integral<Num>::value` is `false` the type `Num` must have defined: 482 483* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=` 484* numeric operators for: `+`, `-`, `/`, `*`, `%`, and unary `-` 485* helper functions implementing the interface and the semantics of: `std::fmod`, 486 `std::fabs`, `std::pow`, `std::lround`, `std::ltrunc`, `std::floor`, and 487 `std::ceil`. These need to be defined in a way so that they will be found 488 using argument dependent lookup (ADL). 489 490[heading Attributes] 491 492[table 493 [[Expression] [Attribute]] 494 [[`lit(num)`] [__unused__]] 495 [[`short_`] [`short`, attribute is mandatory (otherwise compilation 496 will fail)]] 497 [[`short_(num)`] [`short`, attribute is optional, if it is supplied, the 498 generator compares the attribute with `num` and 499 succeeds only if both are equal, failing otherwise.]] 500 501 [[`int_`] [`int`, attribute is mandatory (otherwise compilation 502 will fail)]] 503 [[`int_(num)`] [`int`, attribute is optional, if it is supplied, the 504 generator compares the attribute with `num` and 505 succeeds only if both are equal, failing otherwise.]] 506 507 [[`long_`] [`long`, attribute is mandatory (otherwise compilation 508 will fail)]] 509 [[`long_(num)`] [`long`, attribute is optional, if it is supplied, the 510 generator compares the attribute with `num` and 511 succeeds only if both are equal, failing otherwise.]] 512 513 [[`long_long`] [`long long`, attribute is mandatory (otherwise compilation 514 will fail)]] 515 [[`long_long(num)`] [`long long`, attribute is optional, if it is supplied, the 516 generator compares the attribute with `num` and 517 succeeds only if both are equal, failing otherwise.]] 518 519 [ 520[``int_generator< 521 Num, Radix, force_sign 522>()``] [`Num`, attribute is mandatory (otherwise compilation 523 will fail)]] 524 [ 525[``int_generator< 526 Num, Radix, force_sign 527>()(num)``] [`Num`, attribute is optional, if it is supplied, the 528 generator compares the attribute with `num` and 529 succeeds only if both are equal, failing otherwise.]] 530] 531 532[note In addition to their usual attribute of type `Num` all listed generators 533 accept an instance of a `boost::optional<Num>` as well. If the 534 `boost::optional<>` is initialized (holds a value) the generators behave 535 as if their attribute was an instance of `Num` and emit the value stored 536 in the `boost::optional<>`. Otherwise the generators will fail.] 537 538[heading Complexity] 539 540[:O(N), where `N` is the number of digits needed to represent the generated 541 integer number] 542 543[heading Example] 544 545[note The test harness for the example(s) below is presented in the 546 __karma_basics_examples__ section.] 547 548Some includes: 549 550[reference_karma_includes] 551 552Some using declarations: 553 554[reference_karma_using_declarations_int] 555 556Basic usage of an `int_` generator: 557 558[reference_karma_int] 559 560[endsect] 561 562[/////////////////////////////////////////////////////////////////////////////] 563[section:real_number Real Number Generators (`float_`, `double_`, etc.)] 564 565[heading Description] 566 567The `real_generator` can generate real numbers of arbitrary length and size 568limited by its template parameter, `Num`. The numeric base type `Num` can be 569a user defined numeric type such as fixed_point (fixed point reals) and 570bignum (unlimited precision numbers) if the type follows certain 571expression requirements (for more information about the requirements, see 572[link spirit.karma.reference.numeric.real_number.additional_requirements below]). 573 574[heading Header] 575 576 // forwards to <boost/spirit/home/karma/numeric/real.hpp> 577 #include <boost/spirit/include/karma_real.hpp> 578 579Also, see __include_structure__. 580 581[heading Namespace] 582 583[table 584 [[Name]] 585 [[`boost::spirit::lit // alias: boost::spirit::karma::lit`]] 586 [[`boost::spirit::float_ // alias: boost::spirit::karma::float_`]] 587 [[`boost::spirit::double_ // alias: boost::spirit::karma::double_`]] 588 [[`boost::spirit::long_double // alias: boost::spirit::karma::long_double`]] 589] 590 591[note `lit` is reused by the [karma_string String Generators], the 592 __karma_char__, and the Numeric Generators. In 593 general, a char generator is created when you pass in a 594 character, a string generator is created when you pass in a string, and a 595 numeric generator is created when you use a numeric literal.] 596 597[heading Synopsis] 598 599 template <typename Num, typename RealPolicies> 600 struct real_generator; 601 602[heading Template parameters] 603 604[table 605 [[Parameter] [Description] [Default]] 606 [[`Num`] [The type of the real number to generate.] [`double`]] 607 [[`RealPolicies`] [The policies to use while 608 converting the real number.] [`real_policies<Num>`]] 609] 610 611For more information about the type `RealPolicies` see 612[link spirit.karma.reference.numeric.real_number.real_number_formatting_policies below]. 613 614[heading Model of] 615 616[:__primitive_generator_concept__] 617 618[variablelist Notation 619 [[`num`] [Numeric literal, any real number value, or 620 a __karma_lazy_argument__ that evaluates to a real 621 number value of type `Num`]] 622 [[`Num`] [Type of `num`: any real number type]] 623] 624 625[heading Expression Semantics] 626 627Semantics of an expression is defined only where it differs from, or is 628not defined in __primitive_generator_concept__. 629 630[table 631 [[Expression] [Semantics]] 632 [[`lit(num)`] [Generate the real number literal `num` using the 633 default formatting (no trailing zeros, `fixed` 634 representation for numbers `fabs(n) <= 1e5 && fabs(n) > 1e-3`, 635 scientific representation otherwise, 3 fractional digits, 636 sign is only printed for negative literals). This 637 generator never fails (unless the underlying output 638 stream reports an error).]] 639 [ 640[``float_ 641double_ 642long_double``] [Generate the real number provided by a 643 mandatory attribute using the default formatting (no 644 trailing zeros, `fixed` representation for numbers 645 `fabs(n) <= 1e5 && fabs(n) > 1e-3`, scientific 646 representation otherwise, 3 fractional digits, 647 sign is only printed for negative literals). This 648 generator never fails (unless the underlying output 649 stream reports an error).]] 650 [ 651[``float_(num) 652double_(num) 653long_double(num)``] [Generate the real point number provided by the 654 immediate literal value the generator is initialized 655 from using the default formatting (no trailing zeros, 656 `fixed` representation for numbers 657 `fabs(n) <= 1e5 && fabs(n) > 1e-3`, scientific 658 representation otherwise, 3 fractional digits, sign is 659 only printed for negative literals). If this generator 660 has an associated attribute it succeeds only if 661 the attribute is equal to the immediate literal (unless 662 the underlying output stream reports an error). 663 Otherwise this generator fails and does not generate 664 any output.]] 665] 666 667All generators listed in the table above (except `lit(num)`) are predefined 668specializations of the `real_generator<Num, RealPolicies>` basic real 669number generator type described below. It is possible to directly use this 670type to create real number generators using a wide range of formatting 671options. 672 673[table 674 [[Expression] [Semantics]] 675 [ 676[``real_generator< 677 Num, RealPolicies 678>()``] 679 [Generate the real number of type `Num` 680 provided by a mandatory attribute using the specified 681 `RealPolicies`. This generator never fails 682 (unless the underlying output stream reports an 683 error).]] 684 [ 685[``real_generator< 686 Num, RealPolicies 687>()(num)``] 688 [Generate the real number of type `Num` provided by the 689 immediate literal value the generator is initialized 690 from using the specified `RealPolicies`. 691 If this generator has an associated attribute it 692 succeeds only if the attribute is equal to the 693 immediate literal (unless the underlying output stream 694 reports an error). Otherwise this generator fails and 695 does not generate any output.]] 696] 697 698[heading Additional Requirements] 699 700The following list enumerates the requirements which must be met in order to 701use a certain type `Num` to instantiate a `real_generator<Num, Policies>`. 702 703In order to be usable as the first template parameter for `real_generator<>` 704the type `Num` must have defined: 705 706* comparison operators for: `<`, `<=`, `==`, `!=`, `>`, and `>=` 707* numeric operators for: `+`, `-`, `/`, `*`, and `%` 708* functions implementing the interface and the semantics of: `std::fmod`, 709 `std::pow`, `std::log10`, `std::lround`, `std::ltrunc`, `std::modf`, 710 `std::floor`, and `std::ceil`. These need to be defined in a way so that they 711 will be found using argument dependent lookup (ADL). 712* a valid specialization of the type `std::numeric_limits<Num>` allowing for 713 numeric property inspection. 714 715 716[heading Attributes] 717 718[table 719 [[Expression] [Attribute]] 720 [[`lit(num)`] [__unused__]] 721 722 [[`float_`] [`float`, attribute is mandatory (otherwise compilation 723 will fail)]] 724 [[`float_(num)`] [`float_`, attribute is optional, if it is supplied, the 725 generator compares the attribute with `num` and 726 succeeds only if both are equal, failing otherwise.]] 727 728 [[`double_`] [`double`, attribute is mandatory (otherwise compilation 729 will fail)]] 730 [[`double_(num)`] [`double`, attribute is optional, if it is supplied, the 731 generator compares the attribute with `num` and 732 succeeds only if both are equal, failing otherwise.]] 733 734 [[`long_double`] [`long double`, attribute is mandatory (otherwise 735 compilation will fail)]] 736 [[`long_double(num)`][`long double`, attribute is optional, if it is supplied, 737 the generator compares the attribute with `num` and 738 succeeds only if both are equal, failing otherwise.]] 739 [ 740[``real_generator< 741 Num, Policies 742>()``] [`Num`, attribute is mandatory (otherwise compilation 743 will fail)]] 744 [ 745[``real_generator< 746 Num, Policies 747>()(num)``] [`Num`, attribute is optional, if it is supplied, the 748 generator compares the attribute with `num` and 749 succeeds only if both are equal, failing otherwise.]] 750] 751 752[note In addition to their usual attribute of type `Num` all listed generators 753 accept an instance of a `boost::optional<Num>` as well. If the 754 `boost::optional<>` is initialized (holds a value) the generators behave 755 as if their attribute was an instance of `Num` and emit the value stored 756 in the `boost::optional<>`. Otherwise the generators will fail.] 757 758[heading Real Number Formatting Policies] 759 760If special formatting of a real number is needed, overload 761the policy class `real_policies<Num>` and use it as a template 762parameter to the `real_generator<>` real number generator. For instance: 763 764 // define a new real number formatting policy 765 template <typename Num> 766 struct scientific_policy : real_policies<Num> 767 { 768 // we want the numbers always to be in scientific format 769 static int floatfield(Num n) { return fmtflags::scientific; } 770 }; 771 772 // define a new generator type based on the new policy 773 typedef real_generator<double, scientific_policy<double> > science_type; 774 science_type const scientific = science_type(); 775 776 // use the new generator 777 generate(sink, science_type(), 1.0); // will output: 1.0e00 778 generate(sink, scientific, 0.1); // will output: 1.0e-01 779 780The template parameter `Num` should be the type to be formatted using the 781overloaded policy type. At the same time `Num` will be used as the attribute 782type of the created real number generator. 783 784 785[heading Real Number Formatting Policy Expression Semantics] 786 787A real number formatting policy should expose the following variables and 788functions: 789 790[table 791[[Expression][Description]] 792[ [`` 793 template <typename Inserter 794 , typename OutputIterator 795 , typename Policies> 796 bool call (OutputIterator& sink, Num n 797 , Policies const& p); 798 ``] 799 [This is the main function used to generate the output for a real 800 number. It is called by the real generator in order to perform the 801 conversion. In theory all of the work can be implemented here, but the 802 easiest way is to use existing functionality provided by the type specified 803 by the template parameter `Inserter`. The default implementation of this 804 functions is: 805 `` 806 template <typename Inserter, typename OutputIterator 807 , typename Policies> 808 static bool 809 call (OutputIterator& sink, Num n, Policies const& p) 810 { 811 return Inserter::call_n(sink, n, p); 812 } 813 `` 814 `sink` is the output iterator to use for generation 815 816 `n` is the real number to convert 817 818 `p` is the instance of the policy type used to instantiate this real 819 number generator. 820 ]] 821[ [`` 822 bool force_sign(Num n); 823 ``] 824 [The default behavior is to not to require generating a sign. If the function 825 `force_sign()` returns true, then all generated numbers will have a 826 sign (`'+'` or `'-'`, zeros will have a space instead of a sign). 827 828 `n` is the real number to output. This can be used to 829 adjust the required behavior depending on the value of this number.]] 830[ [`` 831 bool trailing_zeros(Num n); 832 ``] 833 [Return whether trailing zero digits have to be emitted in the fractional 834 part of the output. If set, this flag instructs the real number 835 generator to emit trailing zeros up to the required precision digits (as 836 returned by the `precision()` function). 837 838 `n` is the real number to output. This can be used to 839 adjust the required behavior depending on the value of this number.]] 840[ [`` 841 int floatfield(Num n); 842 ``] 843 [Decide, which representation type to use in the generated output. 844 845 By default all numbers having an absolute value of zero or in between 846 `0.001` and `100000` will be generated using the fixed format, all others 847 will be generated using the scientific representation. 848 849 The `trailing_zeros()` can be used to force the output of trailing zeros 850 in the fractional part up to the number of digits returned by the 851 `precision()` member function. The default is not to generate the trailing 852 zeros. 853 854 `n` is the real number to output. This can be used to 855 adjust the formatting flags depending on the value of 856 this number. 857 858 The return value has to be either `fmtflags::scientific` (generate real 859 number values in scientific notation) or `fmtflags::fixed` (generate 860 real number values in fixed-point notation). 861 ]] 862[ [`` 863 unsigned precision(Num n); 864 ``] 865 [Return the maximum number of decimal digits to generate in the 866 fractional part of the output. 867 868 `n` is the real number to output. This can be used to 869 adjust the required precision depending on the value of this number. If 870 the trailing zeros flag is specified the fractional part of the output will 871 be 'filled' with zeros, if appropriate. 872 873 *Note:* If the trailing_zeros flag is not in effect additional semantics 874 apply. See the description for the `fraction_part()` function below. 875 Moreover, this precision will be limited to the value of 876 `std::numeric_limits<T>::digits10 + 1`.]] 877[ [`` 878 template <typename OutputIterator> 879 bool integer_part(OutputIterator& sink 880 , Num n, bool sign, bool force_sign); 881 ``] 882 [This function is called to generate the integer part of the real 883 number. 884 885 `sink` is the output iterator to use for generation 886 887 `n` is the absolute value of the integer part of the real 888 number to convert (always non-negative) 889 890 `sign` is the sign of the overall real number to convert. 891 892 `force_sign` is a flag indicating whether a sign has to be generated even for 893 non-negative numbers (this is the same as has been returned 894 from the function `force_sign()` described above) 895 896 The return value defines the outcome of the whole generator. If it is 897 `false`, no further output is generated, immediately returning `false` from 898 the calling `real_generator` as well. If it is `true`, normal output 899 generation continues.]] 900[ [`` 901 template <typename OutputIterator> 902 bool dot(OutputIterator& sink, Num n, 903 unsigned precision); 904 ``] 905 [This function is called to generate the decimal point. 906 907 `sink` is the output iterator to use for generation 908 909 `n` is the fractional part of the real number to convert. Note 910 that this number is scaled such, that it represents the number of units 911 which correspond to the value returned from the `precision()` function 912 earlier. I.e. a fractional part of `0.01234` is represented as `1234` 913 when the function `precision()` returned `5`. 914 915 `precision` is the number of digits to emit as returned by the function 916 `precision()` described above 917 918 This is given to allow to decide, whether a decimal point has to be 919 generated at all. 920 921 *Note:* If the `trailing_zeros` flag is not in effect additional comments 922 apply. See the description for the `fraction_part()` function below. 923 924 The return value defines the outcome of the whole generator. If it is 925 `false`, no further output is generated, immediately returning `false` from 926 the calling `real_generator` as well. If it is `true`, normal output 927 generation continues.]] 928[ [`` 929 template <typename OutputIterator> 930 bool fraction_part(OutputIterator& sink, Num n 931 , unsigned adjprec, unsigned precision); 932 ``] 933 [This function is called to generate the fractional part of the number. 934 935 `sink` is the output iterator to use for generation 936 937 `n` is the fractional part of the real number to convert. Note 938 that this number is scaled such, that it represents the number of units 939 which correspond to the value returned from the `precision()` function 940 earlier. I.e. a fractional part of `0.01234` is represented as `1234` 941 when the function `precision()` returned `5`. 942 943 `adjprec` is the corrected number of digits to emit (see note below) 944 945 `precision` is the number of digits to emit as returned by the function 946 `precision()` described above 947 948 *Note:* If `trailing_zeros()` returns `false` the `adjprec` 949 parameter will have been corrected from the value the `precision()` 950 function returned earlier (defining the maximal number of fractional 951 digits) in the sense, that it takes into account trailing zeros. I.e. a 952 real number `0.0123` and a value of `5` returned from 953 `precision()` will result in: 954 955 `trailing_zeros()` returned `false`: `n` will be `123`, and `adjprec` 956 will be `4` (as we need to print `0123`) 957 958 `trailing_zeros()` returned `true`: `n` will be `1230`, and `adjprec` 959 will be `5` (as we need to print `01230`) 960 961 The missing preceding zeros in the fractional part have to be supplied 962 by the implementation of this policy function. 963 964 The return value defines the outcome of the whole generator. If it is 965 `false`, no further output is generated, immediately returning `false` from 966 the calling `real_generator` as well. If it is `true`, normal output 967 generation continues.]] 968[ [`` 969 template <typename CharEncoding, 970 typename Tag, typename OutputIterator> 971 bool exponent( 972 OutputIterator& sink, long n); 973 ``] 974 [This function is called to generate the exponential part of the number 975 (this is called only if the `floatfield()` function returned the 976 `fmtflags::scientific` flag). 977 978 `sink` is the output iterator to use for generation 979 980 `n` is the (signed) exponential part of the real number to convert. 981 982 The template parameters `CharEncoding` and `Tag` are either of the type 983 `unused_type` or describe the character class and conversion to be 984 applied to any output possibly influenced by either the `lower[]` or 985 `upper[]` directives. 986 987 The return value defines the outcome of the whole generator. If it is 988 `false`, no further output is generated, immediately returning `false` from 989 the calling `real_generator` as well. If it is `true`, normal output 990 generation continues.]] 991[ [`` 992 template <typename CharEncoding 993 , typename Tag, typename OutputIterator> 994 bool nan (OutputIterator& sink, Num n 995 , bool force_sign); 996 ``] 997 [This function is called whenever the number to print is a non-normal 998 real number of type `NaN`. 999 1000 `sink` is the output iterator to use for generation 1001 1002 `n` is the (signed) real number to convert 1003 1004 `force_sign` is a flag indicating whether a sign has to be generated even for 1005 non-negative numbers (this is the same as has been returned from 1006 the function `force_sign()` described above) 1007 1008 The template parameters `CharEncoding` and `Tag` are either of the type 1009 `unused_type` or describe the character class and conversion to be 1010 applied to any output possibly influenced by either the `lower[]` or 1011 `upper[]` directives. 1012 1013 The return value defines the outcome of the whole generator. If it is 1014 `false`, no further output is generated, immediately returning `false` from 1015 the calling `real_generator` as well. If it is `true`, normal output 1016 generation continues.]] 1017[ [`` 1018 template <typename CharEncoding 1019 , typename Tag, typename OutputIterator> 1020 bool inf (OutputIterator& sink, Num n 1021 , bool force_sign); 1022 ``] 1023 [This function is called whenever the number to print is a non-normal 1024 real number of type `Inf`. 1025 1026 `sink` is the output iterator to use for generation 1027 1028 `n` is the (signed) real number to convert 1029 1030 `force_sign` is a flag indicating whether a sign has to be generated even for 1031 non-negative numbers (this is the same as has been returned from 1032 the function `force_sign()` described above) 1033 1034 The template parameters `CharEncoding` and `Tag` are either of the type 1035 `unused_type` or describe the character class and conversion to be 1036 applied to any output possibly influenced by either the `lower[]` or 1037 `upper[]` directives. 1038 1039 The return value defines the outcome of the whole generator. If it is 1040 `false`, no further output is generated, immediately returning `false` from 1041 the calling `real_generator` as well. If it is `true`, normal output 1042 generation continues.]] 1043] 1044 1045[tip The easiest way to implement a proper real number formatting policy is 1046 to derive a new type from the type `real_policies<>` while overriding 1047 the aspects of the formatting which need to be changed.] 1048 1049 1050[heading Complexity] 1051 1052[:O(N), where `N` is the number of digits needed to represent the generated 1053 real number.] 1054 1055[heading Example] 1056 1057[note The test harness for the example(s) below is presented in the 1058 __karma_basics_examples__ section.] 1059 1060Some includes: 1061 1062[reference_karma_includes] 1063 1064Some using declarations: 1065 1066[reference_karma_using_declarations_real] 1067 1068Basic usage of an `double_` generator: 1069 1070[reference_karma_real] 1071 1072[endsect] 1073 1074[/////////////////////////////////////////////////////////////////////////////] 1075[section:boolean Boolean Generators (`bool_`)] 1076 1077[heading Description] 1078 1079As you might expect, the `bool_generator` can generate output from boolean 1080values. The `bool_generator` generator can be used to generate output from 1081ordinary primitive C/C++ `bool` values or user defined boolean types if 1082the type follows certain expression requirements (for more information about 1083the requirements, see 1084[link spirit.karma.reference.numeric.boolean.additional_requirements below])). 1085The `bool_generator` is a template class. Template parameters fine tune its 1086behavior. 1087 1088[heading Header] 1089 1090 // forwards to <boost/spirit/home/karma/numeric/bool.hpp> 1091 #include <boost/spirit/include/karma_bool.hpp> 1092 1093Also, see __include_structure__. 1094 1095[heading Namespace] 1096 1097[table 1098 [[Name]] 1099 [[`boost::spirit::lit // alias: boost::spirit::karma::lit`]] 1100 [[`boost::spirit::bool_ // alias: boost::spirit::karma::bool_`]] 1101 [[`boost::spirit::true_ // alias: boost::spirit::karma::true_`]] 1102 [[`boost::spirit::false_ // alias: boost::spirit::karma::false_`]] 1103] 1104 1105[note `lit` is reused by the [karma_string String Generators], the 1106 __karma_char__, and the Numeric Generators. In 1107 general, a char generator is created when you pass in a 1108 character, a string generator is created when you pass in a string, and a 1109 numeric generator is created when you use a numeric (boolean) literal.] 1110 1111[heading Synopsis] 1112 1113 template < 1114 typename B 1115 , unsigned Policies> 1116 struct bool_generator; 1117 1118[heading Template parameters] 1119 1120[table 1121 [[Parameter] [Description] [Default]] 1122 [[`B`] [The boolean base type of the 1123 boolean generator.] [`bool`]] 1124 [[`Policies`] [The policies to use while 1125 converting the boolean.] [`bool_policies<B>`]] 1126] 1127 1128[heading Model of] 1129 1130[:__primitive_generator_concept__] 1131 1132[variablelist Notation 1133 [[`b`] [Boolean literal, or a __karma_lazy_argument__ that 1134 evaluates to a boolean value of type `B`]] 1135 [[`B`] [Type of `b`: any type usable as a boolean, or in case 1136 of a __karma_lazy_argument__, its return value]] 1137] 1138 1139[heading Expression Semantics] 1140 1141Semantics of an expression is defined only where it differs from, or is 1142not defined in __primitive_generator_concept__. 1143 1144[table 1145 [[Expression] [Semantics]] 1146 [[`lit(b)`] [Generate the boolean literal `b` using the default 1147 formatting (`false` is generated as `"false"`, and 1148 `true` is generated as `"true"`). This generator never 1149 fails (unless the underlying output stream reports an error).]] 1150 [[`bool_`] [Generate the boolean value provided by a mandatory 1151 attribute using the default formatting (`false` is 1152 generated as `"false"`, and `true` is generated as 1153 `"true"`). This generator never fails (unless the 1154 underlying output stream reports an error).]] 1155 [[`bool_(b)`] [Generate the boolean value provided by the 1156 immediate literal value the generator is initialized 1157 from using the default formatting (`false` is 1158 generated as `"false"`, and `true` is generated as 1159 `"true"`). If this generator has an associated 1160 attribute it succeeds only if the attribute 1161 is equal to the immediate literal (unless the 1162 underlying output stream reports an error). Otherwise 1163 this generator fails and does not generate any output.]] 1164 [[`true_`] [Generate `"true"`. If this generator has an associated 1165 attribute it succeeds only if the attribute 1166 is `true` as well (unless the underlying output stream 1167 reports an error).]] 1168 [[`false_`] [Generate `"false"`. If this generator has an associated 1169 attribute it succeeds only if the attribute 1170 is `false` as well (unless the underlying output stream 1171 reports an error).]] 1172] 1173 1174All generators listed in the table above (except `lit(num)`) are predefined 1175specializations of the `bool_generator<B, Policies>` basic boolean generator 1176type described below. It is possible to directly use this type to create 1177boolean generators using a wide range of formatting options. 1178 1179[table 1180 [[Expression] [Semantics]] 1181 [ 1182[``bool_generator< 1183 B, Policies 1184>()``] [Generate the boolean of type `B` provided 1185 by a mandatory attribute using the specified `Policies` 1186 This generator never fails (unless the underlying 1187 output stream reports an error).]] 1188 [ 1189[``bool_generator< 1190 B, Policies 1191>()(b)``] [Generate the boolean of type `B` provided 1192 by the immediate literal value the generator is 1193 initialized from, using the specified `Policies`. If 1194 this generator has an associated attribute it succeeds 1195 only if the attribute is equal to the 1196 immediate literal (unless the underlying output 1197 stream reports an error). Otherwise this generator 1198 fails and does not generate any output.]] 1199] 1200 1201[note All boolean generators properly respect the [karma_upperlower `upper`] 1202 and [karma_upperlower `lower`] directives.] 1203 1204[heading Additional Requirements] 1205 1206The following lists enumerate the requirements which must be met in order to 1207use a certain type `B` to instantiate and use a `bool_generator<B, Policies>`. 1208 1209The type `B`: 1210 1211* must be (safely) convertible to `bool` 1212 1213[heading Attributes] 1214 1215[table 1216 [[Expression] [Attribute]] 1217 [[`bool_(b)`] [__unused__]] 1218 [[`bool_`] [`bool`, attribute is mandatory (otherwise 1219 compilation will fail)]] 1220 [[`bool_(b)`] [`bool`, attribute is optional, if it is 1221 supplied, the generator compares the attribute with 1222 `b` and succeeds only if both are equal, failing 1223 otherwise.]] 1224 1225 [ 1226[``bool_generator< 1227 B, Policies 1228>()``] [`B`, attribute is mandatory (otherwise compilation 1229 will fail)]] 1230 [ 1231[``bool_generator< 1232 B, Policies 1233>()(b)``] [`B`, attribute is optional, if it is supplied, the 1234 generator compares the attribute with `b` and 1235 succeeds only if both are equal, failing otherwise.]] 1236] 1237 1238[note In addition to their usual attribute of type `B` all listed generators 1239 accept an instance of a `boost::optional<B>` as well. If the 1240 `boost::optional<>` is initialized (holds a value) the generators behave 1241 as if their attribute was an instance of `B` and emit the value stored 1242 in the `boost::optional<>`. Otherwise the generators will fail.] 1243 1244[heading Boolean Formatting Policies] 1245 1246If special formatting of a boolean is needed, overload 1247the policy class `bool_policies<B>` and use it as a template 1248parameter to the `bool_generator<>` boolean generator. For instance: 1249 1250 struct special_bool_policy : karma::bool_policies<> 1251 { 1252 template <typename CharEncoding, typename Tag 1253 , typename OutputIterator> 1254 static bool generate_false(OutputIterator& sink, bool b) 1255 { 1256 // we want to spell the names of false as eurt (true backwards) 1257 return string_inserter<CharEncoding, Tag>::call(sink, "eurt"); 1258 } 1259 }; 1260 1261 typedef karma::bool_generator<special_bool_policy> backwards_bool_type; 1262 backwards_bool_type const backwards_bool; 1263 1264 karma::generate(sink, backwards_bool, true); // will output: true 1265 karma::generate(sink, backwards_bool(false)); // will output: uert 1266 1267The template parameter `B` should be the type to be formatted using the 1268overloaded policy type. At the same time `B` will be used as the attribute 1269type of the created real number generator. The default for `B` is `bool`. 1270 1271 1272[heading Boolean Formatting Policy Expression Semantics] 1273 1274A boolean formatting policy should expose the following: 1275 1276[table 1277[[Expression][Description]] 1278[ [`` 1279 template <typename Inserter 1280 , typename OutputIterator 1281 , typename Policies> 1282 bool call (OutputIterator& sink, Num n 1283 , Policies const& p); 1284 ``] 1285 [This is the main function used to generate the output for a boolean. 1286 It is called by the boolean generator in order to perform the 1287 conversion. In theory all of the work can be implemented here, but the 1288 easiest way is to use existing functionality provided by the type specified 1289 by the template parameter `Inserter`. The default implementation of this 1290 functions is: 1291 `` 1292 template <typename Inserter, typename OutputIterator 1293 , typename Policies> 1294 static bool 1295 call (OutputIterator& sink, B b, Policies const& p) 1296 { 1297 return Inserter::call_n(sink, b, p); 1298 } 1299 `` 1300 `sink` is the output iterator to use for generation 1301 1302 `b` is the boolean to convert 1303 1304 `p` is the instance of the policy type used to instantiate this real 1305 number generator. 1306 ]] 1307[ [`` 1308 template <typename CharEncoding, 1309 typename Tag, typename OutputIterator> 1310 bool generate_false( 1311 OutputIterator& sink, B b); 1312 ``] 1313 [This function is called to generate the boolean if it is `false`. 1314 1315 `sink` is the output iterator to use for generation 1316 1317 `b` is the boolean to convert (the value is `false`). 1318 1319 The template parameters `CharEncoding` and `Tag` are either of the type 1320 `unused_type` or describe the character class and conversion to be 1321 applied to any output possibly influenced by either the `lower[]` or 1322 `upper[]` directives. 1323 1324 The return value defines the outcome of the whole generator. ]] 1325[ [`` 1326 template <typename CharEncoding, 1327 typename Tag, typename OutputIterator> 1328 bool generate_true( 1329 OutputIterator& sink, B b); 1330 ``] 1331 [This function is called to generate the boolean if it is `true`. 1332 1333 `sink` is the output iterator to use for generation 1334 1335 `b` is the boolean to convert (the value is `true`). 1336 1337 The template parameters `CharEncoding` and `Tag` are either of the type 1338 `unused_type` or describe the character class and conversion to be 1339 applied to any output possibly influenced by either the `lower[]` or 1340 `upper[]` directives. 1341 1342 The return value defines the outcome of the whole generator. ]] 1343] 1344 1345[heading Complexity] 1346 1347[:O(N), where `N` is the number of characters needed to represent the generated 1348 boolean.] 1349 1350[heading Example] 1351 1352[note The test harness for the example(s) below is presented in the 1353 __karma_basics_examples__ section.] 1354 1355Some includes: 1356 1357[reference_karma_includes] 1358 1359Some using declarations: 1360 1361[reference_karma_using_declarations_bool] 1362 1363Basic usage of an `bool_` generator: 1364 1365[reference_karma_bool] 1366 1367[endsect] 1368 1369[endsect] 1370