bblb_schedulegenerationutil

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]);