Component bdlt_timetz [Package bdlt]

Provide a representation of a time with time zone offset. More...

Namespaces
namespace	bdlt

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Caveats on Time Zone Support
  • ISO Standard Text Representation
  • Usage
    • Example 1: Comparing Times from Multiple Time Zones

Purpose:

Provide a representation of a time with time zone offset.

Classes:

bdlt::TimeTz

local-time value with time zone offset from UTC

See also:

Component bdlt_time, Component bdlt_datetimetz

Description:

This component provides a single, simply constrained value-semantic class, bdlt::TimeTz, that represents a time value in a particular time zone. Each bdlt::TimeTz object contains a time zone offset from UTC (in minutes) and a bdlt::Time value in that time zone. For logical consistency, the time value and offset should correspond to a geographically valid time zone, but such consistency is the user's responsibility. This component does not enforce logical constraints on any values.

The localTime and utcTime methods return bdlt::Time values corresponding to the local time and UTC time represented by the object, respectively. In addition, the offset method returns the time zone offset in minutes from UTC (i.e., UTC + offset equals local time).

Attributes:

  Name                Type         Default         Simple Constraints
  ------------------  -----------  --------------  ------------------
  localTime           bdlt::Time   '24:00:00.000'  none
  offset              int          0               ( -1440 .. 1440 )

• localTime: local time in the timezone described by offset.
• offset: offset from UTC (in minutes) of the time zone in which localTime occurs.

Caveats on Time Zone Support:

A bdlt::TimeTz value is intended to be interpreted as a value in a local time zone, along with the offset of that value from UTC. However, there are some problems with this simple interpretation. First of all, the offset value may not correspond to any time zone that has ever existed. For example, the offset value could be set to one minute, or to 1,234 minutes. The meaning of the resulting "local time" value is always clear, but the local time might not correspond to any geographical or historical time zone.

For these reasons (and others), this component cannot and does not perform any validation relating to time zones or offsets. The user must take care to honor the "local time" contract of this component.

ISO Standard Text Representation:

A common standard text representation of a date and time value is described by ISO 8601. BDE provides the bdlt_iso8601util component for conversion to and from the standard ISO8601 format.

Usage:

This section illustrates intended use of this component.

Example 1: Comparing Times from Multiple Time Zones:

Some legacy systems may represent points in time as a combination of a local time-of-day plus an offset from UTC, with an underlying assumption that the dates on which points in time occur can be inferred from context. Assuming that we know that two such times fall on the same (local) calendar date, we can determine whether or not the two times coincide by comparing their bdlt::TimeTz representations.

First, we define three bdlt::TimeTz objects representing the time in three different time zones on the same (local) date:

  bdlt::TimeTz newYorkTime(bdlt::Time(9, 30, 0, 0.0),
                           -5 * bdlt::TimeUnitRatio::k_MINUTES_PER_HOUR);
  bdlt::TimeTz chicagoTime(bdlt::Time(8, 30, 0, 0.0),
                           -6 * bdlt::TimeUnitRatio::k_MINUTES_PER_HOUR);
  bdlt::TimeTz phoenixTime(bdlt::Time(6, 30, 0, 0.0),
                           -7 * bdlt::TimeUnitRatio::k_MINUTES_PER_HOUR);

Then, we observe that the local times are distinct:

  assert(newYorkTime.localTime() != chicagoTime.localTime());
  assert(chicagoTime.localTime() != phoenixTime.localTime());
  assert(phoenixTime.localTime() != newYorkTime.localTime());

Next, we observe that newYorkTime and chicagoTime actually represent the same point in time:

  assert(newYorkTime.utcTime() == chicagoTime.utcTime());

Finally, we observe that phoenixTime is one hour earlier than newYorkTime:

  bdlt::DatetimeInterval delta =
                               newYorkTime.utcTime() - phoenixTime.utcTime();

  assert(0 == delta.days());
  assert(1 == delta.hours());
  assert(0 == delta.minutes());
  assert(0 == delta.seconds());
  assert(0 == delta.milliseconds());