# Date Time Input/Output

Date Time IO System

Exception Handling on Streams

As of version 1.33, the date_time library utilizes a new IO streaming system. This new system gives the user great control over how dates and times can be represented. The customization options can be broken down into two groups: format flags and string elements. Format flags provide flexibility in the order of the date elements as well as the type. Customizing the string elements allows the replacement of built in strings from month names, weekday names, and other strings used in the IO.

The output system is based on a date_facet (derived from std::facet), while the input system is based on a date_input_facet (also derived from std::facet). The time and local_time facets are derived from these base types. The output system utilizes three formatter objects, whereas the input system uses four parser objects. These formatter and parser objetcs are also customizable.

It is important to note, that while all the examples shown here use narrow streams, there are wide stream facets available as well (see IO Objects for a complete list).

It should be further noted that not all compilers are capable of using this IO system. For those compilers the IO system used in previous `date_time` versions is still available. The "legacy IO" is automatically selected for these compilers, however, the legacy IO system can be manually selected by defining `USE_DATE_TIME_PRE_1_33_FACET_IO`. See the Build-Compiler Information for more information.

Exception Handling on Streams

When an error occurs during the input streaming process, the `std::ios_base::failbit` will (always) be set on the stream. It is also possible to have exceptions thrown when an error occurs. To "turn on" these exceptions, call the stream's `exceptions` function with a parameter of `std::ios_base::failbit`.

    // "Turning on" exceptions
    date d(not_a_date_time);
    std::stringstream ss;
    ss.exceptions(std::ios_base::failbit);
    ss.str("204-Jan-01");
    ss >> d; // throws bad_year exception AND sets failbit on stream

A simple example of this new system:

    //example to customize output to be "LongWeekday LongMonthname day, year"
    //                                  "%A %b %d, %Y"
    date d(2005,Jun,25);
    date_facet* facet(new date_facet("%A %B %d, %Y"));
    std::cout.imbue(std::locale(std::cout.getloc(), facet));
    std::cout << d << std::endl;
    // "Saturday June 25, 2005"

The following table lists the available facets.

IO Objects

Output | Input
--- | ---
`date_facet` | `date_input_facet`
`wdate_facet` | `wdate_input_facet`
`time_facet` | `time_input_facet`
`wtime_facet` | `wtime_input_facet`
`local_time_facet`* | `local_time_input_facet`*
`wlocal_time_facet`* | `wlocal_time_input_facet`*

* These links lead to the `time_facet` and `time_input_facet` reference sections. They are not actual classes but typedefs.

Formatter/Parser Objects

To implement the new i/o facets the date-time library uses a number of new parsers and formatters. These classes are available for users that want to implement specialized input/output routines.

Output | Input
--- | ---
`period_formatter` | `period_parser`
`date_generator_formatter` | `date_generator_parser`
`special_values_formatter` | `special_values_parser`
| `format_date_parser`