bdlt_calendarutil

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Manipulating Dates with CalendarUtil

Purpose

Provide common date manipulations requiring a calendar.

Classes

• bdlt::CalendarUtil: common date manipulations requiring a calendar

See also

bdlt_date, bdlt_calendar

Description

This component provides a struct, bdlt::CalendarUtil, that serves as a namespace for date-manipulation functions that require the use of a calendar.

This utility component provides the following (static) methods:

'addBusinessDaysIfValid'   Add an integral number of business days to the
                           specified original date within the valid range
                           of the specified calendar.
 
'nthBusinessDayOfMonthOrMaxIfValid'
                           Determine the 'n'th business day of the
                           specified year and month subject to a maximum of
                           the total number of business days in the
                           specified year and month, based on the provided
                           calendar.
 
'shiftFollowingIfValid'    If original date is not a business day, move
                           the date forward until it is a business day.
 
'shiftPrecedingIfValid'    If original date is not a business day, move
                           the date backwards until it is a business day.
 
'shiftModifiedFollowingIfValid'
                           If original date is not a business day, move
                           the date forward until it is a business day,
                           unless the date goes into the next month, in
                           which case the date is moved to the previous
                           business day.
 
'shiftModifiedPrecedingIfValid'
                           If original date is not a business day, move
                           the date backward until it is a business day,
                           unless the date goes into the previous month, in
                           which case the date is moved to the next
                           business day.
 
'shiftIfValid'             Shift a date based on a provided convention.
                           Note that this function delegates its operation
                           to one of the above shift functions, based on
                           the date-shifting convention specified.
 
'subtractBusinessDaysIfValid'
                           Subtract an integral number of business days
                           from the specified original date within the
                           valid range of the specified calendar.

Usage

This section illustrates intended use of this component.

Example 1: Manipulating Dates with CalendarUtil

Suppose that we want to determine the actual interest payment date in January 2014 from a US bond that pays on the 20th of each month and uses the modified-following date-shifting convention.

We create a calendar, calUS, that has the calendar information populated for the US in 2014. We then use the shiftIfValid function, provided by CalendarUtil, to compute the payment date.

First, we create a date for January 1, 2014 that corresponds to the nominal payment date (which happens to be holiday) and a calendar with valid range from April 20, 2012 through April 20, 2014, typical weekend days, and the holiday:

const bdlt::Date unadjustedDate(2014, 1, 20);
 
const bdlt::Date startDate(2012, 4, 20);
const bdlt::Date endDate(2014, 4, 20);
 
bdlt::Calendar calUS(startDate, endDate);
calUS.addWeekendDay(bdlt::DayOfWeek::e_SAT);
calUS.addWeekendDay(bdlt::DayOfWeek::e_SUN);
calUS.addHoliday(unadjustedDate);

Now, we determine the actual payment date by invoking the shiftIfValid function:

bdlt::Date result;
int        status = CalendarUtil::shiftIfValid(
                                       &result,
                                       unadjustedDate,
                                       calUS,
                                       CalendarUtil::e_MODIFIED_FOLLOWING);

Notice that e_MODIFIED_FOLLOWING is specified as an argument to shiftIfValid to indicate that we want to use the modified-following date-shifting convention.

Finally, we verify that the resulting date is correct:

const bdlt::Date expected(2014, 1, 21);
 
assert(0 == status);
assert(expected == result);