Component bdlt_calendarutil [Package bdlt]

Provide common date manipulations requiring a calendar. More...

Namespaces
namespace	bdlt

---

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:

Component bdlt_date, Component 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);