baltzo_localtimeoffsetutil

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

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);