Component baltzo_timezoneutilimp [Package baltzo]

Implement utilities for converting times between time zones. More...

Namespaces
namespace	baltzo

---

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:

Component baltzo_localdatetime, Component baltzo_zoneinfo, Component 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());