Component bdlt_timetable [Package bdlt]

Provide a repository for accessing timetable information. More...

Namespaces
namespace	bdlt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Exception-Safety Guarantees
  • Usage
    • Example 1: Exchange Schedule

Purpose:

Provide a repository for accessing timetable information.

Classes:

bdlt::Timetable	repository for accessing timetable information
bdlt::TimetableTransition	datetime and transition code value

Description:

This component provides a value-semantic class, bdlt::Timetable, that represents a timetable of state transitions over a valid range of dates, an associated iterator, bdlt::Timetable::const_iterator, that provides non-modifiable access to the timetable's state transitions, and a class, bdlt::TimetableTransition, that represents a change of state at a datetime.

bdlt::Timetable is designed to be especially efficient at determining the state in effect at a given bdlt::Datetime value (within the valid range for a particular bdlt::Timetable object), and iterating through the state transitions.

bdlt::TimetableTransition consists of a bdlt::Datetime and a (single) non-negative integral code (of type int) that defines the "state" that becomes effective at that datetime. The meaning of the integral code ascribed to each transition is defined by the client. There can be at most one bdlt::TimetableTransition defined for any datetime value within the range of a bdlt::Timetable. Consequently, there is at most one (client-defined) state in effect at any datetime in a timetable.

Default-constructed timetables are empty, and have an empty valid range. Timetables can also be constructed with an initial (non-empty) valid range. The setValidRange method modifies the valid range of a timetable, and a suite of "add" methods can be used to populate a timetable with state transitions.

Timetables are value-semantic objects, and, as such, necessarily support all of the standard value-semantic operations, such as default construction, copy construction and copy assignment, and equality comparison.

Exception-Safety Guarantees:

All methods of bdlt::Timetable are exception-safe, but in general provide only the basic guarantee (i.e., no guarantee of rollback): If an exception occurs (i.e., while attempting to allocate memory), the timetable object is left in a coherent state, but (unless otherwise specified) its value is undefined.

All methods of bdlt::TimetableTransition are exception-safe.

Usage:

This section illustrates intended use of this component.

Example 1: Exchange Schedule:

Suppose we want to track the open and close times for an exchange. Most Mondays (and Tuesdays, Wednesdays, etc.) will have the same schedule, although some may differ. We can use bdlt::Timetable to efficiently store this data.

First, we create an instance of bdlt::Timetable with the desired valid range:

  bdlt::Timetable timetable(bdlt::Date(2018, 1, 1),
                            bdlt::Date(2018, 12, 31));

Then, we define the codes for start-of-trading and end-of-trading and populate the typical transitions into the timetable:

  const int k_TRADING    = 0;
  const int k_NO_TRADING = 1;

  timetable.setInitialTransitionCode(k_NO_TRADING);

  for (int i = 0; i < 5; ++ i) {
      timetable.addTransitions(static_cast<bdlt::DayOfWeek::Enum>(
                                                 bdlt::DayOfWeek::e_MON + i),
                               bdlt::Time(8, 30),
                               k_TRADING,
                               timetable.firstDate(),
                               timetable.lastDate());

      timetable.addTransitions(static_cast<bdlt::DayOfWeek::Enum>(
                                                 bdlt::DayOfWeek::e_MON + i),
                               bdlt::Time(16, 30),
                               k_NO_TRADING,
                               timetable.firstDate(),
                               timetable.lastDate());
  }

Next, we add a holiday on January 19, 2018:

  timetable.removeTransitions(bdlt::Date(2018, 1, 19));

Then, we add a half-day on November 23, 2018:

  timetable.addTransition(bdlt::Datetime(2018, 11, 23, 12, 30),
                          k_NO_TRADING);

  timetable.removeTransition(bdlt::Datetime(2018, 11, 23, 16, 30));

Finally, we verify the transition code in effect at a few datetimes.

  assert(k_NO_TRADING == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018,  1, 15,  8,  0)));

  assert(k_TRADING    == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018,  1, 15,  8, 30)));

  assert(k_TRADING    == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018,  1, 15, 16,  0)));

  assert(k_NO_TRADING == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018,  1, 15, 16, 30)));

  assert(k_NO_TRADING == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018, 11, 23,  8,  0)));

  assert(k_TRADING    == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018, 11, 23,  8, 30)));

  assert(k_TRADING    == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018, 11, 23, 12,  0)));

  assert(k_NO_TRADING == timetable.transitionCodeInEffect(
                                      bdlt::Datetime(2018, 11, 23, 12, 30)));