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