baltzo_timezoneutilimp

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Prologue: Initializing an Example baltzo::ZoneinfoCache Object
    • Example 1: Converting from a UTC Time to a Local Time

Purpose

Implement utilities for converting times between time zones.

Classes

• baltzo::TimeZoneUtilImp: implementation utilities for converting times

See also

baltzo_localdatetime, baltzo_zoneinfo, baltzo_defaultzoneinfocache

Description

This component provides a namespace, baltzo::TimeZoneUtilImp, containing a set of utility functions for converting time values to and from, their corresponding local time representations in (possibly) different time zones. The primary methods provided include: convertUtcToLocalTime for converting time values to their corresponding local-time values in some time zone; convertLocalToUtc, for converting a local-time value into the corresponding UTC time value; and initLocalTime for initializing a local-time value. Additionally the loadLocalTimeForUtc method enable clients to obtain information about a time value, such as whether the provided time is a daylight-saving time value.

Usage

The following examples demonstrate how to use a baltzo::TimeZoneUtilImp to perform common operations on time values:

Prologue: Initializing an Example baltzo::ZoneinfoCache Object

Before using the methods provided by baltzo::TimeZoneUtilImp we must first define a baltzo::ZoneinfoCache object containing information about various time zones. For the purposes of this example, we will define a sample cache containing only data for New York loaded through a baltzo::TestLoader object. Note that, in general, clients should use data from an external data source (see baltzo_datafileloader ).

First, we create a Zoneinfo object for New York, and populate newYork with a correct time zone identifier:

baltzo::Zoneinfo newYork;
newYork.setIdentifier("America/New_York");

Next, we create two local-time descriptors, one for standard time and one for daylight-saving time:

baltzo::LocalTimeDescriptor est(-18000, false, "EST");
baltzo::LocalTimeDescriptor edt(-14400, true,  "EDT");

Then, we set the initial descriptor for newYork to Eastern Standard Time. Note that such an initial transition is required for a baltzo::Zoneinfo object to be considered Well-Defined (see baltzo_zoneinfoutil )

const bsls::Epoch::TimeT64 firstTransitionTime =
                bdlt::EpochUtil::convertToTimeT64(bdlt::Datetime(1, 1, 1));
 
newYork.addTransition(firstTransitionTime, est);

Next, we create a series of transitions between these local-time descriptors for the years 2007-2011. Note that the United States transitions to daylight saving time on the second Sunday in March, at 2am local time (07:00 UTC), and transitions back to standard time on the first Sunday in November at 2am local time (06:00 UTC), resulting in an even number of transitions:

static const bdlt::Datetime TRANSITION_TIMES[] = {
    bdlt::Datetime(2007,  3, 11, 7),
    bdlt::Datetime(2007, 11,  4, 6),
    bdlt::Datetime(2008,  3,  9, 7),
    bdlt::Datetime(2008, 11,  2, 6),
    bdlt::Datetime(2009,  3,  8, 7),
    bdlt::Datetime(2009, 11,  1, 6),
    bdlt::Datetime(2010,  3, 14, 7),
    bdlt::Datetime(2010, 11,  7, 6),
    bdlt::Datetime(2011,  3, 13, 7),
    bdlt::Datetime(2011, 11,  6, 6),
};
const int NUM_TRANSITION_TIMES =
                        sizeof TRANSITION_TIMES / sizeof *TRANSITION_TIMES;
assert(0 == NUM_TRANSITION_TIMES % 2);
 
for (int i = 0; i < NUM_TRANSITION_TIMES; i += 2) {
 
    const bsls::Epoch::TimeT64 edtTransitionTime =
                    bdlt::EpochUtil::convertToTimeT64(TRANSITION_TIMES[i]);
    newYork.addTransition(edtTransitionTime, edt);
 
    const bsls::Epoch::TimeT64 estTransitionTime =
                bdlt::EpochUtil::convertToTimeT64(TRANSITION_TIMES[i + 1]);
    newYork.addTransition(estTransitionTime, est);
}

Next, we verify that the time zone information we have created is considered well-defined (as discussed above):

assert(true == baltzo::ZoneinfoUtil::isWellFormed(newYork));

Finally, we create a baltzo::TestLoader object, provide it the description of newYork, and use it to initialize a baltzo::ZoneinfoCache object:

baltzo::TestLoader loader;
loader.setTimeZone(newYork);
baltzo::ZoneinfoCache cache(&loader);

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

In this example we demonstrate how to convert a UTC time to the corresponding local time using the convertUtcToLocalTime class method.

We start by creating a bdlt::Datetime representing the UTC time "Dec 12, 2010 15:00":

bdlt::Datetime utcTime(2010, 12, 12, 15, 0, 0);

Now, we call convertUtcToLocalTime and supply as input utcTime, the time zone identifier for New York ("America/New_York"), and the cache of time zone information created in the prologue:

bdlt::DatetimeTz localNYTime;
baltzo::TimeZoneUtilImp::convertUtcToLocalTime(&localNYTime,
                                              "America/New_York",
                                              utcTime,
                                              &cache);

Finally we verify that localNYTime is "Dec 12, 2010 10:00+5:00", the time in New York corresponding to the UTC time "Dec 12, 2010 15:00".

assert(utcTime                         == localNYTime.utcDatetime());
assert(bdlt::Datetime(2010, 12, 12, 10) == localNYTime.localDatetime());
assert(-5 * 60                         == localNYTime.offset());