Component baltzo_localtimedescriptor [Package baltzo]

Provide an attribute class for characterizing local time values. More...

Namespaces
namespace	baltzo

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Converting Between UTC and Local Times

Purpose:

Provide an attribute class for characterizing local time values.

Classes:

baltzo::LocalTimeDescriptor

attributes characterizing a local time

See also:

Component baltzo_zoneinfo

Description:

This component provides a single, simply constrained (value-semantic) attribute class, baltzo::LocalTimeDescriptor, that is used to characterize subsets of local time values within time zones. Note that this class is consistent with the "local-time types" found in the "Zoneinfo" representation of a time zone (see baltzo_zoneinfo).

Attributes:

  Name                Type         Default  Simple Constraints
  ------------------  -----------  -------  ------------------
  description         bsl::string  ""       none
  dstInEffectFlag     bool         false    none
  utcOffsetInSeconds  int          0        [-86399 .. 86399]

• description: non-canonical, non-localized name (intended for debugging).
• dstInEffectFlag: true if the described local times are Daylight-Saving-Time (DST) values.
• utcOffsetInSeconds: offset from UTC of the described local times.

For example, in New York on January 1, 2011, the local time is Eastern Standard Time, Daylight-Saving Time (DST) is not in effect, and the offset from UTC is -5 hours. We can represent this information using a baltzo::LocalTimeDescriptor object whose description is "EST", dstInEffectFlag is false, and utcOffsetInSeconds is -18,000 (-5 * 60 * 60). Note that description is not canonical, and is intended for development and debugging only.

Usage:

This section illustrates intended use of this component.

Example 1: Converting Between UTC and Local Times:

When using the "Zoneinfo" database, we want to represent and access the local time information contained in the "Zoneinfo" binary data files. Once we have obtained this information, we can use it to convert times from one time zone to another. The following code illustrates how to perform such conversions using baltzo::LocalTimeDescriptor.

First, we define a baltzo::LocalTimeDescriptor object that characterizes the local time in effect for New York Daylight-Saving Time in 2010:

  enum { NEW_YORK_DST_OFFSET = -4 * 60 * 60 };  // -4 hours in seconds

  baltzo::LocalTimeDescriptor newYorkDst(NEW_YORK_DST_OFFSET, true, "EDT");

  assert(NEW_YORK_DST_OFFSET == newYorkDst.utcOffsetInSeconds());
  assert(               true == newYorkDst.dstInEffectFlag());
  assert(              "EDT" == newYorkDst.description());

Then, we create a bdlt::Datetime representing the time "Jul 20, 2010 11:00" in New York:

  bdlt::Datetime newYorkDatetime(2010, 7, 20, 11, 0, 0);

Next, we convert newYorkDatetime to its corresponding UTC value using the newYorkDst descriptor (created above); note that, when converting from a local time to a UTC time, the signed offset from UTC is subtracted from the local time:

  bdlt::Datetime utcDatetime = newYorkDatetime;
  utcDatetime.addSeconds(-newYorkDst.utcOffsetInSeconds());

Then, we verify that the result corresponds to the expected UTC time, "Jul 20, 2010 15:00":

  assert(bdlt::Datetime(2010, 7, 20, 15, 0, 0) == utcDatetime);

Next, we define a baltzo::LocalTimeDescriptor object that describes the local time in effect for Rome in the summer of 2010:

  enum { ROME_DST_OFFSET = 2 * 60 * 60 };  // 2 hours in seconds

  baltzo::LocalTimeDescriptor romeDst(ROME_DST_OFFSET, true, "CEST");

  assert(ROME_DST_OFFSET == romeDst.utcOffsetInSeconds());
  assert(           true == romeDst.dstInEffectFlag());
  assert(         "CEST" == romeDst.description());

Now, we convert utcDatetime to its corresponding local-time value in Rome using the romeDst descriptor (created above):

  bdlt::Datetime romeDatetime = utcDatetime;
  romeDatetime.addSeconds(romeDst.utcOffsetInSeconds());

Notice that, when converting from UTC time to local time, the signed offset from UTC is added to UTC time rather than subtracted.

Finally, we verify that the result corresponds to the expected local time, "Jul 20, 2010 17:00":

  assert(bdlt::Datetime(2010, 7, 20, 17, 0, 0) == romeDatetime);