- Generated by
1.9.8
|
BDE 4.39.x Production Release
|
Basic Development Library Time (bdlt)
Provide date and time vocabulary types, and related utilities.
Basic Development Library Time (bdlt)
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:
See {Value Types} and {Utilities} below for overviews of the types and functions provided by this package.
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.
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_dateformatter : Provide bsl::formatter specialization for bdlt::Date.
bdlt_datetime : Provide a value-semantic type representing both date and time.
bdlt_datetimeformatter : Provide bsl::formatter specialization for bdlt::Datetime.
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_datetimetzformatter : Provide bsl::formatter specialization for bdlt::DatetimeTz.
bdlt_datetimeutil : Provide common non-primitive operations on bdlt::Datetime.
bdlt_datetz : Provide a representation of a date with time zone offset.
bdlt_datetzformatter : Provide bsl::formatter specialization for bdlt::DateTz.
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_formatdoc : Provide documentation for bsl::format of bdlt value types
bdlt_formatter : Provide a standard compliant format implementation.
bdlt_formattestutil : Provide macros and utilities for testing of format in bdlt.
bdlt_formatutil : Provide utilities for formatting bdlt types
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_iso8601utilparseconfiguration : Provide an attribute class to configure ISO 8601 string parsing.
bdlt_literal_specifierformatter : !PRIVATE! Provide a specifier formatter for formatting simple literal values.
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_timeformatter : Provide bsl::formatter specialization for bdlt::Time.
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_timetzformatter : Provide bsl::formatter specialization for bdlt::TimeTz.
bdlt_timeunitratio : Provide constants characterizing ratios between common time units.
bdlt_timeutil : Provide common non-primitive operations on bdlt::Time.
bdlt_timezoneformatter : Provide a mechanism for formatting time zones.
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.
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.
Further note that:
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.
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}.
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:
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 .)
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:
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}.
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).
This package provides utility components that:
The bdlt_currenttime component provides:
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.
The bdet_dateutil component provides functions on 'bdlt::Date' values that extend those provided by the 'bdlt::Date' class itself. For example:
This utility also provides a function for conversion of 'bdlt::Date' values to and from 'int' values in the "YYYYMMDD" format.
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).
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'.
This section illustrates intended use of these components.
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:
Next, we calculate the milestone date (and time).
and find:
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.
which is one calendar day earlier:
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.
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.
Finally, we examine our results:
we find:
and we send out hold-the-date requests to our friends and family.
1.9.8