| Home | Libraries | People | FAQ | More

## 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"

### Format Flags

Many of the format flags this new system uses for output are those used by `strftime(...)`, but not all. Some new flags have been added, and others overridden. The input system supports only specific flags, therefore, not all flags that work for output will work with input (we are currently working to correct this situation).

The following tables list the all the flags available for both date_time IO as well as strftime. Format flags marked with a single asterisk (*) have a behavior unique to date_time. Those flags marked with an exclamation point (!) are not usable for input (at this time). The first table is for dates, and the second table is for times.

Date Facet Format Flags

Format Specifier | Description
--- | ---
Example

    %a

Abbreviated weekday name

    "Mon" => Monday

    %A

Long weekday name

    "Monday"

    %b

Abbreviated month name

    "Feb" => February

    %B

Full month name

    "February"

    %c !

The preferred date and time representation for the current locale.

    %C !

The century number (year/100) as a 2-digit integer.

    %d

Day of the month as decimal 01 to 31

    %D !

Equivalent to %m/%d/%y

    %e

Like %d, the day of the month as a decimal number, but a leading zero is replaced by a space

    %G !

This has the same format and value as %y, except that if the ISO week number belongs to the previous or next year, that year is used instead.

    %g !

Like %G, but without century.

    %h !

Equivalent to %b

    %j

Day of year as decimal from 001 to 366 for leap years, 001 - 365 for non-leap years.

    "060" => Feb-29

    %m

Month name as a decimal 01 to 12

    "01" => January

    %u !

The day of the week as a decimal, range 1 to 7, Monday being 1.

    %U

The week number of the current year as a decimal number, range 00 to 53, starting with the first Sunday as the first day of week 01. In 2005, Jan 1st falls on a Saturday, so therefore it falls within week 00 of 2005 (week 00 spans 2004-Dec-26 to 2005-Jan-01. This also happens to be week 53 of 2004).

    date d(2005, Jan, 1); // Saturday
      // with format %U
      ss << d; // "00"
      d += day(1); // Sunday
      ss << d; // "01" beginning of week 1

    %V !

The ISO 8601:1988 week number of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the current year, and with Monday as the first day of the week.

    %w

Weekday as decimal number 0 to 6

    "0" => Sunday

    %W

Week number 00 to 53 where Monday is first day of week 1

    date d(2005, Jan, 2); // Sunday
      // with format %W
      ss << d; // "00"
      d += day(1); // Monday
      ss << d; // "01" beginning of week 1

    %x

Implementation defined date format from the locale.

    date d(2005,Oct,31);
      date_facet* f = new date_facet("%x");

      locale loc = locale(locale("en_US"), f);
      cout.imbue(loc);
      cout << d; // "10/31/2005"

      loc = locale(locale("de_DE"), f);
      cout.imbue(loc);
      cout << d; // "31.10.2005"

    %y

Two digit year

    "05" => 2005

    %Y

Four digit year

    "2005"

    %Y-%b-%d

Default date format

    "2005-Apr-01"

    %Y%m%d

ISO format

    "20050401"

    %Y-%m-%d

ISO extended format

    "2005-04-01"

Time Facet Format Flags

Format Specifier | Description
--- | ---
Example

    %- *!

Placeholder for the sign of a duration. Only displays when the duration is negative.

    "-13:15:16"

    %+ *!

Placeholder for the sign of a duration. Always displays for both positive and negative.

    "+13:15:16"

    %f

Fractional seconds are always used, even when their value is zero

    "13:15:16.000000"

    %F *

Fractional seconds are used only when their value is not zero.

    "13:15:16"
      "05:04:03.001234"

    %I !

The hour as a decimal number using a 12-hour clock

    %k !

The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank.

    %l !

The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank.

    %p !

Either `AM' or `PM' according to the given time value, or the corresponding strings for the current locale.

    %P !

Like %p but in lowercase: `am' or `pm' or a corresponding string for the current locale.

    %r !

The time in a.m. or p.m. notation. In the POSIX locale this is equivalent to `%I:%M:%S %p'

    %R !

The time in 24-hour notation (%H:%M)

    %s *

Seconds with fractional seconds.

    "59.000000"

    %S

Seconds only

    "59"

    %T !

The time in 24-hour notation (%H:%M:%S)

    %q

ISO time zone (output only). This flag is ignored when using the time_facet with a ptime.

    "-0700" // Mountain Standard Time

    %Q

ISO extended time zone (output only). This flag is ignored when using the time_facet with a ptime.

    "-05:00" // Eastern Standard Time

    %z *!

Abbreviated time zone (output only). This flag is ignored when using the time_facet with a ptime.

    "MST" // Mountain Standard Time

    %Z *!

Full time zone name (output only). This flag is ignored when using the time_facet with a ptime.

    "EDT" // Eastern Daylight Time

    %ZP *

Posix time zone string (available to both input and output). This flag is ignored when using the time_facet with a ptime. For complete details on posix time zone strings, see posix_time_zone class.

    "EST-05EDT+01,M4.1.0/02:00,M10.5.0/02:00"

    %x %X

Implementation defined date/time format from the locale.

    date d(2005,Oct,31);
      ptime pt(d, hours(20));
      time_facet* f = new time_facet("%x %X");

      locale loc = locale(locale("en_US"), f);
      cout.imbue(loc);
      cout << pt; // "10/31/2005 08:00:00 PM"

      loc = locale(locale("de_DE"), f);
      cout.imbue(loc);
      cout << pt; // "31.10.2005 20:00:00"

    %Y%m%dT%H%M%S%F%q

ISO format

    "20051015T131211-0700"
      // Oct 15, 2005 13:12:11 MST

    %Y-%m-%d %H:%M:%S%F%Q

Extended ISO format

    "2005-10-15 13:12:11-07:00"

    %Y-%b-%d %H:%M:%S%F %z

Default format used when outputting ptime and local_date_time.

    "2005-Oct-15 13:12:11 MST"

    %Y-%b-%d %H:%M:%S%F %ZP

Default format used when inputting ptime and local_date_time.

    "2005-Oct-15 13:12:11 MST-07"

    %-%H:%M:%S%F !

Default time_duration format for output. Sign will only be displayed for negative durations.

    "-13:14:15.003400"

    %H:%M:%S%F

Default time_duration format for input.

    "13:14:15.003400"

* Signifies flags that have a behavior unique to `date_time`.

! Signifies flags that currently do not work for input.

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`

### Date Facet

Introduction - Construction - Accessors

### Introduction

The `boost::date_time::date_facet` enables users to have significant control over the output streaming of dates (and other gregorian objects). The date_facet is typedef'd in the `gregorian` namespace as `date_facet` and `wdate_facet`.

### Construction

Syntax | Description
--- | ---

    date_facet()

Default constructor

    date_facet(...)
      Parameters:
        char_type* format
        input_collection_type

Format given will be used for date output. All other formats will use their defaults. Collection is the set of short names to be used for months. All other name collections will use their defaults.

    date_facet(...)
      Parameters:
        char_type* format
        period_formatter_type
        special_values_formatter_type
        date_gen_formatter_type

Format given will be used for date output. The remaining parameters are formatter objects. Further details on these objects can be found here. This constructor also provides default arguments for all parameters except the format. Therefore, `date_facet("%m %d %Y")` will work.

### Accessors

Syntax | Description
--- | ---
Example

    void format(char_type*)

Set the format for dates.

    date_facet* f = new date_facet();
    f->format("%m %d %Y");

    void set_iso_format()

Sets the date format to ISO

    f->set_iso_format();
    // "%Y%m%d"

    void set_iso_extended_format()

Sets the date format to ISO Extended

    f->set_iso_extended_format();
    // "%Y-%m-%d"

    void month_format(char_type*)

Set the format for months when they are 'put' individually.

    f->month_format("%B");
    ss << greg_month(12); // "December"

    void weekday_format(char_type*)

Set the format for weekdays when they are 'put' individually.

    f->weekday_format("%a");
    ss << greg_weekday(2); // "Tue"

    void period_formatter(...)
      Parameter:
        period_formatter_type

Replaces the period formatter object with a user created one.

see the tutorial for a complete example.

    void special_values_formatter(...)
      Parameter:
        special_values_formatter_type

Replaces the special_values formatter object with a user created one.

see the tutorial for a complete example.

    void date_gen_phrase_strings(...)
      Parameters:
        input_collection_type
        date_gen_formatter_type::
          phrase_elements

Sets new date generator phrase strings in date_gen_formatter. The input collection is a vector of strings (for details on these strings see date generator formatter/parser documentation). The phrase_elements parameter is an enum, defined in the date_generator_formatter object, that has a default value of 'first'. It is used to indicate what the position of the first string in the collection will be.

    void short_weekday_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'putting' short weekdays.

see the tutorial for a complete example.

    void long_weekday_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'putting' long weekdays.

see the tutorial for a complete example.

    void short_month_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'putting' short months.

see the tutorial for a complete example.

    void long_month_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'putting' long months.

see the tutorial for a complete example.

    OutItrT put(...)
      Common parameters for all
      'put' functions:
        OutItrT
        ios_base
        char_type
      Unique parameter for 'put' funcs:
        gregorian object

There are 12 put functions in the date_facet. The common paraeters are: an iterator pointing to the next item in the stream, an ios_base object, and the fill character. Each unique gregorian object has it's own put function. Each unique put function is described below.

    OutItrT put(..., date)

Puts a date object into the stream using the format set by `format(...)` or the default.

    OutItrT put(..., days)

Puts a days object into the stream as a number.

    OutItrT put(..., month)

Puts a month object into the stream using the format set by `month_format(...)` or the default.

    OutItrT put(..., day)

Puts a day of month object into the stream as a two digit number.

    "01" // January 1st

    OutItrT put(..., day_of_week)

Puts a day of week object into the stream using the format set by `weekday_format(...)` or the default.

    OutItrT put(..., date_period)

Puts a date_period into the stream. The format of the dates will use the format set by `format(..)` or the default date format. The type of period (open or closed range) and the delimiters used are those used by the period_formatter.

    OutItrT put(..., partial_date)

Puts a partial_date date_generator object into the stream. The month format used is set by `month_format(..)` or the default. The day of month is represented as a two digit number.

    "01 Jan" // default formats
    "01 January" // long month format

    OutItrT put(..., date_generator)
      Date Generator Type:
        nth_day_of_the_week_in_month

Puts a nth_day_of_the_week_in_month object into the stream. The month format is set by `month_format(...)` or the default. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_formatter.

    "third Fri in May" // defaults

    OutItrT put(..., date_generator)
      Date Generator Type:
        first_day_of_the_week_in_month

Puts a first_day_of_the_week_in_month object into the stream. The month format is set by `month_format(...)` or the default. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_formatter.

    "first Wed of Jun" // defaults

    OutItrT put(..., date_generator)
      Date Generator Type:
        last_day_of_the_week_in_month

Puts a last_day_of_the_week_in_month object into the stream. The month format is set by `month_format(...)` or the default. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_formatter.

    "last Tue of Mar" // defaults

    OutItrT put(..., date_generator)
      Date Generator Type:
        first_day_of_the_week_after

Puts a first_day_of_the_week_after object into the stream. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_formatter.

    "first Sat after" // defaults

    OutItrT put(..., date_generator)
      Date Generator Type:
        first_day_of_the_week_before

Puts a first_day_of_the_week_before object into the stream. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_formatter.

    "first Mon before" // defaults

### Date Input Facet

Introduction - Construction - Accessors

### Introduction

The `boost::date_time::date_input_facet` enables users to have significant control how dates (and other gregorian objects) are streamed in. The date_input_facet is typedef'd in the `gregorian` namespace as `date_input_facet` and `wdate_input_facet`.

### Construction

Syntax | Description
--- | ---

    date_input_facet()

Default constructor

    date_input_facet(string_type format)

Format given will be used for date input. All other formats will use their defaults.

    date_input_facet(...)
      Parameters:
        string_type format
        format_date_parser_type
        special_values_parser_type
        period_parser_type
        date_gen_parser_type

Format given will be used for date input. The remaining parameters are parser objects. Further details on these objects can be found here.

### Accessors

Syntax | Description
--- | ---
Example

    void format(char_type*)

Set the format for dates.

    date_input_facet* f =
        new date_input_facet();
    f->format("%m %d %Y");

    void set_iso_format()

Sets the date format to ISO

    f->set_iso_format();
    // "%Y%m%d"

    void set_iso_extended_format()

Sets the date format to ISO Extended

    f->set_iso_extended_format();
    // "%Y-%m-%d"

    void month_format(char_type*)

Set the format when 'get'ing months individually.

    f->month_format("%B");
    ss.str("March");
    ss >> m; // March

    void weekday_format(char_type*)

Set the format when 'get'ing weekdays individually.

    f->weekday_format("%a");
    ss.str("Sun");
    ss >> wd; // Sunday

    void year_format(char_type*)

Set the format when 'get'ing years individually.

    f->weekday_format("%y");
    ss.str("04");
    ss >> year; // 2004

    void period_parser(...)
      Parameter:
        period_parser_type

Replaces the period parser object with a user created one.

see the tutorial for a complete example.

    void special_values_parser(...)
      Parameter:
        special_values_parser_type

Replaces the special_values parser object with a user created one.

see the tutorial for a complete example.

    void date_gen_phrase_strings(...)
      Parameters:
        input_collection_type

Sets new date generator phrase strings in date_gen_parser. The input collection is a vector of strings (for details on these strings see date generator formatter/parser documentation).

    void short_weekday_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'getting' short weekdays.

see the tutorial for a complete example.

    void long_weekday_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'getting' long weekdays.

see the tutorial for a complete example.

    void short_month_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'getting' short months.

see the tutorial for a complete example.

    void long_month_names(...)
      Parameter:
        input_collection_type

Replace strings used when 'getting' long months.

see the tutorial for a complete example.

    InItrT get(...)
      Common parameters for all
      'get' functions:
        InItrT from
        InItrT to
        ios_base
      Unique parameter for 'get' funcs:
        gregorian object

There are 13 get functions in the date_input_facet. The common parameters are: an iterator pointing to the begining of the stream, an iterator pointing to the end of the stream, and an ios_base object. Each unique gregorian object has it's own get function. Each unique get function is described below.

    InItrT get(..., date)

Gets a date object from the stream using the format set by `format(...)` or the default.

    ss.str("2005-Jan-01");
    ss >> d; // default format

    InItrT get(..., month)

Gets a month object from the stream using the format set by `month_format(...)` or the default.

    ss.str("Feb");
    ss >> m; // default format

    InItrT get(..., day_of_week)

Gets a day of week object from the stream using the format set by `weekday_format(...)` or the default.

    ss.str("Sun");
    ss >> dow; // default format

    InItrT get(..., day)

Gets a day of month object from the stream as a two digit number.

    "01" // January 1st

    InItrT get(..., year)

Gets a year object from the stream as a number. The number of expected digits depends on the year format.

    ss/str("2005");
    ss >> y; // default format

    InItrT get(..., days)

Gets a days object from the stream as a number.

    ss.str("356");
    ss >> dys; // a full year

    InItrT get(..., date_period)

Gets a date_period from the stream. The format of the dates will use the format set by `format(..)` or the default date format. The type of period (open or closed range) and the delimiters used are those used by the period_parser.

see the tutorial for a complete example.

    InItrT get(..., partial_date)

Gets a partial_date date_generator object from the stream. The month format used is set by `month_format(..)` or the default. The day of month is represented as a two digit number.

    "01 Jan" // default formats
    "01 January" // long month format

    InItrT get(..., date_generator)
      Date Generator Type:
        nth_day_of_the_week_in_month

Gets a nth_day_of_the_week_in_month object from the stream. The month format is set by `month_format(...)` or the default. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_parser.

    "third Fri in May" // defaults

    InItrT get(..., date_generator)
      Date Generator Type:
        first_day_of_the_week_in_month

Gets a first_day_of_the_week_in_month object from the stream. The month format is set by `month_format(...)` or the default. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_parser.

    "first Wed of Jun" // defaults

    InItrT get(..., date_generator)
      Date Generator Type:
        last_day_of_the_week_in_month

Gets a last_day_of_the_week_in_month object from the stream. The month format is set by `month_format(...)` or the default. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_parser.

    "last Tue of Mar" // defaults

    InItrT get(..., date_generator)
      Date Generator Type:
        first_day_of_the_week_after

Gets a first_day_of_the_week_after object from the stream. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_parser.

    "first Sat after" // defaults

    InItrT get(..., date_generator)
      Date Generator Type:
        first_day_of_the_week_before

Gets a first_day_of_the_week_before object from the stream. The weekday format is set by `weekday_format(...)` or the default. The remaining phrase elements are set in the date_generator_parser.

    "first Mon before" // defaults

### Time Facet

Introduction - Construction - Accessors

### Introduction

The `boost::date_time::time_facet` is an extension of the `boost::date_time::date_facet`. The time_facet is typedef'ed in the `posix_time` namespace as `time_facet` and `wtime_facet`. It is typedef'd in the `local_time` namespace as `local_time_facet` and `wlocal_time_facet`.

### Construction

Syntax | Description
--- | ---

    time_facet()

Default constructor

    time_facet(...)
      Parameters:
        char_type* format
        period_formatter_type
        special_values_formatter_type
        date_gen_formatter_type

Format given will be used for time output. The remaining parameters are formatter objects. Further details on these objects can be found here. This constructor also provides default arguments for all parameters except the format. Therefore, `time_facet("%H:%M:S %m %d %Y")` will work.

### Accessors

The time_facet inherits all the public date_facet methods. Therefore, the date_facet methods are not listed here. Instead, they can be found by following this link.

Syntax | Description
--- | ---
Example

    void time_duration_format(...)
      Parameter:
        char_type*

Sets the time_duration format. The time_duration format has the ability to display the sign of the duration. The `'%+'` flag will always display the sign. The `'%-'` will only display if the sign is negative. Currently the '-' and '+' characters are used to denote the sign.

    f->time_duration_format("%+%H:%M");
    // hours and minutes only w/ sign always displayed
    time_duration td1(3, 15, 56);
    time_duration td2(-12, 25, 32);
    ss << td1; // "+03:15:56"
    ss << td2; // "-12:25:56"

    void set_iso_format()

Sets the date and time format to ISO.

    f->set_iso_format();
    // "%Y%m%dT%H%M%S%F%q"

    void set_iso_extended_format()

Sets the date and time format to ISO Extended

    f->set_iso_extended_format();
    // "%Y-%m-%d %H:%M:%S%F%Q"

    OutItrT put(...)
      Common parameters for all
      'put' functions:
        OutItrT
        ios_base
        char_type
      Unique parameter for 'put' funcs:
        posix_time object

There are 3 put functions in the time_facet. The common parameters are: an iterator pointing to the next item in the stream, an ios_base object, and the fill character. Each unique posix_time object has it's own put function. Each unique put function is described below.

    OutItrT put(..., ptime)

Puts a ptime object into the stream using the format set by `format(...)` or the default.

    OutItrT put(..., time_duration)

Puts a time_duration object into the stream using the format set by `time_duration_format(...)` or the default.

    OutItrT put(..., time_period)

Puts a time_period into the stream. The format of the dates and times will use the format set by `format(..)` or the default date/time format. The type of period (open or closed range) and the delimiters used are those used by the period_formatter.

### Time Input Facet

Introduction - Construction - Accessors

### Introduction

The `boost::date_time::time_input_facet` is an extension of the `date_input_facet`. It is typedef'ed in the `boost::posix_time` namespace as `time_input_facet` and `wtime_input_facet`. It is typedef'ed in the `boost::local_time` namespace as `local_time_input_facet` and `wlocal_time_input_facet`.

### Construction

Syntax | Description
--- | ---

    time_input_facet()

Default constructor

    time_input_facet(string_type)

Format given will be used for date/time input. All other formats will use their defaults.

    time_input_facet(...)
      Parameters:
        string_type format
        format_date_parser_type
        special_values_parser_type
        period_parser_type
        date_gen_parser_type

Format given will be used for date/time input. The remaining parameters are parser objects. Further details on these objects can be found here.

### Accessors

The time_input_facet inherits all the public date_input_facet methods. Therefore, the date_input_facet methods are not listed here. Instead, they can be found by following this link.

Syntax | Description
--- | ---
Example

    void set_iso_format()

Sets the time format to ISO

    f->set_iso_format();
    // "%Y%m%dT%H%M%S%F%q"
    "20051225T132536.789-0700"

    void set_iso_extended_format()

Sets the date format to ISO Extended

    f->set_iso_extended_format();
    // "%Y-%m-%d %H:%M:%S%F %Q"
    "2005-12-25 13:25:36.789 -07:00"

    void time_duration_format(...)
      Parameter:
        char_type*

Sets the time_duration format.

    f->time_duration_format("%H:%M");
    // hours and minutes only

    InItrT get(...)
      Common parameters for all
      'get' functions:
        InItrT from
        InItrT to
        ios_base
      Unique parameter for 'get' funcs:
        gregorian object

There are 3 get functions in the time_input_facet. The common parameters are: an iterator pointing to the begining of the stream, an iterator pointing to the end of the stream, and an ios_base object. Each unique gregorian object has it's own get function. Each unique get function is described below.

    InItrT get(..., ptime)

Gets a ptime object from the stream using the format set by `format(...)` or the default.

    ss.str("2005-Jan-01 13:12:01");
    ss >> pt; // default format

    InItrT get(..., time_duration)

Gets a time_duration object from the stream using the format set by `time_duration_format(...)` or the default.

    ss.str("01:25:15.000123000");
    ss >> td; // default format

    InItrT get(..., time_period)

Gets a time_period from the stream. The format of the dates/times will use the format set by `format(..)` or the default date and time format. The type of period (open or closed range) and the delimiters used are those used by the period_parser.

see the tutorial for a complete example.

### Date Time Formatter/Parser Objects

Periods | Date Generators | Special Values | Format Date Parser

### Periods

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.

#### Period Form

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.

    [2003-Jan-01/2003-Dec-31] <-- period holding 365 days
    [2003-Jan-01/2004-Jan-01) <-- period holding 365 days

#### Delimiters

There are four delimiters. The default values are

"\" - separator
"[" - start delimiter
")" - open range end delimiter
"]" - closed range end delimiter

A user can provide a custom set of delimiters. Custom delimiters may contain spaces.

#### Customization

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.

#### Period Formatter/Parser Reference

The complete class reference can be found here: `Period Formatter Doxygen Reference` and here: `Period Parser Doxygen Reference`

#### Period Formatter Construction

Syntax | Description
--- | ---

    period_formatter(...)
      Parameters:
        range_display_options
        char_type*
        char_type*
        char_type*
        char_type*

NOTE: All five construction parameters have default values so this constructor also doubles as the default constructor. The `range_display_options` is a public type enum of the `period_formatter` 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.

#### Period Formatter Accessors

Syntax | Description
--- | ---
Example

    range_display_options range_option()

Returns the current setting for the range display (either AS_OPEN_RANGE or AS_CLOSED_RANGE).

    void range_option(...)
      Parameter:
        range_display_options

Sets the option for range display (either AS_OPEN_RANGE or AS_CLOSED_RANGE).

    void delimiter_strings(...)
      Parameters:
        string_type
        string_type
        string_type
        string_type

Set new delimiter strings in the formatter.

    string beg("->| ");
    string sep(" || ");
    string opn(" ->|");
    string clo(" |<-");
    pf.delimiter_strings(beg, sep,
                         opn, clo);

    put_period_start_delimeter(...)
      Return Type:
        OutItrT
      Parameter:
        OutItrT

Puts the start delimiter into the stream at position pointed to by OutItrT parameter.

    put_period_sepatator(...)
      Return Type:
        OutItrT
      Parameter:
        OutItrT

Puts the separator into the stream at position pointed to by OutItrT parameter.

    put_period_end_delimeter(...)
      Return Type:
        OutItrT
      Parameter:
        OutItrT

Puts the end delimiter into the stream at position pointed to by OutItrT parameter.

    OutItrT put_period(...)
      Parameters:
        OutItrT
        ios_base
        char_type
        period_type
        facet_type

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.

#### Period Parser Construction

Syntax | Description
--- | ---

    period_parser(...)
      Parameters:
        period_range_option
        char_type*
        char_type*
        char_type*
        char_type*

NOTE: All five construction parameters have default values so this constructor also doubles as the default constructor. The `period_range_option` is a public type enum of the `period_parser` 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.

    period_parser(period_parser)

Copy constructor

#### Period Parser Accessors

Syntax | Description
--- | ---
Example

    period_range_option range_option()

Returns the current setting for the period range (either AS_OPEN_RANGE or AS_CLOSED_RANGE).

    void range_option(...)
      Parameter:
        period_range_option

Sets the option for period range (either AS_OPEN_RANGE or AS_CLOSED_RANGE).

    void delimiter_strings(...)
      Parameters:
        string_type
        string_type
        string_type
        string_type

Set new delimiter strings in the parser.

    string beg("->| ");
    string sep(" || ");
    string opn(" ->|");
    string clo(" |<-");
    pp.delimiter_strings(beg, sep,
                         opn, clo);

    collection_type delimiter_strings()

Returns the set of delimiter strings currently held in the parser.

    period_type get_period(...)
      Parameters:
        stream_itr_type
        stream_itr_type
        ios_base
        period_type
        duration_type
        facet_type

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 `date_period` would use `days` as a duration_type. The period will be parsed according to the formats and strings found in the facet parameter.

_____________________________________________________

### Date Generators

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.

#### Customization

The default "phrase_strings" are:

"first" | "second" | "third" | "fourth" | "fifth" | "last" | "before" | "after" | "of"

A custom set of phrase_strings must maintain this order of occurance (Ex: "1st", "2nd", "3rd", "4th", "5th", "last", "prior", "past", "in").

Examples using default phrase_strings and default facet formats for weekday & month:

    "first Tue of Mar"

And using custom phrase_strings:

    "1st Tue in Mar"

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.

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".

#### Date Generator Reference

The complete class references can be found here: `Date Generator Formatter Doxygen Reference` and here: `Date Generator Parser Doxygen Reference`

#### Date Generator Formatter Construction

Syntax | Description
--- | ---

    date_generator_formatter()

Uses the default date generator elements.

    date_generator_formatter(...)
      Parameters:
        string_type first_element
        string_type second_element
        string_type third_element
        string_type fourth_element
        string_type fifth_element
        string_type last_element
        string_type before_element
        string_type after_element
        string_type of_element

Constructs a date_generator_formatter using the given element strings.

#### Date Generator Formatter Accessors

Syntax | Description
--- | ---
Example

    void elements(...)
      Parameters:
        collection_type
        phrase_elements

Replace the current phrase elements with a collection of new ones. The `phrase_elements` parameter is an enum that indicates what the first element in the new collection is (defaults to first).

    // col is a collection holding
    // "final", "prior", "following",
    // and "in"
    typedef date_generator_formatter dgf;
    dgf formatter();
    formatter.elements(col, dgf::last);
    // complete elements in dgf are now:
    "first", "second", "third",
    "fourth", "fifth", "final",
    "prior", "following", and "in"

    put_partial_date(...)
      Return Type:
        facet_type::OutItrT
      Parameters:
        OutItrT next
        ios_base
        char_type fill
        partial_date
        facet_type

A put function for partial_date. This is a templated function that takes a facet_type as a parameter.

Put a partial_date => "dd Month".

    put_nth_kday(...)
      Return Type:
        facet_type::OutItrT
      Parameters:
        OutItrT next
        ios_base
        char_type fill
        nth_kday_type
        facet_type

A put function for nth_kday_type. This is a templated function that takes a facet_type as a parameter.

Put an nth_day_of_the_week_in_month => "nth weekday of month".

    put_first_kday(...)
      Return Type:
        facet_type::OutItrT
      Parameters:
        OutItrT next
        ios_base
        char_type fill
        first_kday_type
        facet_type

A put function for first_kday_type. This is a templated function that takes a facet_type as a parameter.

Put a first_day_of_the_week_in_month => "first weekday of month".

    put_last_kday(...)
      Return Type:
        facet_type::OutItrT
      Parameters:
        OutItrT next
        ios_base
        char_type fill
        last_kday_type
        facet_type

A put function for last_kday_type. This is a templated function that takes a facet_type as a parameter.

Put a last_day_of_the_week_in_month => "last weekday of month".

    put_kday_before(...)
      Return Type:
        facet_type::OutItrT
      Parameters:
        OutItrT next
        ios_base
        char_type fill
        kday_before_type
        facet_type

A put function for kday_before_type. This is a templated function that takes a facet_type as a parameter.

Put a first_day_of_the_week_before => "weekday before"

    put_kday_after(...)
      Return Type:
        facet_type::OutItrT
      Parameters:
        OutItrT next
        ios_base
        char_type fill
        kday_after_type
        facet_type

A put function for kday_after_type. This is a templated function that takes a facet_type as a parameter.

Put a first_day_of_the_week_after => "weekday after".

#### Date Generator Parser Construction

Syntax | Description
--- | ---

    date_generator_parser()

Uses the default date generator elements.

    date_generator_parser(...)
      Parameter:
        date_generator_parser

Copy Constructor

    date_generator_parser(...)
      Parameters:
        string_type first_element
        string_type second_element
        string_type third_element
        string_type fourth_element
        string_type fifth_element
        string_type last_element
        string_type before_element
        string_type after_element
        string_type of_element

Constructs a date_generator_parser using the given element strings.

#### Date Generator Parser Accessors

Syntax | Description
--- | ---
Example

    void element_strings(...)
      Parameter:
        collection_type

Replace the set of date generator element string with a new set.

    void element_strings(...)
      Parameters:
        string_type first
        string_type second
        string_type third
        string_type fourth
        string_type fifth
        string_type last
        string_type before
        string_type after
        string_type of

Replace the set of date generator elements with new values.

    get_partial_date_type(...)
      Return Type:
        facet_type::partial_date_type
      Parameters:
        stream_itr_type next
        stream_itr_type str_end
        ios_base
        facet_type

A templated function that parses a date_generator from the stream.

Parses a partial_date => "dd Month".

    get_nth_kday_type(...)
      Return Type:
        facet_type::nth_kday_type
      Parameters:
        stream_itr_type next
        stream_itr_type str_end
        ios_base
        facet_type

A templated function that parses a date_generator from the stream.

Parses an nth_day_of_the_week_in_month => "nth weekday of month".

    get_first_kday_type(...)
      Return Type:
        facet_type::firat_kday_type
      Parameters:
        stream_itr_type next
        stream_itr_type str_end
        ios_base
        facet_type

A templated function that parses a date_generator from the stream.

Parses a first_day_of_the_week_in_month => "first weekday of month".

    get_last_kday_type(...)
      Return Type:
        facet_type::last_kday_type
      Parameters:
        stream_itr_type next
        stream_itr_type str_end
        ios_base
        facet_type

A templated function that parses a date_generator from the stream.

Parses a last_day_of_the_week_in_month => "last weekday of month".

    get_kday_before_type(...)
      Return Type:
        facet_type::kday_before_type
      Parameters:
        stream_itr_type next
        stream_itr_type str_end
        ios_base
        facet_type

A templated function that parses a date_generator from the stream.

Parses a first_day_of_the_week_before => "weekday before"

    get_kday_after_type(...)
      Return Type:
        facet_type::kday_after_type
      Parameters:
        stream_itr_type next
        stream_itr_type str_end
        ios_base
        facet_type

A templated function that parses a date_generator from the stream.

Parses a first_day_of_the_week_after => "weekday after".

_____________________________________________________

### Special Values

The date_time library uses five special_values. They are:

not_a_date_time | neg_infin | pos_infin | min_date_time | max_date_time

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.

#### Customization

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.

#### Special Values Formatter/Parser Reference

The complete class references can be found here: `Special Values Formatter Doxygen Reference` and here: `Special Values Parser Doxygen Reference`

#### Special Values Formatter Constructor

Syntax | Description
--- | ---

    special_values_formatter()

Constructor uses defaults for special value strings.

    special_values_formatter(...)
      Parameters:
        collection_type::iterator
        collection_type::iterator

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.

    special_values_formatter(...)
      Parameters:
        char_type*
        char_type*

Constructs special values formatter from an array of strings.

#### Special Values Formatter Accessors

Syntax | Description
--- | ---
Example

    OutItrT put_special(...)
      Parameters:
        OutItrT next
        special_values value

Puts the given special value into the stream.

    date d1(not_a_date_time);
    date d2(minimum_date_time);
    special_values_formatter formatter;
    formatter.put_special(itr, d1);
    // Puts: "not-a-date-time"
    formatter.put_special(itr, d2);
    // Puts: "1400-Jan-01"

#### Special Values Parser Constructor

Syntax | Description
--- | ---

    special_values_parser()

    special_values_parser(...)
      Parameters:
        collection_type::iterator
        collection_type::iterator

Constructs a special values parser using the strings in the collection.

    special_values_parser(...)
      Parameter:
        scpecial_values_parser

Copy constructor.

    special_values_parser(...)
      Parameters:
        string_type nadt_str
        string_type neg_inf_str
        string_type pos_inf_str
        string_type min_dt_str
        string_type max_dt_str

Constructs a special values parser using the supplied strings.

#### Special Values Parser Accessors

Syntax | Description
--- | ---
Example

    void sv_strings(...)
      Parameters:
        string_type nadt_str
        string_type neg_inf_str
        string_type pos_inf_str
        string_type min_dt_str
        string_type max_dt_str

Replace the set of special value strings with the given ones.

    bool match(...)
      Parameters:
        stream_itr_type beg
        stream_itr_type end
        match_results

Returns true if parse was successful. Upon a successful parse, `mr.current_match` will be set an int values corresponding to the equivalent special_value.

    // stream holds "maximum_date_time"
    typedef special_values_parser svp;
    svp parser;
    svp::match_results mr;
    if(parser.match(itr, str_end, mr)) {
      d = date(static_cast<special_values>(
               mr.match_results))
    } else {
      // error, failed parse
    }
    // d == "9999-Dec-31"

_____________________________________________________

### Format Date Parser

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.

#### Format Date Parser Reference

The complete class reference can be found here: `Doxygen Reference`

#### Format Date Parser Constructor

Syntax | Description
--- | ---

    format_date_parser(...)
                    Parameters:
                    string_type format
                    std::locale

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.

    format_date_parser(...)
      Parameters:
        string_type format
        input_collection_type
        input_collection_type
        input_collection_type
        input_collection_type

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).

    format_date_parser(...)
      Parameters:
        format_date_parser

Copy Constructor

#### Format Date Parser Accessors

Syntax | Description
--- | ---
Example

    string_type format()

Returns the format that will be used when parsing dates in those functions where there is no format parameter.

    void format(string_type)

Sets the format that will be used when parsing dates in those functions where there is no format parameter.

    void short_month_names(...)
      Parameter:
        input_collection_type names

Replace the short month names used by the parser. The collection must contain values for each month, starting with January.

    void long_month_names(...)
      Parameter:
        input_collection_type names

Replace the long month names used by the parser. The collection must contain values for each month, starting with January.

    void short_weekday_names(...)
      Parameter:
        input_collection_type names

Replace the short weekday names used by the parser. The collection must contain values for each weekday, starting with Sunday.

    void long_weekday_names(...)
      Parameter:
        input_collection_type names

Replace the long weekday names used by the parser. The collection must contain values for each weekday, starting with Sunday.

    date_type parse_date(...)
      Parameters:
        string_type input
        string_type format
        special_values_parser

Parse a date from the given input using the given format.

    string inp("2005-Apr-15");
    string format("%Y-%b-%d");
    date d;
    d = parser.parse_date(inp,
                          format,
                          svp);
    // d == 2005-Apr-15

    date_type parse_date(...)
      Parameters:
        istreambuf_iterator input
        istreambuf_iterator str_end
        special_values_parser

Parse a date from stream using the parser's format.

    date_type parse_date(...)
      Parameters:
        istreambuf_iterator input
        istreambuf_iterator str_end
        string_type format
        special_values_parser

Parse a date from stream using the given format.

    // stream holds "2005-04-15"
    string format("%Y-%m-%d");
    date d;
    d = parser.parse_date(itr,
                          str_end,
                          format,
                          svp);
    // d == 2005-Apr-15

    month_type parse_month(...)
      Parameters:
        istreambuf_iterator input
        istreambuf_iterator str_end
        string_type format

Parses a month from stream using given format. Throws bad_month if unable to parse.

    // stream holds "March"
    string format("%B");
    greg_month m;
    m = parser.parse_month(itr,
                           str_end,
                           format);
    // m == March

    day_type parse_day_of_month(...)
      Parameters:
        istreambuf_iterator input
        istreambuf_iterator str_end

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.

    // stream holds "01"
    greg_day d;
    d = parser.parse_day_of_month(itr,
                           str_end);
    // d == 1st

    day_type parse_var_day_of_month(...)
      Parameters:
        istreambuf_iterator input
        istreambuf_iterator str_end

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.

    // stream holds "1"
    greg_day d;
    d = parser.parse_var_day_of_month(itr,
                           str_end);
    // d == 1st

    day_of_week_type parse_weekday(...)
      Parameters:
        istreambuf_iterator input
        istreambuf_iterator str_end
        string_type format

Parse a weekday from stream according to the given format. Throws a bad_weekday if unable to parse.

    // stream holds "Tue"
    string format("%a");
    greg_weekday wd;
    wd = parser.parse_weekday(itr,
                              str_end,
                              format);
    // wd == Tuesday

    year_type parse_year(...)
      Parameters:
        istreambuf_iterator input
        istreambuf_iterator str_end
        string_type format

Parse a year from stream according to given format. Throws bad year if unable to parse.

    // stream holds "98"
    string format("%y");
    greg_year y;
    y = parser.parse_year(itr,
                          str_end,
                          format);
    // y == 1998

### Date Time IO Tutorial

Basic Use | Format Strings | Content Strings | Special Values | Date/Time Periods | Date Generators

#### Basic Use

Facets are automatically imbued when operators '>>' and '<<' are called. The list of date_time objects that can be streamed are:

##### Gregorian

`date`, `days`, `date_period`, `greg_month`, `greg_weekday`, `greg_year`, `partial_date`, `nth_day_of_the_week_in_month`, `first_day_of_the_week_in_month`, `last_day_of_the_week_in_month`, `first_day_of_the_week_after`, `first_day_of_the_week_before`

##### Posix_time

`ptime`, `time_period`, `time_duration`

##### Local_time

`local_date_time`

The following example is of the basic use of the new IO code, utilizing all the defaults. (this example can be found in the `libs/date_time/examples/tutorial` directory)

      date d(2004, Feb, 29);
      time_duration td(12,34,56,789);
      stringstream ss;
      ss << d << ' ' << td;
      ptime pt(not_a_date_time);
      cout << pt << endl; // "not-a-date-time"
      ss >> pt;
      cout << pt << endl; // "2004-Feb-29 12:34:56.000789"
      ss.str("");
      ss << pt << " EDT-05EDT,M4.1.0,M10.5.0";
      local_date_time ldt(not_a_date_time);
      ss >> ldt;
      cout << ldt << endl; // "2004-Feb-29 12:34:56.000789 EDT"

This example used the default settings for the input and output facets. The default formats are such that interoperability like that shown in the example is possible. NOTE: Input streaming of local_date_time can only be done with a posix time zone string. The default output format uses a time zone abbreviation. The format can be changed so out and in match (as we will see later in this tutorial).

#### Format Strings

The format strings control the order, type, and style of the date/time elements used. The facets provide some predefined formats (iso_format_specifier, iso_format_extended_specifier, and default_date_format) but the user can easily create their own.

(continued from previous example)

      local_time_facet* output_facet = new local_time_facet();
      local_time_input_facet* input_facet = new local_time_input_facet();
      ss.imbue(locale(locale::classic(), output_facet));
      ss.imbue(locale(ss.getloc(), input_facet));

      output_facet->format("%a %b %d, %H:%M %z");
      ss.str("");
      ss << ldt;
      cout << ss.str() << endl; // "Sun Feb 29, 12:34 EDT"

      output_facet->format(local_time_facet::iso_time_format_specifier);
      ss.str("");
      ss << ldt;
      cout << ss.str() << endl; // "20040229T123456.000789-0500"

      output_facet->format(local_time_facet::iso_time_format_extended_specifier);
      ss.str("");
      ss << ldt;
      cout << ss.str() << endl; // "2004-02-29 12:34:56.000789-05:00"

Format strings are not limited to date/time elements. Extra verbiage can be placed in a format string. NOTE: When extra verbiage is present in an input format, the data being input must also contain the exact verbiage.

(continued from previous example)

      // extra words in format
      string my_format("The extended ordinal time %Y-%jT%H:%M can also be \
      represented as %A %B %d, %Y");
      output_facet->format(my_format.c_str());
      input_facet->format(my_format.c_str());
      ss.str("");
      ss << ldt;
      cout << ss.str() << endl;

      // matching extra words in input
      ss.str("The extended ordinal time 2005-128T12:15 can also be \
      represented as Sunday May 08, 2005");
      ss >> ldt;
      cout << ldt << endl;

#### Content Strings

So far we've shown how a user can achieve a great deal of customization with very little effort by using formats. Further customization can be achieved through user defined elements (ie strings). The elements that can be customized are: Special value names, month names, month abbreviations, weekday names, weekday abbreviations, delimiters of the date/time periods, and the phrase elements of the date_generators.

The default values for these are as follows:

##### Special values

`not-a-date-time`, `-infinity`, `+infinity`, `minimum-date-time`, `maximum-date-time`

##### Months

`English calendar and three letter abbreviations`

##### Weekdays

`English calendar and three letter abbreviations`

##### Date generator phrase elements

`first`, `second`, `third`, `fourth`, `fifth`, `last`, `before`, `after`, `of`

NOTE: We've shown earlier that the components of a date/time representation can be re-ordered via the format string. This is not the case with date_generators. The elements themselves can be customized but their order cannot be changed.

#### Content Strings

To illustrate the customization possibilities we will use custom strings for months and weekdays (we will only use long names, is all lowercase, for this example).

(continued from previous example)

      // set up the collections of custom strings.
      // only the full names are altered for the sake of brevity
      string month_names[12] = { "january", "february", "march",
                                 "april", "may", "june",
                                 "july", "august", "september",
                                 "october", "november", "december" };
      vector<string> long_months(&month_names[0], &month_names[12]);
      string day_names[7] = { "sunday", "monday", "tuesday", "wednesday",
                              "thursday", "friday", "saturday" };
      vector<string> long_days(&day_names[0], &day_names[7]);

      //  create date_facet and date_input_facet using all defaults
      date_facet* date_output = new date_facet();
      date_input_facet* date_input = new date_input_facet();
      ss.imbue(locale(ss.getloc(), date_output));
      ss.imbue(locale(ss.getloc(), date_input));

      // replace names in the output facet
      date_output->long_month_names(long_months);
      date_output->long_weekday_names(long_days);

      // replace names in the input facet
      date_input->long_month_names(long_months);
      date_input->long_weekday_names(long_days);

      // customize month, weekday and date formats
      date_output->format("%Y-%B-%d");
      date_input->format("%Y-%B-%d");
      date_output->month_format("%B"); // full name
      date_input->month_format("%B"); // full name
      date_output->weekday_format("%A"); // full name
      date_input->weekday_format("%A"); // full name

      ss.str("");
      ss << greg_month(3);
      cout << ss.str() << endl; // "march"
      ss.str("");
      ss << greg_weekday(3);
      cout << ss.str() << endl; // "tuesday"
      ss.str("");
      ss << date(2005,Jul,4);
      cout << ss.str() << endl; // "2005-july-04"

#### Special Values

Customizing the input and output of special values is best done by creating a new special_values_parser and special_values_formatter. The new strings can be set at construction time (as in the example below).

(continued from previous example)

      // reset the formats to defaults
      output_facet->format(local_time_facet::default_time_format);
      input_facet->format(local_time_input_facet::default_time_input_format);

      // create custom special_values parser and formatter objects
      // and add them to the facets
      string sv[5] = {"nadt","neg_inf", "pos_inf", "min_dt", "max_dt" };
      vector<string> sv_names(&sv[0], &sv[5]);
      special_values_parser sv_parser(sv_names.begin(), sv_names.end());
      special_values_formatter sv_formatter(sv_names.begin(), sv_names.end());
      output_facet->special_values_formatter(sv_formatter);
      input_facet->special_values_parser(sv_parser);

      ss.str("");
      ldt = local_date_time(not_a_date_time);
      ss << ldt;
      cout << ss.str() << endl; // "nadt"

      ss.str("min_dt");
      ss >> ldt;
      ss.str("");
      ss << ldt;
      cout << ss.str() << endl; // "1400-Jan-01 00:00:00 UTC"

NOTE: even though we sent in strings for min and max to the formatter, they are ignored because those special values construct to actual dates (as shown above).

#### Date/Time Periods

Customizing the input and output of periods is best done by creating a new period_parser and period_formatter. The new strings can be set at construction time (as in the example below).

(continued from previous example)

      // all formats set back to defaults (not shown for brevity)

      // create our date_period
      date_period dp(date(2005,Mar,1), days(31)); // month of march

      // custom period formatter and parser
      period_formatter per_formatter(period_formatter::AS_OPEN_RANGE,
                                     " to ", "from ", " exclusive", " inclusive" );
      period_parser per_parser(period_parser::AS_OPEN_RANGE,
                               " to ", "from ", " exclusive" , "inclusive" );

      // default output
      ss.str("");
      ss << dp;
      cout << ss.str() << endl; // "[2005-Mar-01/2005-Mar-31]"

      // add out custom parser and formatter to  the facets
      date_output->period_formatter(per_formatter);
      date_input->period_parser(per_parser);

      // custom output
      ss.str("");
      ss << dp;
      cout << ss.str() << endl; // "from 2005-Feb-01 to 2005-Apr-01 exclusive"

#### Date Generators

Customizing the input and output of date_generators is done by replacing the existing strings (in the facet) with new strings.

NOTE: We've shown earlier that the components of a date/time representation can be re-ordered via the format string. This is not the case with date_generators. The elements themselves can be customized but their order cannot be changed.

(continued from previous example)

      // custom date_generator phrases
      string dg_phrases[9] = { "1st", "2nd", "3rd", "4th", "5th",
                               "final", "prior to", "following", "in" };
      vector<string> phrases(&dg_phrases[0], &dg_phrases[9]);

      // create our date_generator
      first_day_of_the_week_before d_gen(Monday);

      // default output
      ss.str("");
      ss << d_gen;
      cout << ss.str() << endl; // "Mon before"

      // add our custom strings to the date facets
      date_output->date_gen_phrase_strings(phrases);
      date_input->date_gen_element_strings(phrases);

      // custom output
      ss.str("");
      ss << d_gen;
      cout << ss.str() << endl; // "Mon prior to"

| Copyright © 2001-2005 CrystalClear Software, Inc