bdlt_datetz

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Caveats on Time Zone Support
  • ISO Standard Text Representation
  • Usage
    • Example 1: Representing Dates In Different Time Zones

Purpose

Provide a representation of a date with time zone offset.

Classes

• bdlt::DateTz: local-date value with time zone offset from UTC

See also

bdlt_date, bdlt_datetimetz

Description

This component provides a single value-semantic class, bdlt::DateTz, that represents a date value in a particular time zone. Each bdlt::DateTz object contains a time zone offset from UTC (in minutes) and a bdlt::Date value in that time zone. For logical consistency, the date 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.

Caveats on Time Zone Support

A bdlt::DateTz 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.

The second problem is more subtle. A given offset from UTC might be "valid" in that it corresponds to a real time zone, but the actual date value might not exist in that time zone. To make matters worse, a "valid" offset may not (indeed, rarely will) specify one time zone uniquely. Moreover, the date value might be valid in one time zone corresponding to a given offset, and not in another 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 date" 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: Representing Dates In Different Time Zones

Suppose that we need to compare dates in different time zones. The bdlt::DateTz type helps us to accomplish this by providing the utcStartTime method, which returns a bdlt::Datetime value corresponding to the UTC "point in time" when the local date starts (i.e. 000 hours local time).

First, we default construct an object dateTz1, which has an offset of 0, implying that the object represents a date in the UTC time zone.

bdlt::DateTz dateTz1;
assert(0                   == dateTz1.offset());
assert(dateTz1.localDate() == dateTz1.utcStartTime().date());
assert(dateTz1.localDate() == bdlt::Date());

Notice the value of a default contructed bdlt::DateTz object is the same as that of a default constructed bdlt::Date object.

Then, we construct two objects dateTz2 and dateTz3 to have a local date of 2013/12/31 in the EST time zone (UTC-5) and the pacific time zone (UTC-8) respectively:

bdlt::DateTz dateTz2 (bdlt::Date(2013, 12, 31), -5 * 60);
bdlt::DateTz dateTz3 (bdlt::Date(2013, 12, 31), -8 * 60);

Next, we compare the local dates of the two DateTz objects, and verify that they compare equal:

bdlt::Date localDate(2013, 12, 31);
assert(localDate == dateTz2.localDate());
assert(localDate == dateTz3.localDate());

Now, we compare the starting time of the two DateTz objects using the utcStartTime method:

assert(dateTz2.utcStartTime() < dateTz3.utcStartTime());