bblb_schedulegenerationutil.h

Go to the documentation of this file.

/// @file bblb_schedulegenerationutil.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bblb_schedulegenerationutil.h                                      -*-C++-*-
#ifndef INCLUDED_BBLB_SCHEDULEGENERATIONUTIL
#define INCLUDED_BBLB_SCHEDULEGENERATIONUTIL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bblb_schedulegenerationutil bblb_schedulegenerationutil
/// @brief  Provide functions for generating schedules of dates.
/// @addtogroup bbl
/// @{
/// @addtogroup bblb
/// @{
/// @addtogroup bblb_schedulegenerationutil
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bblb_schedulegenerationutil-purpose"> Purpose</a>
/// * <a href="#bblb_schedulegenerationutil-classes"> Classes </a>
/// * <a href="#bblb_schedulegenerationutil-description"> Description </a>
///   * <a href="#bblb_schedulegenerationutil-usage"> Usage </a>
///     * <a href="#bblb_schedulegenerationutil-example-1-generating-a-schedule"> Example 1: Generating a Schedule </a>
///
/// # Purpose {#bblb_schedulegenerationutil-purpose}
/// Provide functions for generating schedules of dates.
///
/// # Classes {#bblb_schedulegenerationutil-classes}
///
/// -  bblb::ScheduleGenerationUtil: namespace for schedule generation functions
///
/// @see 
///
/// # Description {#bblb_schedulegenerationutil-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:
/// @code
/// ___________|__________________|___________________|________
///        'example'          'earliest'          'latest'
///            .___.___.___.___.___|___|___|___|___|___.
///                                ^   ^   ^   ^   ^
/// 'interval':.___.               |   |   |   |   |
/// 'schedule':                   [d0, d1, d2, d3, d4]
/// @endcode
/// 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:
/// @code
/// '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.
/// @endcode
///
/// ## Usage {#bblb_schedulegenerationutil-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Generating a Schedule {#bblb_schedulegenerationutil-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:
/// @code
/// bdlt::Date earliest(2012, 2,  1);
/// bdlt::Date   latest(2015, 2, 28);
/// bdlt::Date  example(2007, 7, 23);
///
/// bsl::vector<bdlt::Date> schedule;
/// @endcode
/// Now, we invoke the `generateFromDayOfMonth` routine to obtain the subset of
/// dates:
/// @code
/// bblb::ScheduleGenerationUtil::generateFromDayOfMonth(
///                                                 &schedule,
///                                                 earliest,
///                                                 latest,
///                                                 example.year(),
///                                                 example.month(),
///                                                 9,    // 'intervalInMonths'
///                                                 23);  // 'targetDayOfMonth'
/// @endcode
/// Finally, we assert that the generated schedule is what we expect:
/// @code
/// 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]);
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bbl
 * @{
 */
/** @addtogroup bblb
 * @{
 */
/** @addtogroup bblb_schedulegenerationutil
 * @{
 */
 
#include <bblscm_version.h>
 
#include <bdlt_calendar.h>
#include <bdlt_date.h>
#include <bdlt_dayofweek.h>
 
#include <bsls_libraryfeatures.h>
 
#include <bsl_vector.h>
 
#include <vector>                   // 'std::vector', 'std::pmr::vector'
 
 
namespace bblb {
 
                      // =============================
                      // struct ScheduleGenerationUtil
                      // =============================
 
/// This `struct` provides a namespace for utility functions that generate
/// schedules.
struct ScheduleGenerationUtil {
 
    // CLASS METHODS
    static void generateFromDayInterval(
                                 bsl::vector<bdlt::Date>      *schedule,
                                 const bdlt::Date&             earliest,
                                 const bdlt::Date&             latest,
                                 const bdlt::Date&             example,
                                 int                           intervalInDays);
    static void generateFromDayInterval(
                                 std::vector<bdlt::Date>      *schedule,
                                 const bdlt::Date&             earliest,
                                 const bdlt::Date&             latest,
                                 const bdlt::Date&             example,
                                 int                           intervalInDays);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR
    static void generateFromDayInterval(
                                 std::pmr::vector<bdlt::Date> *schedule,
                                 const bdlt::Date&             earliest,
                                 const bdlt::Date&             latest,
                                 const bdlt::Date&             example,
                                 int                           intervalInDays);
#endif
        // Load, into the specified 'schedule', the chronologically increasing
        // sequence of unique dates that are integral multiples of the
        // specified 'intervalInDays' away from the specified 'example' date,
        // and within the specified closed-interval '[earliest, latest]'.  The
        // behavior is undefined unless 'earliest <= latest' and
        // '1 <= intervalInDays'.
 
    static void generateFromDayOfMonth(
                             bsl::vector<bdlt::Date>      *schedule,
                             const bdlt::Date&             earliest,
                             const bdlt::Date&             latest,
                             int                           exampleYear,
                             int                           exampleMonth,
                             int                           intervalInMonths,
                             int                           targetDayOfMonth,
                             int                           targetDayOfFeb = 0);
    static void generateFromDayOfMonth(
                             std::vector<bdlt::Date>      *schedule,
                             const bdlt::Date&             earliest,
                             const bdlt::Date&             latest,
                             int                           exampleYear,
                             int                           exampleMonth,
                             int                           intervalInMonths,
                             int                           targetDayOfMonth,
                             int                           targetDayOfFeb = 0);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR
    static void generateFromDayOfMonth(
                             std::pmr::vector<bdlt::Date> *schedule,
                             const bdlt::Date&             earliest,
                             const bdlt::Date&             latest,
                             int                           exampleYear,
                             int                           exampleMonth,
                             int                           intervalInMonths,
                             int                           targetDayOfMonth,
                             int                           targetDayOfFeb = 0);
#endif
        // Load, into the specified 'schedule', the chronologically increasing
        // sequence of unique dates that are on the specified
        // 'targetDayOfMonth' (or the last day of the month if
        // 'targetDayOfMonth' would be past the end of the month), integral
        // multiples of the specified 'intervalInMonths' away from the
        // specified 'exampleYear' and 'exampleMonth', and within the specified
        // closed-interval '[earliest, latest]'.  Optionally specify
        // 'targetDayOfFeb' to replace 'targetDayOfMonth' whenever the month of
        // a 'schedule' entry is February.  The behavior is undefined unless
        // 'earliest <= latest', '1 <= exampleYear <= 9999',
        // '1 <= exampleMonth <= 12', '1 <= intervalInMonths',
        // '1 <= targetDayOfMonth <= 31', and '0 <= targetDayOfFeb <= 29'.
 
    static void generateFromBusinessDayOfMonth(
                       bsl::vector<bdlt::Date>      *schedule,
                       const bdlt::Date&             earliest,
                       const bdlt::Date&             latest,
                       int                           exampleYear,
                       int                           exampleMonth,
                       int                           intervalInMonths,
                       const bdlt::Calendar&         calendar,
                       int                           targetBusinessDayOfMonth);
    static void generateFromBusinessDayOfMonth(
                       std::vector<bdlt::Date>      *schedule,
                       const bdlt::Date&             earliest,
                       const bdlt::Date&             latest,
                       int                           exampleYear,
                       int                           exampleMonth,
                       int                           intervalInMonths,
                       const bdlt::Calendar&         calendar,
                       int                           targetBusinessDayOfMonth);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR
    static void generateFromBusinessDayOfMonth(
                       std::pmr::vector<bdlt::Date> *schedule,
                       const bdlt::Date&             earliest,
                       const bdlt::Date&             latest,
                       int                           exampleYear,
                       int                           exampleMonth,
                       int                           intervalInMonths,
                       const bdlt::Calendar&         calendar,
                       int                           targetBusinessDayOfMonth);
#endif
        // Load, into the specified 'schedule', the chronologically increasing
        // sequence of unique dates that are on the specified
        // 'targetBusinessDayOfMonth' (or the highest count possible in the
        // resulting month), integral multiples of the specified
        // 'intervalInMonths' away from the specified 'exampleYear' and
        // 'exampleMonth', and within the specified closed-interval
        // '[earliest, latest]'.  Business days, as per the specified
        // 'calendar', are counted, if 'targetBusinessDayOfMonth' is positive,
        // from and including the chronologically earliest business day to
        // chronologically later business days, and if
        // 'targetBusinessDayOfMonth' is negative, from and including the
        // chronologically latest business day to chronologically earlier
        // business days.  If any of the months required for the schedule do
        // not have a business day, return an empty 'schedule'.  The behavior
        // is undefined unless 'earliest <= latest',
        // '1 <= exampleYear <= 9999', '1 <= exampleMonth <= 12',
        // '1 <= intervalInMonths', and
        // '1 <= abs(targetBusinessDayOfMonth) <= 31'.
 
    static void generateFromDayOfWeekAfterDayOfMonth(
                                bsl::vector<bdlt::Date>      *schedule,
                                const bdlt::Date&             earliest,
                                const bdlt::Date&             latest,
                                int                           exampleYear,
                                int                           exampleMonth,
                                int                           intervalInMonths,
                                bdlt::DayOfWeek::Enum         dayOfWeek,
                                int                           dayOfMonth);
    static void generateFromDayOfWeekAfterDayOfMonth(
                                std::vector<bdlt::Date>      *schedule,
                                const bdlt::Date&             earliest,
                                const bdlt::Date&             latest,
                                int                           exampleYear,
                                int                           exampleMonth,
                                int                           intervalInMonths,
                                bdlt::DayOfWeek::Enum         dayOfWeek,
                                int                           dayOfMonth);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR
    static void generateFromDayOfWeekAfterDayOfMonth(
                                std::pmr::vector<bdlt::Date> *schedule,
                                const bdlt::Date&             earliest,
                                const bdlt::Date&             latest,
                                int                           exampleYear,
                                int                           exampleMonth,
                                int                           intervalInMonths,
                                bdlt::DayOfWeek::Enum         dayOfWeek,
                                int                           dayOfMonth);
#endif
        // Load, into the specified 'schedule', the chronologically increasing
        // sequence of unique dates that are on the specified 'dayOfWeek' on or
        // after the specified 'dayOfMonth', integral multiples of the
        // specified 'intervalInMonths' away from the specified 'exampleYear'
        // and 'exampleMonth', and within the specified closed-interval
        // '[earliest, latest]'.  If any of the months required for the
        // schedule have fewer than 'dayOfMonth' days, return an empty
        // 'schedule'.  The behavior is undefined unless 'earliest <= latest',
        // '1 <= exampleYear <= 9999', '1 <= exampleMonth <= 12',
        // '1 <= intervalInMonths', and '1 <= dayOfMonth <= 31'.
 
    static void generateFromDayOfWeekInMonth(
                                bsl::vector<bdlt::Date>      *schedule,
                                const bdlt::Date&             earliest,
                                const bdlt::Date&             latest,
                                int                           exampleYear,
                                int                           exampleMonth,
                                int                           intervalInMonths,
                                bdlt::DayOfWeek::Enum         dayOfWeek,
                                int                           occurrenceWeek);
    static void generateFromDayOfWeekInMonth(
                                std::vector<bdlt::Date>      *schedule,
                                const bdlt::Date&             earliest,
                                const bdlt::Date&             latest,
                                int                           exampleYear,
                                int                           exampleMonth,
                                int                           intervalInMonths,
                                bdlt::DayOfWeek::Enum         dayOfWeek,
                                int                           occurrenceWeek);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR
    static void generateFromDayOfWeekInMonth(
                                std::pmr::vector<bdlt::Date> *schedule,
                                const bdlt::Date&             earliest,
                                const bdlt::Date&             latest,
                                int                           exampleYear,
                                int                           exampleMonth,
                                int                           intervalInMonths,
                                bdlt::DayOfWeek::Enum         dayOfWeek,
                                int                           occurrenceWeek);
#endif
        // Load, into the specified 'schedule', the chronologically increasing
        // sequence of unique dates that are on the specified 'dayOfWeek' of
        // the specified 'occurrenceWeek' of the month, integral multiples of
        // the specified 'intervalInMonths' away from the specified
        // 'exampleYear' and 'exampleMonth', and within the specified
        // closed-interval '[earliest, latest]'.  The behavior is undefined
        // unless 'earliest <= latest', '1 <= exampleYear <= 9999',
        // '1 <= exampleMonth <= 12', '1 <= intervalInMonths', and
        // '1 <= occurrenceWeek <= 4'.
};
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2016 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */