1<?xml version="1.0" encoding="utf-8"?> 2<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" 3"../../../tools/boostbook/dtd/boostbook.dtd"> 4 5<!-- Copyright (c) 2005 CrystalClear Software, Inc. 6 Subject to the Boost Software License, Version 1.0. 7 (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt) 8--> 9 10<section id="date_time.io_objects" 11 xmlns:xi="http://www.w3.org/2001/XInclude"> 12 <title>Date Time Formatter/Parser Objects</title> 13 <!-- <using-namespace name="boost"/> --> 14 <using-namespace name="boost::date_time"/> 15 <bridgehead renderas="sect2">Date Time Formatter/Parser Objects</bridgehead> 16 17 <link linkend="io_objects.periods">Periods</link> | 18 <link linkend="io_objects.date_generators">Date Generators</link> | 19 <link linkend="io_objects.special_values">Special Values</link> | 20 <link linkend="io_objects.format_date_parser">Format Date Parser</link> 21 22 <anchor id="io_objects.periods" /> 23 <bridgehead renderas="sect3">Periods</bridgehead> 24 <para>The period_formatter and period_parser provide a uniform interface for the input and output of date_periods, time_periods, and in a future release, local_date_time_periods. The user has control over the delimiters, formats of the date/time components, and the form the period takes. The format of the date/time components is controlled via the date_time input and output facets.</para> 25 26 <bridgehead renderas="sect4">Period Form</bridgehead> 27 <para>Periods are constructed with open ranged parameters. The first value is the starting point, and is included in the period. The end value is not included but immediately follows the last value: [begin/end). However, a period can be streamed as either an open range or a closed range.</para> 28 <screen>[2003-Jan-01/2003-Dec-31] <-- period holding 365 days 29[2003-Jan-01/2004-Jan-01) <-- period holding 365 days</screen> 30 31 <bridgehead renderas="sect4">Delimiters</bridgehead> 32 <para>There are four delimiters. The default values are<simplelist type="vert" columns="1"> 33 <member>"\" - separator</member> 34 <member>"[" - start delimiter</member> 35 <member>")" - open range end delimiter</member> 36 <member>"]" - closed range end delimiter</member> 37 </simplelist>A user can provide a custom set of delimiters. Custom delimiters may contain spaces.</para> 38 39 <bridgehead renderas="sect4">Customization</bridgehead> 40 <para>The period form and delimiters can be set as construction parameters or by means of accessor functions. A custom period parser/formatter can then be used as a construction parameter to a new facet, or can be set in an existing facet via an accessor function.</para> 41 42 43 <bridgehead renderas="sect4">Period Formatter/Parser Reference</bridgehead> 44 The complete class reference can be found here: <classname alt="boost::date_time::period_formatter">Period Formatter Doxygen Reference</classname> and here: <classname alt="boost::date_time::period_parser">Period Parser Doxygen Reference</classname> 45 46 <para> 47 <bridgehead renderas="sect4">Period Formatter Construction</bridgehead> 48 <informaltable frame="all"> 49 <tgroup cols="2"> 50 <thead> 51 <row> 52 <entry valign="top">Syntax</entry> 53 <entry>Description</entry> 54 </row> 55 </thead> 56 <tbody> 57 <row> 58 <entry valign="top"><screen>period_formatter(...) 59 Parameters: 60 range_display_options 61 char_type* 62 char_type* 63 char_type* 64 char_type*</screen></entry> 65 <entry>NOTE: All five construction parameters have default values so this constructor also doubles as the default constructor. The <code>range_display_options</code> is a public type enum of the <code>period_formatter</code> class. The possible choices are AS_OPEN_RANGE or AS_CLOSED_RANGE. The closed range is the default. A period has three significant points: the begining, the last, and the end. A closed range period takes the form [begin,end), where an open range period takes the form [begin,last]. The four char_type* parameters are: the period separator, the start delimiter, the open range end delimiter, and the closed range end delimiter.</entry> 66 </row> 67 </tbody> 68 </tgroup> 69 </informaltable> 70 <bridgehead renderas="sect4">Period Formatter Accessors</bridgehead> 71 <informaltable frame="all"> 72 <tgroup cols="2"> 73 <thead> 74 <row> 75 <entry valign="top" morerows="1">Syntax</entry> 76 <entry>Description</entry> 77 </row> 78 <row> 79 <entry>Example</entry> 80 </row> 81 </thead> 82 <tbody> 83 <row> 84 <entry valign="top" morerows="1"><screen>range_display_options range_option()</screen></entry> 85 <entry>Returns the current setting for the range display (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</entry> 86 </row> 87 <row> 88 <entry><screen></screen></entry> 89 </row> 90 91 <row> 92 <entry valign="top" morerows="1"><screen>void range_option(...) 93 Parameter: 94 range_display_options</screen></entry> 95 <entry>Sets the option for range display (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</entry> 96 </row> 97 <row> 98 <entry><screen></screen></entry> 99 </row> 100 101 <row> 102 <entry valign="top" morerows="1"><screen>void delimiter_strings(...) 103 Parameters: 104 string_type 105 string_type 106 string_type 107 string_type</screen></entry> 108 <entry>Set new delimiter strings in the formatter.</entry> 109 </row> 110 <row> 111 <entry><screen>string beg("->| "); 112string sep(" || "); 113string opn(" ->|"); 114string clo(" |<-"); 115pf.delimiter_strings(beg, sep, 116 opn, clo);</screen></entry> 117 </row> 118 119 <row> 120 <entry valign="top" morerows="1"><screen>put_period_start_delimeter(...) 121 Return Type: 122 OutItrT 123 Parameter: 124 OutItrT</screen></entry> 125 <entry>Puts the start delimiter into the stream at position pointed to by OutItrT parameter.</entry> 126 </row> 127 <row> 128 <entry><screen></screen></entry> 129 </row> 130 131 <row> 132 <entry valign="top" morerows="1"><screen>put_period_sepatator(...) 133 Return Type: 134 OutItrT 135 Parameter: 136 OutItrT</screen></entry> 137 <entry>Puts the separator into the stream at position pointed to by OutItrT parameter.</entry> 138 </row> 139 <row> 140 <entry><screen></screen></entry> 141 </row> 142 143 <row> 144 <entry valign="top" morerows="1"><screen>put_period_end_delimeter(...) 145 Return Type: 146 OutItrT 147 Parameter: 148 OutItrT</screen></entry> 149 <entry>Puts the end delimiter into the stream at position pointed to by OutItrT parameter.</entry> 150 </row> 151 <row> 152 <entry><screen></screen></entry> 153 </row> 154 155 <row> 156 <entry valign="top" morerows="1"><screen>OutItrT put_period(...) 157 Parameters: 158 OutItrT 159 ios_base 160 char_type 161 period_type 162 facet_type</screen></entry> 163 <entry>Puts a period into the stream using the set values for delimiters, separator, and range display. The facet parameter is used to put the date (or time) objects of the period.</entry> 164 </row> 165 <row> 166 <entry><screen></screen></entry> 167 </row> 168 169 </tbody> 170 </tgroup> 171 </informaltable> 172 </para> 173 <para> 174 <bridgehead renderas="sect4">Period Parser Construction</bridgehead> 175 <informaltable frame="all"> 176 <tgroup cols="2"> 177 <thead> 178 <row> 179 <entry valign="top">Syntax</entry> 180 <entry>Description</entry> 181 </row> 182 </thead> 183 <tbody> 184 <row> 185 <entry valign="top"><screen>period_parser(...) 186 Parameters: 187 period_range_option 188 char_type* 189 char_type* 190 char_type* 191 char_type*</screen></entry> 192 <entry>NOTE: All five construction parameters have default values so this constructor also doubles as the default constructor. The <code>period_range_option</code> is a public type enum of the <code>period_parser</code> class. The possible choices are AS_OPEN_RANGE or AS_CLOSED_RANGE. The closed range is the default. A period has three significant points: the begining, the last, and the end. A closed range period takes the form [begin,end), where an open range period takes the form [begin,last]. The four char_type* parameters are: the period separator, the start delimiter, the open range end delimiter, and the closed range end delimiter.</entry> 193 </row> 194 <row> 195 <entry valign="top"><screen>period_parser(period_parser)</screen></entry> 196 <entry>Copy constructor</entry> 197 </row> 198 </tbody> 199 </tgroup> 200 </informaltable> 201 <bridgehead renderas="sect4">Period Parser Accessors</bridgehead> 202 <informaltable frame="all"> 203 <tgroup cols="2"> 204 <thead> 205 <row> 206 <entry valign="top" morerows="1">Syntax</entry> 207 <entry>Description</entry> 208 </row> 209 <row> 210 <entry>Example</entry> 211 </row> 212 </thead> 213 <tbody> 214 <row> 215 <entry valign="top" morerows="1"><screen>period_range_option range_option()</screen></entry> 216 <entry>Returns the current setting for the period range (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</entry> 217 </row> 218 <row> 219 <entry><screen></screen></entry> 220 </row> 221 222 <row> 223 <entry valign="top" morerows="1"><screen>void range_option(...) 224 Parameter: 225 period_range_option </screen></entry> 226 <entry>Sets the option for period range (either AS_OPEN_RANGE or AS_CLOSED_RANGE).</entry> 227 </row> 228 <row> 229 <entry><screen></screen></entry> 230 </row> 231 232 <row> 233 <entry valign="top" morerows="1"><screen>void delimiter_strings(...) 234 Parameters: 235 string_type 236 string_type 237 string_type 238 string_type</screen></entry> 239 <entry>Set new delimiter strings in the parser.</entry> 240 </row> 241 <row> 242 <entry><screen>string beg("->| "); 243string sep(" || "); 244string opn(" ->|"); 245string clo(" |<-"); 246pp.delimiter_strings(beg, sep, 247 opn, clo);</screen></entry> 248 </row> 249 250 <row> 251 <entry valign="top" morerows="1"><screen>collection_type delimiter_strings()</screen></entry> 252 <entry>Returns the set of delimiter strings currently held in the parser.</entry> 253 </row> 254 <row> 255 <entry><screen></screen></entry> 256 </row> 257 258 <row> 259 <entry valign="top" morerows="1"><screen>period_type get_period(...) 260 Parameters: 261 stream_itr_type 262 stream_itr_type 263 ios_base 264 period_type 265 duration_type 266 facet_type</screen></entry> 267<entry>Parses a period from the stream. The iterator parameters point to the begining and end of the stream. The duration_type is relevant to the period type, for example: A <code>date_period</code> would use <code>days</code> as a duration_type. The period will be parsed according to the formats and strings found in the facet parameter.</entry> 268 </row> 269 <row> 270 <entry><screen></screen></entry> 271 </row> 272 273 </tbody> 274 </tgroup> 275 </informaltable> 276 </para> 277 278 <para>_____________________________________________________</para> 279 280 <anchor id="io_objects.date_generators" /> 281 <bridgehead renderas="sect3">Date Generators</bridgehead> 282 <para>The date_generator formatter and parser provide flexibility by allowing the user to use custom "phrase elements". These phrase elements are the "in-between" words in the date_generators. For example, in the date_generator "Second Monday of March", "Second" and "of" are the phrase elements, where "Monday" and "March" are the date elements. Customization of the date elements is done with the facet. The order of the date and phrase elements cannot be changed. When parsing, all elements of the date_generator phrase must parse correctly or an ios_base::failure exception will be thrown.</para> 283 284 <bridgehead renderas="sect4">Customization</bridgehead> 285 <para>The default "phrase_strings" are: 286 <simplelist type="horiz" columns="9"> 287 <member>"first"</member> 288 <member>"second"</member> 289 <member>"third"</member> 290 <member>"fourth"</member> 291 <member>"fifth"</member> 292 <member>"last"</member> 293 <member>"before"</member> 294 <member>"after"</member> 295 <member>"of"</member> 296 </simplelist> 297 A custom set of phrase_strings must maintain this order of occurance (Ex: "1st", "2nd", "3rd", "4th", "5th", "last", "prior", "past", "in").</para> 298 <para> Examples using default phrase_strings and default facet formats for weekday & month: <screen>"first Tue of Mar"</screen>And using custom phrase_strings: <screen>"1st Tue in Mar"</screen> 299 </para> 300 <para>The custom set of phrase elements can be set as construction parameters or through an accessor function.A custom date_generator parser/formatter can then be used as a construction parameter to a new facet, or can be set in an existing facet via an accessor function.</para> 301 <para>IMPORTANT NOTE: Prior to 1.33, partial_date was output as "1 Jan" with a single *or* double digit number for the day. The new behavior is to *always* place a double digit number for the day - "01 Jan".</para> 302 303 <bridgehead renderas="sect4">Date Generator Reference</bridgehead> 304 The complete class references can be found here: <classname alt="boost::date_time::date_generator_formatter">Date Generator Formatter Doxygen Reference</classname> and here: <classname alt="boost::date_time::date_generator_parser">Date Generator Parser Doxygen Reference</classname> 305 306 <para> 307 <bridgehead renderas="sect4">Date Generator Formatter Construction</bridgehead> 308 <informaltable frame="all"> 309 <tgroup cols="2"> 310 <thead> 311 <row> 312 <entry valign="top">Syntax</entry> 313 <entry>Description</entry> 314 </row> 315 </thead> 316 <tbody> 317 <row> 318 <entry valign="top"><screen>date_generator_formatter()</screen></entry> 319 <entry>Uses the default date generator elements.</entry> 320 </row> 321 <row> 322 <entry valign="top"><screen>date_generator_formatter(...) 323 Parameters: 324 string_type first_element 325 string_type second_element 326 string_type third_element 327 string_type fourth_element 328 string_type fifth_element 329 string_type last_element 330 string_type before_element 331 string_type after_element 332 string_type of_element</screen></entry> 333 <entry>Constructs a date_generator_formatter using the given element strings.</entry> 334 </row> 335 336 </tbody> 337 </tgroup> 338 </informaltable> 339 <bridgehead renderas="sect4">Date Generator Formatter Accessors</bridgehead> 340 <informaltable frame="all"> 341 <tgroup cols="2"> 342 <thead> 343 <row> 344 <entry valign="top" morerows="1">Syntax</entry> 345 <entry>Description</entry> 346 </row> 347 <row> 348 <entry>Example</entry> 349 </row> 350 </thead> 351 <tbody> 352 <row> 353 <entry valign="top" morerows="1"><screen>void elements(...) 354 Parameters: 355 collection_type 356 phrase_elements</screen></entry> 357 <entry>Replace the current phrase elements with a collection of new ones. The <code>phrase_elements</code> parameter is an enum that indicates what the first element in the new collection is (defaults to first).</entry> 358 </row> 359 <row> 360 <entry><screen>// col is a collection holding 361// "final", "prior", "following", 362// and "in" 363typedef date_generator_formatter dgf; 364dgf formatter(); 365formatter.elements(col, dgf::last); 366// complete elements in dgf are now: 367"first", "second", "third", 368"fourth", "fifth", "final", 369"prior", "following", and "in"</screen></entry> 370 </row> 371 372 <row> 373 <entry valign="top" morerows="1"><screen>put_partial_date(...) 374 Return Type: 375 facet_type::OutItrT 376 Parameters: 377 OutItrT next 378 ios_base 379 char_type fill 380 partial_date 381 facet_type</screen></entry> 382 <entry>A put function for partial_date. This is a templated function that takes a facet_type as a parameter.</entry> 383 </row> 384 <row> 385 <entry>Put a partial_date => "dd Month".</entry> 386 </row> 387 388 <row> 389 <entry valign="top" morerows="1"><screen>put_nth_kday(...) 390 Return Type: 391 facet_type::OutItrT 392 Parameters: 393 OutItrT next 394 ios_base 395 char_type fill 396 nth_kday_type 397 facet_type</screen></entry> 398 <entry>A put function for nth_kday_type. This is a templated function that takes a facet_type as a parameter.</entry> 399 </row> 400 <row> 401 <entry>Put an nth_day_of_the_week_in_month => "nth weekday of month".</entry> 402 </row> 403 404 <row> 405 <entry valign="top" morerows="1"><screen>put_first_kday(...) 406 Return Type: 407 facet_type::OutItrT 408 Parameters: 409 OutItrT next 410 ios_base 411 char_type fill 412 first_kday_type 413 facet_type</screen></entry> 414 <entry>A put function for first_kday_type. This is a templated function that takes a facet_type as a parameter.</entry> 415 </row> 416 <row> 417 <entry>Put a first_day_of_the_week_in_month => "first weekday of month".</entry> 418 </row> 419 420 <row> 421 <entry valign="top" morerows="1"><screen>put_last_kday(...) 422 Return Type: 423 facet_type::OutItrT 424 Parameters: 425 OutItrT next 426 ios_base 427 char_type fill 428 last_kday_type 429 facet_type</screen></entry> 430 <entry>A put function for last_kday_type. This is a templated function that takes a facet_type as a parameter.</entry> 431 </row> 432 <row> 433 <entry>Put a last_day_of_the_week_in_month => "last weekday of month".</entry> 434 </row> 435 436 <row> 437 <entry valign="top" morerows="1"><screen>put_kday_before(...) 438 Return Type: 439 facet_type::OutItrT 440 Parameters: 441 OutItrT next 442 ios_base 443 char_type fill 444 kday_before_type 445 facet_type</screen></entry> 446 <entry>A put function for kday_before_type. This is a templated function that takes a facet_type as a parameter.</entry> 447 </row> 448 <row> 449 <entry>Put a first_day_of_the_week_before => "weekday before"</entry> 450 </row> 451 452 <row> 453 <entry valign="top" morerows="1"><screen>put_kday_after(...) 454 Return Type: 455 facet_type::OutItrT 456 Parameters: 457 OutItrT next 458 ios_base 459 char_type fill 460 kday_after_type 461 facet_type</screen></entry> 462 <entry>A put function for kday_after_type. This is a templated function that takes a facet_type as a parameter.</entry> 463 </row> 464 <row> 465 <entry>Put a first_day_of_the_week_after => "weekday after".</entry> 466 </row> 467 468 </tbody> 469 </tgroup> 470 </informaltable> 471 </para> 472 <para> 473 <bridgehead renderas="sect4">Date Generator Parser Construction</bridgehead> 474 <informaltable frame="all"> 475 <tgroup cols="2"> 476 <thead> 477 <row> 478 <entry valign="top">Syntax</entry> 479 <entry>Description</entry> 480 </row> 481 </thead> 482 <tbody> 483 <row> 484 <entry valign="top"><screen>date_generator_parser()</screen></entry> 485 <entry>Uses the default date generator elements.</entry> 486 </row> 487 <row> 488 <entry valign="top"><screen>date_generator_parser(...) 489 Parameter: 490 date_generator_parser</screen></entry> 491 <entry>Copy Constructor</entry> 492 </row> 493 <row> 494 <entry valign="top"><screen>date_generator_parser(...) 495 Parameters: 496 string_type first_element 497 string_type second_element 498 string_type third_element 499 string_type fourth_element 500 string_type fifth_element 501 string_type last_element 502 string_type before_element 503 string_type after_element 504 string_type of_element</screen></entry> 505 <entry>Constructs a date_generator_parser using the given element strings.</entry> 506 </row> 507 508 </tbody> 509 </tgroup> 510 </informaltable> 511 <bridgehead renderas="sect4">Date Generator Parser Accessors</bridgehead> 512 <informaltable frame="all"> 513 <tgroup cols="2"> 514 <thead> 515 <row> 516 <entry valign="top" morerows="1">Syntax</entry> 517 <entry>Description</entry> 518 </row> 519 <row> 520 <entry>Example</entry> 521 </row> 522 </thead> 523 <tbody> 524 <row> 525 <entry valign="top" morerows="1"><screen>void element_strings(...) 526 Parameter: 527 collection_type</screen></entry> 528 <entry>Replace the set of date generator element string with a new set.</entry> 529 </row> 530 <row> 531 <entry><screen></screen></entry> 532 </row> 533 534 <row> 535 <entry valign="top" morerows="1"><screen>void element_strings(...) 536 Parameters: 537 string_type first 538 string_type second 539 string_type third 540 string_type fourth 541 string_type fifth 542 string_type last 543 string_type before 544 string_type after 545 string_type of</screen></entry> 546 <entry>Replace the set of date generator elements with new values.</entry> 547 </row> 548 <row> 549 <entry><screen></screen></entry> 550 </row> 551 552 <row> 553 <entry valign="top" morerows="1"><screen>get_partial_date_type(...) 554 Return Type: 555 facet_type::partial_date_type 556 Parameters: 557 stream_itr_type next 558 stream_itr_type str_end 559 ios_base 560 facet_type</screen></entry> 561 <entry>A templated function that parses a date_generator from the stream.</entry> 562 </row> 563 <row> 564 <entry>Parses a partial_date => "dd Month".</entry> 565 </row> 566 567 <row> 568 <entry valign="top" morerows="1"><screen>get_nth_kday_type(...) 569 Return Type: 570 facet_type::nth_kday_type 571 Parameters: 572 stream_itr_type next 573 stream_itr_type str_end 574 ios_base 575 facet_type</screen></entry> 576 <entry>A templated function that parses a date_generator from the stream.</entry> 577 </row> 578 <row> 579 <entry>Parses an nth_day_of_the_week_in_month => "nth weekday of month".</entry> 580 </row> 581 582 <row> 583 <entry valign="top" morerows="1"><screen>get_first_kday_type(...) 584 Return Type: 585 facet_type::firat_kday_type 586 Parameters: 587 stream_itr_type next 588 stream_itr_type str_end 589 ios_base 590 facet_type</screen></entry> 591 <entry>A templated function that parses a date_generator from the stream.</entry> 592 </row> 593 <row> 594 <entry>Parses a first_day_of_the_week_in_month => "first weekday of month".</entry> 595 </row> 596 597 <row> 598 <entry valign="top" morerows="1"><screen>get_last_kday_type(...) 599 Return Type: 600 facet_type::last_kday_type 601 Parameters: 602 stream_itr_type next 603 stream_itr_type str_end 604 ios_base 605 facet_type</screen></entry> 606 <entry>A templated function that parses a date_generator from the stream.</entry> 607 </row> 608 <row> 609 <entry>Parses a last_day_of_the_week_in_month => "last weekday of month".</entry> 610 </row> 611 612 <row> 613 <entry valign="top" morerows="1"><screen>get_kday_before_type(...) 614 Return Type: 615 facet_type::kday_before_type 616 Parameters: 617 stream_itr_type next 618 stream_itr_type str_end 619 ios_base 620 facet_type</screen></entry> 621 <entry>A templated function that parses a date_generator from the stream.</entry> 622 </row> 623 <row> 624 <entry>Parses a first_day_of_the_week_before => "weekday before"</entry> 625 </row> 626 627 <row> 628 <entry valign="top" morerows="1"><screen>get_kday_after_type(...) 629 Return Type: 630 facet_type::kday_after_type 631 Parameters: 632 stream_itr_type next 633 stream_itr_type str_end 634 ios_base 635 facet_type</screen></entry> 636 <entry>A templated function that parses a date_generator from the stream.</entry> 637 </row> 638 <row> 639 <entry>Parses a first_day_of_the_week_after => "weekday after".</entry> 640 </row> 641 642 </tbody> 643 </tgroup> 644 </informaltable> 645 </para> 646 647 <para>_____________________________________________________</para> 648 649 <anchor id="io_objects.special_values" /> 650 <bridgehead renderas="sect3">Special Values</bridgehead> 651 <para>The date_time library uses five special_values. They are: 652 <simplelist type="horiz" columns="5"> 653 <member>not_a_date_time</member> 654 <member>neg_infin</member> 655 <member>pos_infin</member> 656 <member>min_date_time</member> 657 <member>max_date_time</member> 658 </simplelist> 659 </para> 660 <para>The default set of strings used to represent these types are: "not-a-date-time", "-infinity", "+infinity", "minimum-date-time", "maximum-date-time". When output, the min_date-time and max_date_time appear as normal date/time representations: "1400-Jan-01" and "9999-Dec-31" repectively.</para> 661 662 <bridgehead renderas="sect4">Customization</bridgehead> 663 <para>The special values parser/formatter allows the user to set custom strings for these special values. These strings can be set as construction parameters to a new facet, or can be set in an existing facet via an accessor function.</para> 664 665 <bridgehead renderas="sect4">Special Values Formatter/Parser Reference</bridgehead> 666 The complete class references can be found here: <classname alt="boost::date_time::special_values_formatter">Special Values Formatter Doxygen Reference</classname> and here: <classname alt="boost::date_time::special_values_parser">Special Values Parser Doxygen Reference</classname> 667 668 <para> 669 <bridgehead renderas="sect4">Special Values Formatter Constructor</bridgehead> 670 <informaltable frame="all"> 671 <tgroup cols="2"> 672 <thead> 673 <row> 674 <entry valign="top">Syntax</entry> 675 <entry>Description</entry> 676 </row> 677 </thead> 678 <tbody> 679 <row> 680 <entry valign="top"><screen>special_values_formatter()</screen></entry> 681 <entry>Constructor uses defaults for special value strings.</entry> 682 </row> 683 <row> 684 <entry valign="top"><screen>special_values_formatter(...) 685 Parameters: 686 collection_type::iterator 687 collection_type::iterator</screen></entry> 688 <entry>Constructs using values in collection. NOTE: Only the first three strings of the collection will be used. Strings for minimum_date_time and maximum_date_time are ignored as those special values are output as normal dates/times.</entry> 689 </row> 690 <row> 691 <entry valign="top"><screen>special_values_formatter(...) 692 Parameters: 693 char_type* 694 char_type*</screen></entry> 695 <entry>Constructs special values formatter from an array of strings.</entry> 696 </row> 697 698 </tbody> 699 </tgroup> 700 </informaltable> 701 </para> 702 703 <para> 704 <bridgehead renderas="sect4">Special Values Formatter Accessors</bridgehead> 705 <informaltable frame="all"> 706 <tgroup cols="2"> 707 <thead> 708 <row> 709 <entry valign="top" morerows="1">Syntax</entry> 710 <entry>Description</entry> 711 </row> 712 <row> 713 <entry>Example</entry> 714 </row> 715 </thead> 716 <tbody> 717 <row> 718 <entry valign="top" morerows="1"><screen>OutItrT put_special(...) 719 Parameters: 720 OutItrT next 721 special_values value</screen></entry> 722 <entry>Puts the given special value into the stream.</entry> 723 </row> 724 <row> 725 <entry><screen>date d1(not_a_date_time); 726date d2(minimum_date_time); 727special_values_formatter formatter; 728formatter.put_special(itr, d1); 729// Puts: "not-a-date-time" 730formatter.put_special(itr, d2); 731// Puts: "1400-Jan-01"</screen></entry> 732 </row> 733 734 </tbody> 735 </tgroup> 736 </informaltable> 737 </para> 738 739 <para> 740 <bridgehead renderas="sect4">Special Values Parser Constructor</bridgehead> 741 <informaltable frame="all"> 742 <tgroup cols="2"> 743 <thead> 744 <row> 745 <entry valign="top">Syntax</entry> 746 <entry>Description</entry> 747 </row> 748 </thead> 749 <tbody> 750 <row> 751 <entry valign="top"><screen>special_values_parser()</screen></entry> 752 <entry></entry> 753 </row> 754 755 <row> 756 <entry valign="top"><screen>special_values_parser(...) 757 Parameters: 758 collection_type::iterator 759 collection_type::iterator</screen></entry> 760 <entry>Constructs a special values parser using the strings in the collection.</entry> 761 </row> 762 763 <row> 764 <entry valign="top"><screen>special_values_parser(...) 765 Parameter: 766 scpecial_values_parser</screen></entry> 767 <entry>Copy constructor.</entry> 768 </row> 769 770 <row> 771 <entry valign="top"><screen>special_values_parser(...) 772 Parameters: 773 string_type nadt_str 774 string_type neg_inf_str 775 string_type pos_inf_str 776 string_type min_dt_str 777 string_type max_dt_str</screen></entry> 778 <entry>Constructs a special values parser using the supplied strings.</entry> 779 </row> 780 781 </tbody> 782 </tgroup> 783 </informaltable> 784 </para> 785 786 <para> 787 <bridgehead renderas="sect4">Special Values Parser Accessors</bridgehead> 788 <informaltable frame="all"> 789 <tgroup cols="2"> 790 <thead> 791 <row> 792 <entry valign="top" morerows="1">Syntax</entry> 793 <entry>Description</entry> 794 </row> 795 <row> 796 <entry>Example</entry> 797 </row> 798 </thead> 799 <tbody> 800 <row> 801 <entry valign="top" morerows="1"><screen>void sv_strings(...) 802 Parameters: 803 string_type nadt_str 804 string_type neg_inf_str 805 string_type pos_inf_str 806 string_type min_dt_str 807 string_type max_dt_str</screen></entry> 808 <entry>Replace the set of special value strings with the given ones.</entry> 809 </row> 810 <row> 811 <entry><screen></screen></entry> 812 </row> 813 814 <row> 815 <entry valign="top" morerows="1"><screen>bool match(...) 816 Parameters: 817 stream_itr_type beg 818 stream_itr_type end 819 match_results</screen></entry> 820 <entry>Returns true if parse was successful. Upon a successful parse, <code>mr.current_match</code> will be set an int values corresponding to the equivalent special_value.</entry> 821 </row> 822 <row> 823 <entry><screen>// stream holds "maximum_date_time" 824typedef special_values_parser svp; 825svp parser; 826svp::match_results mr; 827if(parser.match(itr, str_end, mr)) { 828 d = date(static_cast<special_values>( 829 mr.match_results)) 830} else { 831 // error, failed parse 832} 833// d == "9999-Dec-31"</screen></entry> 834 </row> 835 836 </tbody> 837 </tgroup> 838 </informaltable> 839 </para> 840 841 <para>_____________________________________________________</para> 842 843 <anchor id="io_objects.format_date_parser" /> 844 <bridgehead renderas="sect3">Format Date Parser</bridgehead> 845 <para>The format date parser is the object that holds the strings for months and weekday names, as well as their abbreviations. Custom sets of strings can be set at construction time, or, the strings in an existing format_date_parser can be replaced through accessor functions. Both the constructor and the accessor functions take a vector of strings as their arguments.</para> 846 847 <bridgehead renderas="sect4">Format Date Parser Reference</bridgehead> 848 The complete class reference can be found here: <classname alt="boost::date_time::format_date_parser">Doxygen Reference</classname> 849 850 <para> 851 <bridgehead renderas="sect4">Format Date Parser Constructor</bridgehead> 852 <informaltable frame="all"> 853 <tgroup cols="2"> 854 <thead> 855 <row> 856 <entry valign="top">Syntax</entry> 857 <entry>Description</entry> 858 </row> 859 </thead> 860 <tbody> 861 <row> 862 <entry valign="top"><screen>format_date_parser(...) 863 Parameters: 864 string_type format 865 std::locale</screen></entry> 866 <entry>Creates a parser that uses the given format for parsing dates (in those functions where there is no format parameter). The names and abbreviations used are extracted from the given locale.</entry> 867 </row> 868 869 <row> 870 <entry valign="top"><screen>format_date_parser(...) 871 Parameters: 872 string_type format 873 input_collection_type 874 input_collection_type 875 input_collection_type 876 input_collection_type</screen></entry> 877 <entry>Creates a parser from using the given components. The input_collection_type parameters are for: short month names, long month names, short weekday names, and long weekday names (in that order). These collections must contain values for every month and every weekday (begining with January and Sunday).</entry> 878 </row> 879 880 <row> 881 <entry valign="top"><screen>format_date_parser(...) 882 Parameters: 883 format_date_parser</screen></entry> 884 <entry>Copy Constructor</entry> 885 </row> 886 887 </tbody> 888 </tgroup> 889 </informaltable> 890 </para> 891 892 <para> 893 <bridgehead renderas="sect4">Format Date Parser Accessors</bridgehead> 894 <informaltable frame="all"> 895 <tgroup cols="2"> 896 <thead> 897 <row> 898 <entry valign="top" morerows="1">Syntax</entry> 899 <entry>Description</entry> 900 </row> 901 <row> 902 <entry>Example</entry> 903 </row> 904 </thead> 905 <tbody> 906 <row> 907 <entry valign="top" morerows="1"><screen>string_type format()</screen></entry> 908 <entry>Returns the format that will be used when parsing dates in those functions where there is no format parameter.</entry> 909 </row> 910 <row> 911 <entry><screen></screen></entry> 912 </row> 913 914 <row> 915 <entry valign="top" morerows="1"><screen>void format(string_type)</screen></entry> 916 <entry>Sets the format that will be used when parsing dates in those functions where there is no format parameter.</entry> 917 </row> 918 <row> 919 <entry><screen></screen></entry> 920 </row> 921 922 <row> 923 <entry valign="top" morerows="1"><screen>void short_month_names(...) 924 Parameter: 925 input_collection_type names</screen></entry> 926 <entry>Replace the short month names used by the parser. The collection must contain values for each month, starting with January.</entry> 927 </row> 928 <row> 929 <entry><screen></screen></entry> 930 </row> 931 932 <row> 933 <entry valign="top" morerows="1"><screen>void long_month_names(...) 934 Parameter: 935 input_collection_type names</screen></entry> 936 <entry>Replace the long month names used by the parser. The collection must contain values for each month, starting with January.</entry> 937 </row> 938 <row> 939 <entry><screen></screen></entry> 940 </row> 941 942 <row> 943 <entry valign="top" morerows="1"><screen>void short_weekday_names(...) 944 Parameter: 945 input_collection_type names</screen></entry> 946 <entry>Replace the short weekday names used by the parser. The collection must contain values for each weekday, starting with Sunday.</entry> 947 </row> 948 <row> 949 <entry><screen></screen></entry> 950 </row> 951 952 <row> 953 <entry valign="top" morerows="1"><screen>void long_weekday_names(...) 954 Parameter: 955 input_collection_type names</screen></entry> 956 <entry>Replace the long weekday names used by the parser. The collection must contain values for each weekday, starting with Sunday.</entry> 957 </row> 958 <row> 959 <entry><screen></screen></entry> 960 </row> 961 962 <row> 963 <entry valign="top" morerows="1"><screen>date_type parse_date(...) 964 Parameters: 965 string_type input 966 string_type format 967 special_values_parser</screen></entry> 968 <entry>Parse a date from the given input using the given format.</entry> 969 </row> 970 <row> 971 <entry><screen>string inp("2005-Apr-15"); 972string format("%Y-%b-%d"); 973date d; 974d = parser.parse_date(inp, 975 format, 976 svp); 977// d == 2005-Apr-15</screen></entry> 978 </row> 979 980 <row> 981 <entry valign="top" morerows="1"><screen>date_type parse_date(...) 982 Parameters: 983 istreambuf_iterator input 984 istreambuf_iterator str_end 985 special_values_parser</screen></entry> 986 <entry>Parse a date from stream using the parser's format.</entry> 987 </row> 988 <row> 989 <entry><screen></screen></entry> 990 </row> 991 992 <row> 993 <entry valign="top" morerows="1"><screen>date_type parse_date(...) 994 Parameters: 995 istreambuf_iterator input 996 istreambuf_iterator str_end 997 string_type format 998 special_values_parser</screen></entry> 999 <entry>Parse a date from stream using the given format.</entry> 1000 </row> 1001 <row> 1002 <entry><screen>// stream holds "2005-04-15" 1003string format("%Y-%m-%d"); 1004date d; 1005d = parser.parse_date(itr, 1006 str_end, 1007 format, 1008 svp); 1009// d == 2005-Apr-15</screen></entry> 1010 </row> 1011 1012 <row> 1013 <entry valign="top" morerows="1"><screen>month_type parse_month(...) 1014 Parameters: 1015 istreambuf_iterator input 1016 istreambuf_iterator str_end 1017 string_type format</screen></entry> 1018 <entry>Parses a month from stream using given format. Throws bad_month if unable to parse.</entry> 1019 </row> 1020 <row> 1021 <entry><screen>// stream holds "March" 1022string format("%B"); 1023greg_month m; 1024m = parser.parse_month(itr, 1025 str_end, 1026 format); 1027// m == March</screen></entry> 1028 </row> 1029 1030 <row> 1031 <entry valign="top" morerows="1"><screen>day_type parse_day_of_month(...) 1032 Parameters: 1033 istreambuf_iterator input 1034 istreambuf_iterator str_end</screen></entry> 1035 <entry>Parses a day_of_month from stream. The day must appear as a two digit number (01-31), or a bad_day_of_month will be thrown.</entry> 1036 </row> 1037 <row> 1038 <entry><screen>// stream holds "01" 1039greg_day d; 1040d = parser.parse_day_of_month(itr, 1041 str_end); 1042// d == 1st</screen></entry> 1043 </row> 1044 1045 <row> 1046 <entry valign="top" morerows="1"><screen>day_type parse_var_day_of_month(...) 1047 Parameters: 1048 istreambuf_iterator input 1049 istreambuf_iterator str_end</screen></entry> 1050 <entry>Parses a day_of_month from stream. The day must appear as a one or two digit number (1-31), or a bad_day_of_month will be thrown.</entry> 1051 </row> 1052 <row> 1053 <entry><screen>// stream holds "1" 1054greg_day d; 1055d = parser.parse_var_day_of_month(itr, 1056 str_end); 1057// d == 1st</screen></entry> 1058 </row> 1059 1060 <row> 1061 <entry valign="top" morerows="1"><screen>day_of_week_type parse_weekday(...) 1062 Parameters: 1063 istreambuf_iterator input 1064 istreambuf_iterator str_end 1065 string_type format</screen></entry> 1066 <entry>Parse a weekday from stream according to the given format. Throws a bad_weekday if unable to parse.</entry> 1067 </row> 1068 <row> 1069 <entry><screen>// stream holds "Tue" 1070string format("%a"); 1071greg_weekday wd; 1072wd = parser.parse_weekday(itr, 1073 str_end, 1074 format); 1075// wd == Tuesday</screen></entry> 1076 </row> 1077 1078 <row> 1079 <entry valign="top" morerows="1"><screen>year_type parse_year(...) 1080 Parameters: 1081 istreambuf_iterator input 1082 istreambuf_iterator str_end 1083 string_type format</screen></entry> 1084 <entry>Parse a year from stream according to given format. Throws bad year if unable to parse.</entry> 1085 </row> 1086 <row> 1087 <entry><screen>// stream holds "98" 1088string format("%y"); 1089greg_year y; 1090y = parser.parse_year(itr, 1091 str_end, 1092 format); 1093// y == 1998</screen></entry> 1094 </row> 1095 1096 </tbody> 1097 </tgroup> 1098 </informaltable> 1099 </para> 1100 1101</section> 1102