bbldc_periodicmaactualactual.h

Go to the documentation of this file.

/// @file bbldc_periodicmaactualactual.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bbldc_periodicmaactualactual.h                                     -*-C++-*-
#ifndef INCLUDED_BBLDC_PERIODICMAACTUALACTUAL
#define INCLUDED_BBLDC_PERIODICMAACTUALACTUAL
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bbldc_periodicmaactualactual bbldc_periodicmaactualactual
/// @brief  Provide stateless functions for period-based ICMA Actual/Actual.
/// @addtogroup bbl
/// @{
/// @addtogroup bbldc
/// @{
/// @addtogroup bbldc_periodicmaactualactual
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bbldc_periodicmaactualactual-purpose"> Purpose</a>
/// * <a href="#bbldc_periodicmaactualactual-classes"> Classes </a>
/// * <a href="#bbldc_periodicmaactualactual-description"> Description </a>
///   * <a href="#bbldc_periodicmaactualactual-usage"> Usage </a>
///     * <a href="#bbldc_periodicmaactualactual-example-1-computing-day-count-and-year-fraction"> Example 1: Computing Day Count and Year Fraction </a>
///
/// # Purpose {#bbldc_periodicmaactualactual-purpose}
/// Provide stateless functions for period-based ICMA Actual/Actual.
///
/// # Classes {#bbldc_periodicmaactualactual-classes}
///
/// -  bbldc::PeriodIcmaActualActual: ICMA Act/Act convention stateless functions
///
/// # Description {#bbldc_periodicmaactualactual-description}
/// This component provides a `struct`,
/// `bbldc::PeriodIcmaActualActual`, that serves as a namespace for defining a
/// suite of date-related functions used to compute the day count and the year
/// fraction between two dates as per the ICMA Actual/Actual day-count
/// convention.  In this day-count convention, the day count between two dates
/// is exactly the number of days occurring in the time period and the year
/// fraction is the number of full periods multiplied by the period weighting
/// (`periodYearDiff`) plus front-stub and back-stub adjustments.  The periods
/// are defined by the `periodDate` elements representing, say, bond coupon
/// payment dates with the first period starting on `periodDate[0]` and ending
/// on `periodDate[1], the second period starting on `periodDate[1]' and ending
/// on `periodDate[2], and the `i'-th period starting on `periodDate[i - 1]` and
/// ending on `periodDate[i]`.
///
/// ## Usage {#bbldc_periodicmaactualactual-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Computing Day Count and Year Fraction {#bbldc_periodicmaactualactual-example-1-computing-day-count-and-year-fraction}
///
///
/// The following snippets of code illustrate how to use
/// `bbldc::PeriodIcmaActualActual` methods.  First, create two `bdlt::Date`
/// variables, `d1` and `d2`:
/// @code
/// const bdlt::Date d1(2003, 10, 19);
/// const bdlt::Date d2(2003, 12, 31);
/// @endcode
/// Then, create a schedule of period dates, `sched`, corresponding to a
/// quarterly payment (`periodYearDiff == 0.25`):
/// @code
/// bsl::vector<bdlt::Date> sched;
/// sched.push_back(bdlt::Date(2003, 10, 1));
/// sched.push_back(bdlt::Date(2004,  1, 1));
/// @endcode
/// Next, compute the day count between `d1` and `d2`:
/// @code
/// const int daysDiff = bbldc::PeriodIcmaActualActual::daysDiff(d1, d2);
/// assert(73 == daysDiff);
/// @endcode
/// Finally, compute the year fraction between the two dates:
/// @code
/// const double yearsDiff = bbldc::PeriodIcmaActualActual::yearsDiff(d1,
///                                                                   d2,
///                                                                   sched,
///                                                                   0.25);
/// // Need fuzzy comparison since 'yearsDiff' is a 'double'.
/// assert(yearsDiff > 0.1983 && yearsDiff < 0.1985);
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bbl
 * @{
 */
/** @addtogroup bbldc
 * @{
 */
/** @addtogroup bbldc_periodicmaactualactual
 * @{
 */
 
#include <bblscm_version.h>
 
#include <bdlt_date.h>
 
#include <bsls_libraryfeatures.h>
 
#include <bsl_vector.h>
 
#include <vector>                   // 'std::vector', 'std::pmr::vector'
 
 
namespace bbldc {
 
                      // =============================
                      // struct PeriodIcmaActualActual
                      // =============================
 
/// This `struct` provides a namespace for a suite of pure functions that
/// compute values based on dates according to the ICMA Actual/Actual
/// day-count convention.
///
/// See @ref bbldc_periodicmaactualactual 
struct PeriodIcmaActualActual {
 
    // CLASS METHODS
 
    /// Return the (signed) number of days between the specified `beginDate`
    /// and `endDate` according to the ICMA Actual/Actual day-count
    /// convention.  If `beginDate <= endDate`, then the result is non-negative.  
    /// 
    /// \note Note that   reversing the order of `beginDate` and
    /// `endDate` negates the result.
    static int daysDiff(const bdlt::Date& beginDate,
                        const bdlt::Date& endDate);
 
    /// Return the (signed fractional) number of years between the specified
    /// `beginDate` and `endDate` according to the ICMA Actual/Actual
    /// day-count convention with periods starting on the specified range
    /// `[ periodDateBegin, periodDateEnd )` values and each period having a
    /// duration of the specified `periodYearDiff` years (e.g., 0.25 for
    /// quarterly periods).  If `beginDate <= endDate`, then the result is non-negative.  
    /// 
    /// \pre The behavior is undefined   unless
    /// `2 <= periodDateEnd - periodDateBegin`, the values contained in the
    /// range are unique and sorted from minimum to maximum,
    /// `*periodDateBegin <= beginDate <= *(periodDateEnd - 1)`, and
    /// `*periodDateBegin <= endDate <= *(periodDateEnd - 1)`.  
    /// 
    /// \note Note that   reversing the order of `beginDate` and `endDate` negates the result;
    /// specifically,
    /// `|yearsDiff(b, e, pd, pyd) + yearsDiff(e, b, pd, pyd)| <= 1.0e-15`
    /// for all dates `b` and `e`, periods `pd`, and year fraction per
    /// period `pyd`.
    static double yearsDiff(const bdlt::Date&  beginDate,
                            const bdlt::Date&  endDate,
                            const bdlt::Date  *periodDateBegin,
                            const bdlt::Date  *periodDateEnd,
                            double             periodYearDiff);
 
    static double yearsDiff(
                           const bdlt::Date&                   beginDate,
                           const bdlt::Date&                   endDate,
                           const bsl::vector<bdlt::Date>&      periodDate,
                           double                              periodYearDiff);
    static double yearsDiff(
                           const bdlt::Date&                   beginDate,
                           const bdlt::Date&                   endDate,
                           const std::vector<bdlt::Date>&      periodDate,
                           double                              periodYearDiff);
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR
    static double yearsDiff(
                           const bdlt::Date&                   beginDate,
                           const bdlt::Date&                   endDate,
                           const std::pmr::vector<bdlt::Date>& periodDate,
                           double                              periodYearDiff);
#endif
        // Return the (signed fractional) number of years between the specified
        // 'beginDate' and 'endDate' according to the ICMA Actual/Actual
        // day-count convention with periods starting on the specified
        // 'periodDate' values and each period having a duration of the
        // specified 'periodYearDiff' years (e.g., 0.25 for quarterly periods).
        // If 'beginDate <= endDate', then the result is non-negative.  The
        // behavior is undefined unless 'periodDate.size() >= 2', the values
        // contained in 'periodDate' are unique and sorted from minimum to
        // maximum, 'periodDate.front() <= beginDate <= periodDate.back()', and
        // 'periodDate.front() <= endDate <= periodDate.back()'.  Note that
        // reversing the order of 'beginDate' and 'endDate' negates the result;
        // specifically,
        // '|yearsDiff(b, e, pd, pyd) + yearsDiff(e, b, pd, pyd)| <= 1.0e-15'
        // for all dates 'b' and 'e', periods 'pd', and year fraction per
        // period 'pyd'.
};
 
// ============================================================================
//                             INLINE DEFINITIONS
// ============================================================================
 
                      // -----------------------------
                      // struct PeriodIcmaActualActual
                      // -----------------------------
 
// CLASS METHODS
inline
int PeriodIcmaActualActual::daysDiff(const bdlt::Date& beginDate,
                                     const bdlt::Date& endDate)
{
    return endDate - beginDate;
}
 
inline
double PeriodIcmaActualActual::yearsDiff(
                                 const bdlt::Date&              beginDate,
                                 const bdlt::Date&              endDate,
                                 const bsl::vector<bdlt::Date>& periodDate,
                                 double                         periodYearDiff)
{
    return yearsDiff(beginDate,
                     endDate,
                     periodDate.data(),
                     periodDate.data() + periodDate.size(),
                     periodYearDiff);
}
 
inline
double PeriodIcmaActualActual::yearsDiff(
                                 const bdlt::Date&              beginDate,
                                 const bdlt::Date&              endDate,
                                 const std::vector<bdlt::Date>& periodDate,
                                 double                         periodYearDiff)
{
    // Some implmentations of 'std::vector', notably Aix and Solaris, do not
    // provide the 'data' accessor.
 
    const bdlt::Date *begin = periodDate.empty() ? 0 : &*periodDate.begin();
    const bdlt::Date *end   = begin + periodDate.size();
 
    return yearsDiff(beginDate,
                     endDate,
                     begin,
                     end,
                     periodYearDiff);
}
 
#ifdef BSLS_LIBRARYFEATURES_HAS_CPP17_PMR
inline
double PeriodIcmaActualActual::yearsDiff(
                            const bdlt::Date&                   beginDate,
                            const bdlt::Date&                   endDate,
                            const std::pmr::vector<bdlt::Date>& periodDate,
                            double                              periodYearDiff)
{
    return yearsDiff(beginDate,
                     endDate,
                     periodDate.data(),
                     periodDate.data() + periodDate.size(),
                     periodYearDiff);
}
#endif
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2015 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */