Component baltzo_localtimeoffsetutil [Package baltzo]

Provide utilities for a bdlt_localtimeoffset local time callback. More...

Namespaces
namespace	baltzo

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Usage
    • Example 1: Using localTimeOffset as the Local Time Offset Callback

Purpose:

Provide utilities for a bdlt_localtimeoffset local time callback.

Classes:

baltzo::LocalTimeOffsetUtil

utilities managing a local time callback

See also:

Component bdlt_localtimeoffset

Description:

This component, baltzo::LocalTimeOffsetUtil, provides baltzo::LocalTimeOffsetUtil::localTimeOffset, a high performance bdlt::LocalTimeOffset local time offset callback function, which accesses the Zoneinfo database. To achieve high performance, this function refers to a cached copy of local time period information (which includes the local time offset from UTC) that is populated by a call to one of the configure methods. The cache must be configured prior to the first call of localTimeOffset. That cached information is updated on receipt of a request with a datetime value outside of the range covered by the cached information. As there are usually are only a few timezone transitions per year, the cache hit rate should be very high for typical applications. The cached information might be invalidated by updates to the Zoneinfo database; however, those occur are also infrequent events.

A successful return from one of the configure methods is a prerequisite to the use of most of the other functions provided here. Most methods are thread-safe. Refer to the function-level documentation for details.

Usage:

This section illustrates intended use of this component.

Example 1: Using localTimeOffset as the Local Time Offset Callback:

Suppose we must quickly generate time stamp values in local time (e.g., on records for a high frequency logger) and the default performance of the relevant methods of bdlt::CurrentTime is inadequate. Further suppose that we must do so arbitrary time values and time zones. Those requirements can be met by installing the localTimeOffset method of baltzo::LocalTimeOffsetUtil as the local time callback used by bdlt::CurrentTime.

First, specify the time zone to be used by the callback and a UTC date time for the initial offset information in the cache.

  assert(0 == baltzo::LocalTimeOffsetUtil::updateCount());

  int status = baltzo::LocalTimeOffsetUtil::configure("America/New_York",
                                                      bdlt::Datetime(2013,
                                                                       2,
                                                                      26));
  assert(0 == status);
  assert(1 == baltzo::LocalTimeOffsetUtil::updateCount());

  bsl::string timezone;

  baltzo::LocalTimeOffsetUtil::loadTimezone(&timezone);
  assert(0 == strcmp("America/New_York", timezone.c_str()));

Notice that the value returned by the updateCount method is increased by one after then time zone information has been set.

Then, use the setLoadLocalTimeOffsetCallback method to set the localTimeOffset of baltzo::LocalTimeOffsetUtil as the local time offset callback used in bdlt::CurrentTime.

  bdlt::LocalTimeOffset::LocalTimeOffsetCallback previousCallback =
               baltzo::LocalTimeOffsetUtil::setLoadLocalTimeOffsetCallback();

  assert(&baltzo::LocalTimeOffsetUtil::localTimeOffset
      == bdlt::CurrentTime::localTimeOffsetCallback());

Notice that previously installed callback was saved so we can restore it, if needed.

Now, calls to bdlt::CurrentTime methods will use the method we installed. For example, we can check the time offset in New York for three dates of interest:

  bsls::Types::Int64 offsetInSeconds =
      bdlt::LocalTimeOffset::localTimeOffset(bdlt::Datetime(2013, 2, 26))
                                                             .totalSeconds();
  assert(        0 == status);
  assert(-5 * 3600 == offsetInSeconds);
  assert(        1 == baltzo::LocalTimeOffsetUtil::updateCount());

  baltzo::LocalTimeOffsetUtil::loadTimezone(&timezone);
  assert(        0 == strcmp("America/New_York", timezone.c_str()));

  offsetInSeconds =
      bdlt::LocalTimeOffset::localTimeOffset(bdlt::Datetime(2013, 7, 4))
                                                             .totalSeconds();
  assert(-4 * 3600 == offsetInSeconds);
  assert(        2 == baltzo::LocalTimeOffsetUtil::updateCount());
  baltzo::LocalTimeOffsetUtil::loadTimezone(&timezone);
  assert(        0 == strcmp("America/New_York", timezone.c_str()));

  offsetInSeconds =
      bdlt::LocalTimeOffset::localTimeOffset(bdlt::Datetime(2013, 12, 21))
                                                             .totalSeconds();
  assert(-5 * 3600 == offsetInSeconds);
  assert(        3 == baltzo::LocalTimeOffsetUtil::updateCount());
  baltzo::LocalTimeOffsetUtil::loadTimezone(&timezone);
  assert(        0 == strcmp("America/New_York", timezone.c_str()));

Notice that the value returned by updateCount() is unchanged by our first request, but incremented by the second and third request, which transitions into and then out of daylight saving time. Also notice that the updates change the offset information but do not change the timezone.

Finally, we restore the original local time callback.

  previousCallback = bdlt::LocalTimeOffset::setLocalTimeOffsetCallback(
                                                           previousCallback);
  ASSERT(previousCallback == &baltzo::LocalTimeOffsetUtil::localTimeOffset);