bdlt.h

Go to the documentation of this file.

/// @file bdlt.h
///
///
/// @defgroup bdlt Package bdlt
/// @brief  Basic Development Library Time (bdlt)
/// @addtogroup bdl
/// @{
/// @addtogroup bdlt
/// @{
/// * <a href="#bdlt-purpose"> Purpose</a>
/// * <a href="#bdlt-mnemonic"> Mnemonic </a>
/// * <a href="#bdlt-description"> Description </a>
///   * <a href="#bdlt-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bdlt-component-synopsis"> Component Synopsis </a>
///   * <a href="#bdlt-value-types"> Value Types </a>
///     * <a href="#bdlt-value-types-date-time-and-datetime"> Value Types: Date, Time and Datetime </a>
///       * <a href="#bdlt-singular-time-and-datetime-values"> Singular Time and Datetime Values </a>
///     * <a href="#bdlt-timezone-augmented-value-types-datetz-timetz-and-datetimetz"> Timezone Augmented Value Types: DateTz, TimeTz and DatetimeTz </a>
///     * <a href="#bdlt-enumerated-values"> Enumerated Values </a>
///   * <a href="#bdlt-utilities"> Utilities </a>
///     * <a href="#bdlt-obtaining-current-date-time-and-local-time-offset-values"> Obtaining Current Date, Time, and Local-Time Offset Values </a>
///     * <a href="#bdlt-advanced-date-arithmetic-bdlt-dateutil"> Advanced Date Arithmetic: bdlt::DateUtil </a>
///     * <a href="#bdlt-conversion-of-date-time-and-datetime-values"> Conversion of Date, Time and Datetime Values </a>
///     * <a href="#bdlt-conversion-of-conventional-time-units"> Conversion of Conventional Time Units </a>
///   * <a href="#bdlt-usage"> Usage </a>
///     * <a href="#bdlt-example-1-celebrating-milestone-dates"> Example 1: Celebrating Milestone Dates </a>
///
/// # Purpose {#bdlt-purpose}
/// Provide date and time vocabulary types, and related utilities.
///
/// # Mnemonic {#bdlt-mnemonic}
/// Basic Development Library Time (bdlt)
///
/// # Description {#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 {#bdlt-hierarchical-synopsis}
///
/// The 'bdlt' package currently has 53 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.
/// @code
///  9. bdlt_defaultcalendarcache
///     bdlt_defaulttimetablecache
///
///  8. bdlt_calendarcache
///     bdlt_timetablecache
///
///  7. bdlt_currenttime
///     bdlt_datetimetzformatter
///     bdlt_fixutil
///     bdlt_fuzzutil
///     bdlt_iso8601util
///
///  6. bdlt_calendarutil
///     bdlt_datetimetz
///     bdlt_datetzformatter
///     bdlt_localtimeoffset
///     bdlt_timetableloader
///
///  5. bdlt_calendar
///     bdlt_calendarloader
///     bdlt_datetimeformatter
///     bdlt_datetimeutil
///     bdlt_datetz
///     bdlt_epochutil
///     bdlt_timetable
///     bdlt_timetzformatter
///
///  4. bdlt_dateformatter
///     bdlt_datetime
///     bdlt_dateutil
///     bdlt_packedcalendar
///     bdlt_timeformatter
///     bdlt_timetz
///     bdlt_timeutil
///
///  3. bdlt_date
///     bdlt_datetimeintervalutil
///     bdlt_intervalconversionutil
///     bdlt_time
///
///  2. bdlt_datetimeimputil
///     bdlt_datetimeinterval
///     bdlt_dayofweekset
///     bdlt_dayofweekutil
///     bdlt_formatter
///     bdlt_serialdateimputil
///     bdlt_timezoneformatter
///
///  1. bdlt_calendarreverseiteratoradapter
///     bdlt_dayofweek
///     bdlt_fixutilconfiguration
///     bdlt_formatdoc
///     bdlt_formattestutil
///     bdlt_formatutil
///     bdlt_iso8601utilconfiguration
///     bdlt_iso8601utilparseconfiguration
///     bdlt_literal_specifierformatter                                  !PRIVATE!
///     bdlt_monthofyear
///     bdlt_posixdateimputil
///     bdlt_prolepticdateimputil
///     bdlt_timeunitratio
/// @endcode
///
/// ## Component Synopsis {#bdlt-component-synopsis}
///
///  @ref bdlt_calendar :
///       Provide fast repository for accessing weekend/holiday information.
/// 
///  @ref bdlt_calendarcache :
///       Provide an efficient cache for read-only `bdlt::Calendar` objects.
/// 
///  @ref bdlt_calendarloader :
///       Provide a protocol (or pure interface) for loading calendars.
/// 
///  @ref bdlt_calendarreverseiteratoradapter :
///       Provide reverse iterator adapter for calendar iterators.
/// 
///  @ref bdlt_calendarutil :
///       Provide common date manipulations requiring a calendar.
/// 
///  @ref bdlt_currenttime :
///       Provide utilities to retrieve the current time.
/// 
///  @ref bdlt_date :
///       Provide a value-semantic type to represent dates.
/// 
///  @ref bdlt_dateformatter :
///       Provide `bsl::formatter` specialization for `bdlt::Date`.
/// 
///  @ref bdlt_datetime :
///       Provide a value-semantic type representing both date and time.
/// 
///  @ref bdlt_datetimeformatter :
///       Provide `bsl::formatter` specialization for `bdlt::Datetime`.
/// 
///  @ref bdlt_datetimeimputil :
///       Provide constants useful for encoding datetimes.
/// 
///  @ref bdlt_datetimeinterval :
///       Provide a representation of an interval of time.
/// 
///  @ref bdlt_datetimeintervalutil :
///       Provide non-primitive operations on `bdlt::DatetimeInterval`.
/// 
///  @ref bdlt_datetimetz :
///       Provide a representation of a date and time with time zone offset.
/// 
///  @ref bdlt_datetimetzformatter :
///       Provide `bsl::formatter` specialization for `bdlt::DatetimeTz`.
/// 
///  @ref bdlt_datetimeutil :
///       Provide common non-primitive operations on `bdlt::Datetime`.
/// 
///  @ref bdlt_datetz :
///       Provide a representation of a date with time zone offset.
/// 
///  @ref bdlt_datetzformatter :
///       Provide `bsl::formatter` specialization for `bdlt::DateTz`.
/// 
///  @ref bdlt_dateutil :
///       Provide common non-primitive operations on date objects.
/// 
///  @ref bdlt_dayofweek :
///       Provide an enumeration of the set of days of the week.
/// 
///  @ref bdlt_dayofweekset :
///       Provide an ordered set of (unique) `bdlt::DayOfWeek::Enum` values.
/// 
///  @ref bdlt_dayofweekutil :
///       Provide common non-primitive operations on `bdlt::DayOfWeek::Enum`.
/// 
///  @ref bdlt_defaultcalendarcache :
///       Provide a process-wide default `bdlt::CalendarCache` object.
/// 
///  @ref bdlt_defaulttimetablecache :
///       Provide a process-wide default `bdlt::TimetableCache` object.
/// 
///  @ref bdlt_epochutil :
///       Conversion between absolute/relative time with respect to epoch.
/// 
///  @ref bdlt_fixutil :
///       Provide conversions between date/time objects and FIX strings.
/// 
///  @ref bdlt_fixutilconfiguration :
///       Provide an attribute class to configure FIX string generation.
/// 
///  @ref bdlt_formatdoc :
///       Provide documentation for `bsl::format` of bdlt value types
/// 
///  @ref bdlt_formatter :
///       Provide a standard compliant `format` implementation.
/// 
///  @ref bdlt_formattestutil :
///       Provide macros and utilities for testing of `format` in bdlt.
/// 
///  @ref bdlt_formatutil :
///       Provide utilities for formatting `bdlt` types
/// 
///  @ref bdlt_fuzzutil :
///       Provide creation of `bdlt` data types from fuzz data.
/// 
///  @ref bdlt_intervalconversionutil :
///       Provide functions to convert between time-interval representations.
/// 
///  @ref bdlt_iso8601util :
///       Provide conversions between date/time objects and ISO 8601 strings.
/// 
///  @ref bdlt_iso8601utilconfiguration :
///       Provide an attribute class to configure ISO 8601 string generation.
/// 
///  @ref bdlt_iso8601utilparseconfiguration :
///       Provide an attribute class to configure ISO 8601 string parsing.
/// 
///  @ref bdlt_literal_specifierformatter :                                  !PRIVATE!
///       Provide a specifier formatter for formatting simple literal values.
/// 
///  @ref bdlt_localtimeoffset :
///       Provide utilities to retrieve the local time offset.
/// 
///  @ref bdlt_monthofyear :
///       Enumerate the set of month-of-year values.
/// 
///  @ref bdlt_packedcalendar :
///       Provide a compact repository for weekend/holiday information.
/// 
///  @ref bdlt_posixdateimputil :
///       Provide low-level support functions for date-value manipulation.
/// 
///  @ref bdlt_prolepticdateimputil :
///       Provide low-level support functions for date-value manipulation.
/// 
///  @ref bdlt_serialdateimputil :
///       Provide low-level support functions for date-value manipulation.
/// 
///  @ref bdlt_time :
///       Provide a value-semantic type representing time-of-day.
/// 
///  @ref bdlt_timeformatter :
///       Provide `bsl::formatter` specialization for `bdlt::Time`.
/// 
///  @ref bdlt_timetable :
///       Provide a repository for accessing timetable information.
/// 
///  @ref bdlt_timetablecache :
///       Provide an efficient cache for read-only `bdlt::Timetable` objects.
/// 
///  @ref bdlt_timetableloader :
///       Provide a protocol (or pure interface) for loading timetables.
/// 
///  @ref bdlt_timetz :
///       Provide a representation of a time with time zone offset.
/// 
///  @ref bdlt_timetzformatter :
///       Provide `bsl::formatter` specialization for `bdlt::TimeTz`.
/// 
///  @ref bdlt_timeunitratio :
///       Provide constants characterizing ratios between common time units.
/// 
///  @ref bdlt_timeutil :
///       Provide common non-primitive operations on `bdlt::Time`.
/// 
///  @ref bdlt_timezoneformatter :
///       Provide a mechanism for formatting time zones.
///
/// ## Value Types {#bdlt-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 {#bdlt-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.
/// @code
///  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 ]
/// @endcode
/// Further note that:
///  * The date values follow the Unix (POSIX) calendar (see @ref 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.
/// @code
///  Type             Difference Type
///  -------          ----------------
///  Date             int (days)
///  Time             DatetimeInterval
///  Datetime         DatetimeInterval
///  DatetimeInterval DatetimeInterval
/// @endcode
/// 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 {#bdlt-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 @ref bdetu_unset .)
///
/// ### Timezone Augmented Value Types: DateTz, TimeTz and DatetimeTz {#bdlt-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:
/// @code
///  Basis Type    Augmented Type
///  ----------    ----------------
///  bldt:Date     bdlt::DateTz
///  bldt:Time     bdlt::TimeTz
///  bldt:Datetime bdlt::DatetimeTz
/// @endcode
/// 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 {#bdlt-enumerated-values}
///
/// The 'bdlt' package provides enumerations in @ref bdlt_monthofyear  and
/// @ref bdlt_dayofweek .  The @ref bdlt_dayofweekset  provides an efficient, ordered
/// container of unique 'btdl::DayofWeek::Enum' values (i.e., containing no more
/// than seven elements).
///
/// ## Utilities {#bdlt-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 {#bdlt-obtaining-current-date-time-and-local-time-offset-values}
///
/// The @ref 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 @ref 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 {#bdlt-advanced-date-arithmetic-bdlt-dateutil}
///
/// The @ref 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 {#bdlt-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 @ref 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).
/// @code
///  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]')
/// @endcode
///
/// ### Conversion of Conventional Time Units {#bdlt-conversion-of-conventional-time-units}
///
/// The @ref 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 {#bdlt-usage}
///
/// This section illustrates intended use of these components.
///
/// ### Example 1: Celebrating Milestone Dates {#bdlt-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:
/// @code
///    bdlt::Datetime dtBirthday = bdlt::EpochUtil::epoch();
///    assert(bdlt::Datetime(1970, 1, 1, 0, 0, 0, 0) == dtBirthday);
/// @endcode
/// Next, we calculate the milestone date (and time).
/// @code
///    bdlt::Datetime dt20k(dtBirthday);  dt20k.addDays(20000);
///    assert(bdlt::DatetimeInterval(20000) == dt20k - dtBirthday);
///
///    bsl::cout << dt20k << bsl::endl;
/// @endcode
/// and find:
/// @code
///  04OCT2024_00:00:00.000000
/// @endcode
/// 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.
/// @code
///    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;
/// @endcode
/// which is one calendar day earlier:
/// @code
///  03OCT2024_20:00:00.000000-0400
/// @endcode
/// 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.
/// @code
///    bdlt::DayOfWeekSet weekendDays;
///    weekendDays.add(bdlt::DayOfWeek::e_SATURDAY);
///    weekendDays.add(bdlt::DayOfWeek::e_SUNDAY);
/// @endcode
/// 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.
/// @code
///    bdlt::Date milestone = dtz20kLocal.localDatetime().date();
///    bdlt::Date holdDate  = weekendDays.isMember(milestone.dayOfWeek())
///                         ? milestone
///                         : bdlt::DateUtil::nextDayOfWeek(
///                                                   bdlt::DayOfWeek::e_SATURDAY,
///                                                   milestone);
/// @endcode
/// Finally, we examine our results:
/// @code
///    bsl::cout << "Milestone:"          << " "
///              << milestone.dayOfWeek() << " "
///              << milestone             << bsl::endl;
///
///    bsl::cout << "Hold date:"          << " "
///              << holdDate.dayOfWeek()  << " "
///              << holdDate              << bsl::endl;
/// @endcode
/// we find:
/// @code
///  Milestone: THU 03OCT2024
///  Hold date: SAT 05OCT2024
/// @endcode
/// and we send out hold-the-date requests to our friends and family.
///
/// @}
/** @} */