Component bblb_schedulegenerationutil [Package bblb]

Provide functions for generating schedules of dates. More...

Namespaces
namespace	bblb

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Generating a Schedule

Purpose:

Provide functions for generating schedules of dates.

Classes:

bblb::ScheduleGenerationUtil

namespace for schedule generation functions

See also:

Description:

This component provides a struct, bblb::ScheduleGenerationUtil, that serves as a namespace for functions that generate a schedule; a set of dates limited to within a closed-interval date-range, represented by the specified earliest and latest dates. Typically, a schedule generation method can be defined by an algorithm specific to the method, an example date, a closed-interval represented by an earliest and a latest date, and any other information required to determine the interval between successive dates in a schedule (for example, the number of days or months between successive dates). The process of computing the dates within a schedule is exemplified using the following diagram:

  ___________|__________________|___________________|________
         'example'          'earliest'          'latest'
             .___.___.___.___.___|___|___|___|___|___.
                                 ^   ^   ^   ^   ^
  'interval':.___.               |   |   |   |   |
  'schedule':                   [d0, d1, d2, d3, d4]

The schedule generated in the above diagram is [d0, d1, d2, d3, d4]. Notice that the example date does not have to reside within the closed interval (the example date is before the earliest date in this diagram).

More formally, the resulting schedule is the subset of the infinite series of dates, defined by all dates separated by an integral multiple of intervals from the example date, that reside within the closed-interval specified by earliest and latest.

The following section provides a synopsis of the main functions provided in this component:

  'generateFromDayInterval'               Generate a schedule having an
                                          interval of a fixed number of days.

  'generateFromDayOfMonth'                Generate a schedule having an
                                          interval of a fixed number of
                                          months, with each date in the
                                          schedule occuring on a specific day
                                          of the month.

  'generateFromBusinessDayOfMonth'        Generate a schedule having an
                                          interval of a fixed number of
                                          months, with each date in the
                                          schedule occuring on a specific
                                          business day of the month.

  'generateFromDayOfWeekAfterDayOfMonth'  Generate a schedule having an
                                          interval of a fixed number of
                                          months, with each date in the
                                          schedule occuring on a specific day
                                          of the week on or after a specific
                                          day of the month.

  'generateFromDayOfWeekInMonth'          Generate a schedule having an
                                          interval of a fixed number of
                                          months, with each date in the
                                          schedule occuring on a specific day
                                          of the week in a specific week of
                                          the month.

Usage:

This section illustrates intended use of this component.

Example 1: Generating a Schedule:

Suppose that we want to determine the sequence of dates that are: * integral multiples of 9 months away from July 2007, * on the 23rd day of the month, * and within the closed interval [02/01/2012, 02/28/2015].

First, we define the inputs and output to the schedule generation function:

  bdlt::Date earliest(2012, 2,  1);
  bdlt::Date   latest(2015, 2, 28);
  bdlt::Date  example(2007, 7, 23);

  bsl::vector<bdlt::Date> schedule;

Now, we invoke the generateFromDayOfMonth routine to obtain the subset of dates:

  bblb::ScheduleGenerationUtil::generateFromDayOfMonth(
                                                  &schedule,
                                                  earliest,
                                                  latest,
                                                  example.year(),
                                                  example.month(),
                                                  9,    // 'intervalInMonths'
                                                  23);  // 'targetDayOfMonth'

Finally, we assert that the generated schedule is what we expect:

  assert(4 == schedule.size());
  assert(bdlt::Date(2012, 10, 23) == schedule[0]);
  assert(bdlt::Date(2013,  7, 23) == schedule[1]);
  assert(bdlt::Date(2014,  4, 23) == schedule[2]);
  assert(bdlt::Date(2015,  1, 23) == schedule[3]);