Component baltzo_localtimeperiod [Package baltzo]

Provide a type describing local time over a time period. More...

Namespaces
namespace	baltzo

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Attributes
  • Usage
    • Example 1: Converting a UTC Time to a Local Time

Purpose:

Provide a type describing local time over a time period.

Classes:

baltzo::LocalTimePeriod

time descriptor and period of applicability

See also:

Component baltzo_localtimedescriptor, Component baltzo_zoneinfoutil

Description:

This component provides a single, complex-constrained (value-semantic) attribute class, baltzo::LocalTimePeriod, that describes a period of time over which a local time description (UTC offset, DST status, and a descriptive string) is in effect.

Attributes:

  Name            Type                        Default  Simple Constraints
  -------------   --------------------------  -------  ------------------
  descriptor      baltzo::LocalTimeDescriptor  default  none
  utcStartTime    bdlt::Datetime               default  none
  utcEndTime      bdlt::Datetime               default  none

  Complex Constraints
  -----------------------------------------------------------------
  'utcStartTime == utcEndTime ||
  (utcStartTime != bdlt::Datetime() && utcEndTime != bdlt::Datetime()
   && utcStartTime < utcEndTime)'

• localTimeDescriptor: a description of local time that applies during the interval defined by startUtcTime and endUtcTime.
• utcStartTime: UTC representation of the start of the time interval over which localTimeDescriptor applies.
• utcEndTime: UTC representation of the moment immediately after the end of the time interval over which localTimeDescriptor applies.

For example, in New York in 2010, the local time was Eastern Daylight Time ("EDT") from March 14, 2010 to November 7, 2010, and during Eastern Daylight Time, Daylight-Saving Time (DST) was in effect, and the offset from UTC was -4 hours. We can represent this information using a baltzo::LocalTimePeriod object whose utcStartTime is "Mar 14, 2010 07:00 UTC" (2AM EST), utcEndTime is "Nov 7, 2010 06:00 UTC" (1AM EST, what would have been 2AM EDT), and localTimeDescriptor has a description of "EDT", dstInEffectFlag of true, and a utcOffsetInSeconds of -14,400 (-4 * 60 * 60).

Usage:

This section illustrates intended use of this component.

Example 1: Converting a UTC Time to a Local Time:

In this example we illustrate how to use a local time period to convert a UTC time to the corresponding local time in some time zone.

First, we define a function that performs a conversion from UTC time to local time:

  int convertUtcToLocalTime(bdlt::Datetime                 *result,
                            const bdlt::Datetime&           utcTime,
                            const baltzo::LocalTimePeriod&  period)
      // Load into the specified 'result' the date-time value corresponding
      // to the specified 'utcTime' in the local time described by the
      // specified 'period'.  Return 0 on success, and a non-zero value if
      // 'utcTime < period.utcStartTime()' or
      // 'utcTime >= period.utcEndTime()'.
  {
      BSLS_ASSERT(result);

      if (utcTime <  period.utcStartTime() ||
          utcTime >= period.utcEndTime()) {
          return 1;                                                 // RETURN
      }

      *result = utcTime;
      result->addSeconds(period.descriptor().utcOffsetInSeconds());
      return 0;
  }

Then, we create a baltzo::LocalTimePeriod object, edt2010, that describes New York Daylight-Saving Time in 2010:

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

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

  baltzo::LocalTimePeriod     edt2010(edt,
                                      bdlt::Datetime(2010,  3, 14, 7),
                                      bdlt::Datetime(2010, 11,  7, 6));

  assert(bdlt::Datetime(2010,  3, 14, 7) == edt2010.utcStartTime());
  assert(bdlt::Datetime(2010, 11,  7, 6) == edt2010.utcEndTime());
  assert("EDT" == edt2010.descriptor().description());
  assert(true  == edt2010.descriptor().dstInEffectFlag());
  assert(NEW_YORK_DST_OFFSET == edt2010.descriptor().utcOffsetInSeconds());

Next, we create a bdlt::Datetime, utcDatetime, representing the (UTC) time "Jul 20, 2010 11:00":

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

Now, we use the convertUtcToLocalTime function we defined earlier to convert utcDatetime into its local time in Eastern Daylight Time (as described by edt2010):

  bdlt::Datetime localDatetime;
  int            status = convertUtcToLocalTime(&localDatetime,
                                                utcDatetime,
                                                edt2010);
  if (0 != status) {
      // The conversion failed so return an error code.

      return 1;                                                     // RETURN
  }

Finally, we verify that the result corresponds to the expected local time in New York, "Jul 20, 2010 7:00":

  assert(bdlt::Datetime(2010, 7, 20, 7) == localDatetime);