baltzo_localtimeperiod

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

baltzo_localtimedescriptor, 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:

/// 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()`.
int convertUtcToLocalTime(bdlt::Datetime                 *result,
                          const bdlt::Datetime&           utcTime,
                          const baltzo::LocalTimePeriod&  period)
{
    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);