bdlt Package

Provide date and time vocabulary types, and related utilities. More...

Components
	Component bdlt_calendar
	Provide fast repository for accessing weekend/holiday information.
	Component bdlt_calendarcache
	Provide an efficient cache for read-only `bdlt::Calendar` objects.
	Component bdlt_calendarloader
	Provide a protocol (or pure interface) for loading calendars.
	Component bdlt_calendarreverseiteratoradapter
	Provide reverse iterator adapter for calendar iterators.
	Component bdlt_calendarutil
	Provide common date manipulations requiring a calendar.
	Component bdlt_currenttime
	Provide utilities to retrieve the current time.
	Component bdlt_date
	Provide a value-semantic type to represent dates.
	Component bdlt_datetime
	Provide a value-semantic type representing both date and time.
	Component bdlt_datetimeimputil
	Provide constants useful for encoding datetimes.
	Component bdlt_datetimeinterval
	Provide a representation of an interval of time.
	Component bdlt_datetimeintervalutil
	Provide non-primitive operations on `bdlt::DatetimeInterval`.
	Component bdlt_datetimetz
	Provide a representation of a date and time with time zone offset.
	Component bdlt_datetimeutil
	Provide common non-primitive operations on `bdlt::Datetime`.
	Component bdlt_datetz
	Provide a representation of a date with time zone offset.
	Component bdlt_dateutil
	Provide common non-primitive operations on date objects.
	Component bdlt_dayofweek
	Provide an enumeration of the set of days of the week.
	Component bdlt_dayofweekset
	Provide an ordered set of (unique) `bdlt::DayOfWeek::Enum` values.
	Component bdlt_dayofweekutil
	Provide common non-primitive operations on `bdlt::DayOfWeek::Enum`.
	Component bdlt_defaultcalendarcache
	Provide a process-wide default `bdlt::CalendarCache` object.
	Component bdlt_defaulttimetablecache
	Provide a process-wide default `bdlt::TimetableCache` object.
	Component bdlt_epochutil
	Conversion between absolute/relative time with respect to epoch.
	Component bdlt_fixutil
	Provide conversions between date/time objects and FIX strings.
	Component bdlt_fixutilconfiguration
	Provide an attribute class to configure FIX string generation.
	Component bdlt_fuzzutil
	Provide creation of `bdlt` data types from fuzz data.
	Component bdlt_intervalconversionutil
	Provide functions to convert between time-interval representations.
	Component bdlt_iso8601util
	Provide conversions between date/time objects and ISO 8601 strings.
	Component bdlt_iso8601utilconfiguration
	Provide an attribute class to configure ISO 8601 string generation.
	Component bdlt_localtimeoffset
	Provide utilities to retrieve the local time offset.
	Component bdlt_monthofyear
	Enumerate the set of month-of-year values.
	Component bdlt_packedcalendar
	Provide a compact repository for weekend/holiday information.
	Component bdlt_posixdateimputil
	Provide low-level support functions for date-value manipulation.
	Component bdlt_prolepticdateimputil
	Provide low-level support functions for date-value manipulation.
	Component bdlt_serialdateimputil
	Provide low-level support functions for date-value manipulation.
	Component bdlt_time
	Provide a value-semantic type representing time-of-day.
	Component bdlt_timetable
	Provide a repository for accessing timetable information.
	Component bdlt_timetablecache
	Provide an efficient cache for read-only `bdlt::Timetable` objects.
	Component bdlt_timetableloader
	Provide a protocol (or pure interface) for loading timetables.
	Component bdlt_timetz
	Provide a representation of a time with time zone offset.
	Component bdlt_timeunitratio
	Provide constants characterizing ratios between common time units.
	Component bdlt_timeutil
	Provide common non-primitive operations on `bdlt::Time`.

Detailed Description

Outline

Purpose
MNEMONIC: Basic Development Library Time (bdlt)
Description

Purpose:: Provide date and time vocabulary types, and related utilities.

MNEMONIC: Basic Development Library Time (bdlt):

Description:: The bdlt ("Basic Development Library Time") package provides vocabulary types for representing date, time, and datetime values, and utilities providing non-primitive functionality on the value types.

Additional utilities provide:

Current date, time, and local-time offset values.
Conversion between different date and time representations.
Arithmetic and validation functions

: See Value Types and Utilities below for overviews of the types and functions provided by this package.

Hierarchical Synopsis:

The bdlt package currently has 40 components having 9 levels of physical dependency. The list below shows the hierarchical ordering of the components. The order of components within each level is not architecturally significant, just alphabetical.

  9. bdlt_defaultcalendarcache
     bdlt_defaulttimetablecache

  8. bdlt_calendarcache
     bdlt_timetablecache

  7. bdlt_currenttime
     bdlt_fixutil
     bdlt_iso8601util

  6. bdlt_calendarutil
     bdlt_datetimetz
     bdlt_localtimeoffset
     bdlt_timetableloader

  5. bdlt_calendar
     bdlt_calendarloader
     bdlt_datetimeutil
     bdlt_datetz
     bdlt_epochutil
     bdlt_timetable

  4. bdlt_datetime
     bdlt_dateutil
     bdlt_fuzzutil
     bdlt_packedcalendar
     bdlt_timetz
     bdlt_timeutil

  3. bdlt_date
     bdlt_datetimeintervalutil
     bdlt_intervalconversionutil
     bdlt_time

  2. bdlt_datetimeimputil
     bdlt_datetimeinterval
     bdlt_dayofweekset
     bdlt_dayofweekutil
     bdlt_serialdateimputil

  1. bdlt_calendarreverseiteratoradapter
     bdlt_dayofweek
     bdlt_fixutilconfiguration
     bdlt_iso8601utilconfiguration
     bdlt_monthofyear
     bdlt_posixdateimputil
     bdlt_prolepticdateimputil
     bdlt_timeunitratio

Component Synopsis:

: bdlt_calendar:
Provide fast repository for accessing weekend/holiday information.

: bdlt_calendarcache:
Provide an efficient cache for read-only bdlt::Calendar objects.

: bdlt_calendarloader:
Provide a protocol (or pure interface) for loading calendars.

: bdlt_calendarreverseiteratoradapter:
Provide reverse iterator adapter for calendar iterators.

: bdlt_calendarutil:
Provide common date manipulations requiring a calendar.

: bdlt_currenttime:
Provide utilities to retrieve the current time.

: bdlt_date:
Provide a value-semantic type to represent dates.

: bdlt_datetime:
Provide a value-semantic type representing both date and time.

: bdlt_datetimeimputil:
Provide constants useful for encoding datetimes.

: bdlt_datetimeinterval:
Provide a representation of an interval of time.

: bdlt_datetimeintervalutil:
Provide non-primitive operations on bdlt::DatetimeInterval.

: bdlt_datetimetz:
Provide a representation of a date and time with time zone offset.

: bdlt_datetimeutil:
Provide common non-primitive operations on bdlt::Datetime.

: bdlt_datetz:
Provide a representation of a date with time zone offset.

: bdlt_dateutil:
Provide common non-primitive operations on date objects.

: bdlt_dayofweek:
Provide an enumeration of the set of days of the week.

: bdlt_dayofweekset:
Provide an ordered set of (unique) bdlt::DayOfWeek::Enum values.

: bdlt_dayofweekutil:
Provide common non-primitive operations on bdlt::DayOfWeek::Enum.

: bdlt_defaultcalendarcache:
Provide a process-wide default bdlt::CalendarCache object.

: bdlt_defaulttimetablecache:
Provide a process-wide default bdlt::TimetableCache object.

: bdlt_epochutil:
Conversion between absolute/relative time with respect to epoch.

: bdlt_fixutil:
Provide conversions between date/time objects and FIX strings.

: bdlt_fixutilconfiguration:
Provide an attribute class to configure FIX string generation.

: bdlt_fuzzutil:
Provide creation of bdlt data types from fuzz data.

: bdlt_intervalconversionutil:
Provide functions to convert between time-interval representations.

: bdlt_iso8601util:
Provide conversions between date/time objects and ISO 8601 strings.

: bdlt_iso8601utilconfiguration:
Provide an attribute class to configure ISO 8601 string generation.

: bdlt_localtimeoffset:
Provide utilities to retrieve the local time offset.

: bdlt_monthofyear:
Enumerate the set of month-of-year values.

: bdlt_packedcalendar:
Provide a compact repository for weekend/holiday information.

: bdlt_posixdateimputil:
Provide low-level support functions for date-value manipulation.

: bdlt_prolepticdateimputil:
Provide low-level support functions for date-value manipulation.

: bdlt_serialdateimputil:
Provide low-level support functions for date-value manipulation.

: bdlt_time:
Provide a value-semantic type representing time-of-day.

: bdlt_timetable:
Provide a repository for accessing timetable information.

: bdlt_timetablecache:
Provide an efficient cache for read-only bdlt::Timetable objects.

: bdlt_timetableloader:
Provide a protocol (or pure interface) for loading timetables.

: bdlt_timetz:
Provide a representation of a time with time zone offset.

: bdlt_timeunitratio:
Provide constants characterizing ratios between common time units.

: bdlt_timeutil:
Provide common non-primitive operations on bdlt::Time.

Value Types:: This package defines value-semantic types that represent dates, times (of day), and combined date and time values. For each of these "time" types, there is a related type that also holds a time offset value from UTC. There are also enumerated types representing the months of the year and the days of the week.

Value Types: Date, Time and Datetime:

The bdlt package defines bdlt::Date to represent date values, bdlt::Time to represent time values (to microsecond resolution) within a day, and the combined bdlt::Datetime to represent all points in time (to microsecond resolution) across the range of date values. The ranges of each type are shown below.

  Type     Range
  -------  ------------------------------------------------------------
  Date     [0001/01/01                 ..  9999/12/31                 ]
  Time     [           00:00:00.000000 ..             23:59:59.999999 ]
  Datetime [0001/01/01_00:00:00.000000 ..  9999/12/31_23:59:59.999999 ]

Further note that:

The date values follow the Unix (POSIX) calendar (see bdlt_date.
The definition of bdlt::Datetime does not allow for leap seconds.

The above classes define values representing points on a timeline (e.g., dates on a calendar, positions on a clock) whereas the bdlt::DatetimeInterval class represents the difference (to microsecond resolution) between those points.

  Type             Difference Type
  -------          ----------------
  Date             int (days)
  Time             DatetimeInterval
  Datetime         DatetimeInterval
  DatetimeInterval DatetimeInterval

Each of these classes are designed to hold date and time values, but do not themselves provide means for obtaining values such as current time and date. Those values are available via separate utility components. See Obtaining Current Date, Time, and Local-Time Offset Values.

Singular Time and Datetime Values:: The bdlt::Time class defines a singular value, "24:00:00.000000", which is also the default-constructed value. This singular value is distinguished in two ways:

Relational comparisons to other time values are disallowed -- the behavior is undefined. Note that comparisons of equality and inequality to other values are legal.
- Note that the singular value cannot appear as a key value in any of the standard ordered containers (which require weak ordering of keys).
The singular value is implicitly converted to "00:00:00.000000" (midnight) in arithmetic operations using bdlt::Time values.

: Similarly, the bdlt::Datetime class defines one singular value, "0001/01/01_24:00:00.000000", which happens to be the default constructed value. The restrictions and semantics of this value parallel those of the singular bdlt::Time value.

: Some applications use the singular values of these types as placeholders when a value must be provided but is not known. (See bdetu_unset.)

Timezone Augmented Value Types: DateTz, TimeTz and DatetimeTz:: For each of the basic date and time types there is a corresponding value-semantic type that is augmented with a value representing an offset (in minutes) from UTC. Note that other BDE types represent local time offset as seconds (e.g., the seconds attribute of bsls::TimeInterval).

The local time offset augmented types are:

  Basis Type    Augmented Type
  ----------    ----------------
  bldt:Date     bdlt::DateTz
  bldt:Time     bdlt::TimeTz
  bldt:Datetime bdlt::DatetimeTz

These types are not normalized to a common time zone when they are compared, hence, equality between objects of any of these types requires that the object have both the same local time and the same local-time offset values. To determine equivalence between such objects, each of these classes provides a utc* accessor method.

: These types themselves do not validate that the combinations of dates, times, and local-time offset values they hold correspond to a valid time in any officially recognized time zone. See Obtaining Current Date, Time, and Local-Time Offset Values.

Enumerated Values:: The bdlt package provides enumerations in bdlt_monthofyear and bdlt_dayofweek. The bdlt_dayofweekset provides an efficient, ordered container of unique btdl::DayofWeek::Enum values (i.e., containing no more than seven elements).

Utilities:: This package provides utility components that:

Provide current date, time, and local-time offset values.
Provide date arithmetic functions.
Provide a wide variety of conversion methods: between the value types defined in this package, between the package value types and standard types for date and time, between time values in different standard units (e.g., hours, minutes, nanoseconds).

Obtaining Current Date, Time, and Local-Time Offset Values:: The bdlt_currenttime component provides:

A bdlt::Datetime value for the current UTC time.
A bdlt::Datetime value for the current local time.
A bsls::TimeInterval from the start of the epoch.

: The bdlt_localtimeoffset component defines a function that returns the offset of the host machines designated time zone (as set by the system administrator) from UTC, including adjustments between standard and daylight-saving time, as of a given UTC time and date. For local-time offset for arbitrary time zones see the baetzo package.

: Both bdlt::CurrentTime and bdlt::LocalTimeOffset obtain their values via user-installed callback functions. The default callbacks obtain their values from platform appropriate system calls. User-defined callbacks can provide high-performance (e.g., cached) alternatives to the default system calls, can be instrumented to gather statistics, and can simulate the passage of time for test scenarios.

Advanced Date Arithmetic: bdlt::DateUtil:: The bdet_dateutil component provides functions on bdlt::Date values that extend those provided by the bdlt::Date class itself. For example:

Calculate the bdlt::Date that is a specified number of months -- or years -- before or after a given date. Two different end-of-month conventions are provided.
Find the next -- or previous -- occurrence of a given day of week relative to a specified date (inclusive or exclusive of that specified date).
Find the date of a specified day of week that is the nth (e.g., 1st, 3rd) or last occurrence in a specified year and month.

: This utility also provides a function for conversion of bdlt::Date values to and from int values in the "YYYYMMDD" format.

Conversion of Date, Time and Datetime Values:

Several utility components of bdlt provide functions for the conversion of date and time types to other types, some defined in the C++ Standard, others defined elsewhere in BDE. In particular, the bdlt_epochutil component provides functions that convert bdlt::Datetime values (in UTC) -- understood to represent an absolute date and time in UTC -- to equivalent difference values measured from the start of the Unix standard epoch (1970/01/01_00:00:00.000000 UTC).

  Component          Conversions
  -----------------  --------------------------------------------------------
  bdlt_dateutil      bdlt::Date     <=> 'int' in "YYYYMMDD" format

  bdlt_datetimeutil  bdlt::Datetime <=> bsl::tm

  bdlt_epochutil     bdlt::Datetime <=> bsl::time_t            from the epoch
                     bdlt::Datetime <=> bdlt::TimeT64          from the epoch
                     bdlt::Datetime <=> bsls::TimeInterval     from the epoch
                     bdlt::Datetime <=> bdlt::DateTimeInterval from the epoch

  bdlt_intervalconversionutil
                     bdlt::DatetimeInterval
                                    <=> bsls::TimeInterval
  bdlt_serialdateimputil
                     bdlt::Date     <=> 'int' in the range '[1 .. 3652059]'
                                        (corresponding to
                                        '[00001/01/01 .. 9999/12/31]')

Conversion of Conventional Time Units:: The bdlt_timeunitratio component provides a set of constants that express the ratios between standard time units such as days, hours, ..., nanoseconds. One example is bdlt::TimeUnitRatio::k_MILLISECONDS_PER_MINUTE.

Usage:: This section illustrates intended use of these components.

Example 1: Celebrating Milestone Dates:: Date and time calculations are simple in principle but tedious and error- prone in practice. Consequently, people tend to schedule events on dates that are easy to calculate -- e.g., first of the month, anniversary dates -- even though we know that not all months and years express intervals of the same length. Access to a rich set of types and utilities for date and time calculations affords us other options.

: Suppose we wish to commemorate the 20,000th day since our birth.

First, create a bdlt::Datetime object to represent our date of birth. Let us assume that we were born at the exact start of the Unix epoch:

    bdlt::Datetime dtBirthday = bdlt::EpochUtil::epoch();
    assert(bdlt::Datetime(1970, 1, 1, 0, 0, 0, 0) == dtBirthday);

Next, we calculate the milestone date (and time).

    bdlt::Datetime dt20k(dtBirthday);  dt20k.addDays(20000);
    assert(bdlt::DatetimeInterval(20000) == dt20k - dtBirthday);

    bsl::cout << dt20k << bsl::endl;

and find:

  04OCT2024_00:00:00.000000

The above value represents UTC date and time values. We, however, plan to celebrate the milestone in New York City. Thus, we must obtain the local time offset in NYC for that future date and use it to calculate the milestone (date) in that time zone.

    bsls::TimeInterval     localTimeOffset =
                                 bdlt::LocalTimeOffset::localTimeOffset(dt20k);

    bdlt::DatetimeInterval dtOffset =
      bdlt::IntervalConversionUtil::convertToDatetimeInterval(localTimeOffset);

    bdlt::DatetimeTz       dtz20kLocal(
                                    dt20k + dtOffset,
                                    static_cast<int>(dtOffset.totalMinutes()));

    bsl::cout << dtz20kLocal << bsl::endl;

which is one calendar day earlier:

  03OCT2024_20:00:00.000000-0400

Notice that the local time offset was expressed in units of minutes for the constructor of bdlt::DatetimeTz, but the class print method shows that value as the concatenated decimal values four hours and minutes.

: Next, since we prefer to hold celebrations on weekend days, not weekdays, we determine the day of the week on which the milestone date falls.

To aid our calculation, we define a bdlt::DayOfWeekSet object set of the weekend days in New York City.

    bdlt::DayOfWeekSet weekendDays;
    weekendDays.add(bdlt::DayOfWeek::e_SATURDAY);
    weekendDays.add(bdlt::DayOfWeek::e_SUNDAY);

Now, we determine if the target date is a weekend day. If so, we can plan our celebration for that date; otherwise, we will plan for the next weekend date.

    bdlt::Date milestone = dtz20kLocal.localDatetime().date();
    bdlt::Date holdDate  = weekendDays.isMember(milestone.dayOfWeek())
                         ? milestone
                         : bdlt::DateUtil::nextDayOfWeek(
                                                   bdlt::DayOfWeek::e_SATURDAY,
                                                   milestone);

Finally, we examine our results:

    bsl::cout << "Milestone:"          << " "
              << milestone.dayOfWeek() << " "
              << milestone             << bsl::endl;

    bsl::cout << "Hold date:"          << " "
              << holdDate.dayOfWeek()  << " "
              << holdDate              << bsl::endl;

we find:

  Milestone: THU 03OCT2024
  Hold date: SAT 05OCT2024

and we send out hold-the-date requests to our friends and family.

Package bdlt [Package Group bdl]

Components

Detailed Description

Package bdlt
[Package Group bdl]