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.
///
/// See @ref bblb_schedulegenerationutil 
struct ScheduleGenerationUtil {
 
    // CLASS METHODS
 
    /// 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]`.  
    /// 
    /// \pre The behavior is undefined   unless `earliest <= latest` and
    /// `1 <= intervalInDays`.
    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 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.  
    /// 
    /// \pre The behavior is undefined   unless
    /// `earliest <= latest`, `1 <= exampleYear <= 9999`,
    /// `1 <= exampleMonth <= 12`, `1 <= intervalInMonths`,
    /// `1 <= targetDayOfMonth <= 31`, and `0 <= targetDayOfFeb <= 29`.
    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
    /// `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`.  
    /// 
    /// \pre The behavior is undefined   unless `earliest <= latest`,
    /// `1 <= exampleYear <= 9999`, `1 <= exampleMonth <= 12`,
    /// `1 <= intervalInMonths`, and
    /// `1 <= abs(targetBusinessDayOfMonth) <= 31`.
    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 `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`.  
    /// 
    /// \pre The behavior is undefined   unless `earliest <= latest`,
    /// `1 <= exampleYear <= 9999`, `1 <= exampleMonth <= 12`,
    /// `1 <= intervalInMonths`, and `1 <= dayOfMonth <= 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` 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]`.  
    /// 
    /// \pre The behavior is undefined   unless `earliest <= latest`, `1 <= exampleYear <= 9999`,
    /// `1 <= exampleMonth <= 12`, `1 <= intervalInMonths`, and
    /// `1 <= occurrenceWeek <= 4`.
    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
};
 
}  // 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */