bdlt_dateutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • "YYYYMMDD" Format
  • End-of-Month Adjustment Conventions
  • Usage
    • Example 1: Schedule Generation

Purpose

Provide common non-primitive operations on date objects.

Classes

• bdlt::DateUtil: namespace for non-primitive operations on date objects

See also

bdlt_date

Description

This component provides a struct, bdlt::DateUtil, that serves as a namespace for utility functions that operate on bdlt::Date objects.

The following list of methods are provided by bdlt::DateUtil:

'isValidYYYYMMDD'             o Validate or convert to and from the
'convertFromYYYYMMDDRaw'        "YYYYMMDD" format
'convertFromYYYYMMDD'           (see {"YYYYMMDD" Format}).
'convertToYYYYMMDD'
 
'nextDayOfWeek'               o Move a date to the next or the previous
'nextDayOfWeekInclusive'        specified day of week.
'previousDayOfWeek'
'previousDayOfWeekInclusive'
 
'earliestDayOfWeekInMonth'    o Find a specified day of the week in a
'nthDayOfWeekInMonth'           specified year and month.
'lastDayOfWeekInMonth'
'lastDayInMonth'
 
'addMonthsEom'                o Add a specified number of months to a date
'addMonthsNoEom'                using either the end-of-month or the
'addMonths'                     non-end-of-month convention (see
                                {End-of-Month Adjustment Conventions}).
 
'addYearsEom'                 o Add a specified number of years to a date
'addYearsNoEom'                 using either the end-of-month or the
'addYears'                      non-end-of-month convention (see
                                {End-of-Month Adjustment Conventions}).

"YYYYMMDD" Format

The "YYYYMMDD" format is a common integral representation of a date that is human readable and maintains appropriate ordering when sorted using integer comparisons. The notation uses eight digits (from left to right): four digits for the year, two digits for the month, and two digits for the day of the month. For example, February 1, 2014, is represented by the number 20140201.

Note that the year is not restricted to values on or after 1000, so, for example, 10102 (or 00010102) represents the date January 2, 0001.

End-of-Month Adjustment Conventions

Two adjustment conventions are used to determine the behavior of the functions (addMonths and addYears) that adjust a date by a particular number of months or years: the end-of-month convention and the non-end-of-month convention. The difference between the two conventions is that the end-of-month convention adjusts the resulting date to the end of the month if the original date is the last day of the month, while the non-end-of-month convention does not perform this adjustment.

For example, if we add 3 months to February 28, 2013 using the non-end-of-month convention, then the resulting date will be May 28, 2013. If we do the same operation except using the end-of-month convention, then the resulting date will be May 31, 2013.

More formal definitions of the two conventions are provided below:

The End-of-Month Convention: If the original date to be adjusted is the last day of a month, or if the day of the month of the original date does not exist in the resulting date, then adjust the resulting date to be the last day of the month.

The Non-End-of-Month Convention: If the day of the month of the original date does not exist in the resulting date, then adjust the resulting date to be the last day of the month.

Usage

This section illustrates intended use of this component.

Example 1: Schedule Generation

Suppose that given a starting date in the "YYYYMMDD" format, we want to generate a schedule for an event that occurs on the same day of the month for 12 months.

First, we use the bdlt::DateUtil::convertFromYYYYMMDD function to convert the integer into a bdlt::Date:

const int startingDateYYYYMMDD = 20130430;
 
bdlt::Date date;
int rc = bdlt::DateUtil::convertFromYYYYMMDD(&date, startingDateYYYYMMDD);
assert(0 == rc);

Now, we use the addMonthsEom function to generate the schedule. Note that addMonthsEom adjusts the resulting date to be the last day of the month if the original date is the last day of the month, while addMonthsNoEom does not make this adjustment.

bsl::vector<bdlt::Date> schedule;
schedule.push_back(date);
 
for (int i = 1; i < 12; ++i) {
    schedule.push_back(bdlt::DateUtil::addMonthsEom(date, i));
}

Finally, we print the generated schedule to the console and observe the output:

bsl::copy(schedule.begin(),
          schedule.end(),
          bsl::ostream_iterator<bdlt::Date>(bsl::cout, "\n"));
 
// Expected output on the console:
//
//   30APR2013
//   31MAY2013
//   30JUN2013
//   31JUL2013
//   31AUG2013
//   30SEP2013
//   31OCT2013
//   30NOV2013
//   31DEC2013
//   31JAN2014
//   28FEB2014
//   31MAR2014

Notice that the dates have been adjusted to the end of the month. If we had used addMonthsNoEom instead of addMonthsEom, this adjustment would not have occurred.