Quick Links: |
Provide utilities for converting times among different time zones. More...
Namespaces | |
namespace | baltzo |
baltzo::TimeZoneUtil | utilities for converting local time values |
baltzo::TimeZoneUtil
, containing utility functions for converting time values to and from their corresponding local time representations in (possibly) different time zones. The primary methods provided include: convertLocalToLocalTime
and convertUtcToLocalTime
, for converting a time to the corresponding local-time value in some time zone; convertLocalToUtc
, for converting a local-time value into the corresponding UTC time value; initLocalTime
, for initializing a local-time value. loadLocalTimePeriod
and loadLocalTimePeriodForUtc
methods enable clients to obtain information about a time value, such as whether the provided time is a daylight-saving time value. Finally note that, all of the functions in this utility component make use of a process-wide cache of time-zone information (see baltzo_defaultzoneinfocache
). bdlt::Datetime
object holding a local time may not describe a valid or unique clock time in the local time zone (see baltzo_localtimevalidity
). When interpreting a local-time value represented using a bdlt::Datetime
object with respect to a given time zone, there are three possible scenarios: bdlt::Datetime
object) could refer to either of those two times. baltzo_dstpolicy
). baltzo::TimeZoneUtil
methods that take, as input, a bdlt::Datetime
object representing a local time (i.e., a local-time value without a UTC offset) also accept an optional baltzo::DstPolicy::Enum
. This (optional) argument policy allows clients to specify how they would like the operation to interpret the input value (as such a value may be ambiguous or invalid within the indicated time zone -- see above). Clients are, however, encouraged to use the default policy, e_UNSPECIFIED
, unless there is some specific reason they require a different option. baltzo::DstPolicy
values are supported: e_UNSPECIFIED
(default)
e_STANDARD
e_DST
mktime
and its interpretation of the tm_isdst
value of the supplied tm
structure. The behavior for the "unspecified" policy, however, is not strictly defined by either the ISO or POSIX standards, and varies among implementations. baltzo::DstPolicy
values have on a call to convertLocalToUtc
for several possible time values in New York. Note that standard local time in New York is UTC-5:00, and daylight-saving local time there is UTC-4:00. Result format: UTC 'bdlt::Time' & corresponding local 'bdlt::TimeTz'. ,--------------------------------------------------------------------------. | Input in New York | 'baltzo::DstPolicy::Enum' | | Local Time |-----------------------------------------------------| | (bdlt::Datetime) | *_UNSPECIFIED | *_STANDARD | *_DST | |==========================================================================| | Jan 1, 2010 01:30 | 06:30:00 UTC | 06:30:00 UTC | 05:30:00 UTC | | (standard time) | (01:30:00-5:00) | (01:30:00-5:00) | (00:30:00-5:00) | | | | [1] | [2] | |--------------------|-----------------------------------------------------| | Mar 14, 2010 02:30 | 07:30:00 UTC | 07:30:00 UTC | 06:30:00 UTC | | (invalid) | (03:30:00-4:00) | (03:30:00-4:00) | (01:30:00-5:00) | | | [3] | [4] | [5] | |--------------------|-----------------------------------------------------| | Apr 1, 2010 01:30 | 05:30:00 UTC | 06:30:00 UTC | 05:30:00 UTC | | (daylight-saving) | (01:30:00-4:00) | (02:30:00-4:00) | (01:30:00-4:00) | | | | [6] | [7] | |--------------------|-----------------------------------------------------| | Nov 7, 2010 01:30 | 06:30:00 UTC | 06:30:00 UTC | 05:30:00 UTC | | (ambiguous) | (01:30:00-5:00) | (01:30:00-5:00) | (01:30:00-4:00) | | | [8] | | | `--------------------------------------------------------------------------'
e_DST
, contradicts the actual occurrence of daylight-saving time in New York. The input time is adjusted by the UTC offset for daylight-saving time in New York (-4:00) resulting in a UTC time 05:30. Note that the result, "Jan 1, 2010 05:30 UTC", corresponds to the New York time "Jan 1, 2010 00:30:00-5:00" (a standard time). e_STANDARD
contradicts the actual occurrence of daylight-saving time in New York. The input time is adjusted by the UTC offset for standard time in New York (-5:00) resulting in a UTC time 06:30. Note that "Apr 1, 2010 06:30 UTC" corresponds to the New York time "Apr 1, 2010 02:30:00-4:00" (a daylight-saving time). baltzo::TimeZoneUtil
are thread-safe, meaning they can be safely executed concurrently. baltzo::TimeZoneUtil
to perform conversions on various time representations. bdlt::Datetime
object holding the UTC time "July 31, 2010 15:00:00": bdlt::Datetime utcTime(2010, 7, 31, 15, 0, 0);
baltzo::LocalDatetime
object to hold the result of the conversion operation: baltzo::LocalDatetime newYorkTime;
convertUtcToLocalTime
function in baltzo::TimeZoneUtil
: int status = baltzo::TimeZoneUtil::convertUtcToLocalTime(&newYorkTime, "America/New_York", utcTime); if (0 != status) { // A non-zero 'status' indicates there was an error in the conversion // (e.g., the time zone id was not valid or the environment has not // been correctly configured). return 1; // RETURN }
newYorkTime
is "July 31, 2010
11:00:00" and that the offset from UTC applied was -4 hours: const bdlt::Datetime test = newYorkTime.datetimeTz().localDatetime(); assert(2010 == test.year()); assert(11 == test.hour()); assert( 7 == test.month()); assert( 0 == test.minute()); assert( 31 == test.day()); assert( 0 == test.second()); assert( -4 * 60 == newYorkTime.datetimeTz().offset());
bdlt::Datetime
object representing the time "July 31,
2010 15:00:00" in New York: bdlt::Datetime newYorkTime(2010, 7, 31, 15, 0, 0);
baltzo::LocalDatetime
object representing the corresponding local time in Italy: baltzo::LocalDatetime romeTime; int status = baltzo::TimeZoneUtil::convertLocalToLocalTime( &romeTime, "Europe/Rome", newYorkTime, "America/New_York"); if (0 != status) { // A non-zero 'status' indicates there was an error in the conversion // (e.g., the time zone id was not valid or the environment has not // been correctly configured). return 1; // RETURN }
dstPolicy
argument to convertLocalToLocalTime
. The default value should be appropriate for most users. romeTime
is "July 31, 2010 21:00:00", which is the time in Italy corresponding to "July 31, 2010 15:00:00" in New York: const bdlt::Datetime test = romeTime.datetimeTz().localDatetime(); assert(2010 == test.year()); assert(21 == test.hour()); assert( 7 == test.month()); assert( 0 == test.minute()); assert( 31 == test.day()); assert( 0 == test.second()); assert( 2 * 60 == romeTime.datetimeTz().offset());
baltzo::LocalDatetime
from a bdlt::Datetime
, which may not represent a unique (or valid) clock time. bdlt::Datetime
object for the New York local time "Jul
31, 2010 15:00:00". Note that this local date-time occurs during a DST transition and is an invalid date-time. bdlt::Datetime uniqueTime(2010, 7, 31, 15, 0, 0);
initLocalTime
, which returns a baltzo::LocalDatetime
object. initLocalTime
also optionally returns baltzo::LocalTimeValidity::Enum
, indicating whether the provided input was a valid and unique clock time. Note that invalid or ambiguous times are resolved using the optionally provided baltzo::DstPolicy::Enum
(see the section Daylight-Saving Time (DST) Policies and Disambiguation): baltzo::LocalDatetime localTime; baltzo::LocalTimeValidity::Enum validity; int status = baltzo::TimeZoneUtil::initLocalTime(&localTime, &validity, uniqueTime, "America/New_York"); if (0 != status) { return 1; }
localTime
is "Jul 31, 2010 15:00:00" with an offset of -4:00 from UTC, in the time zone "America/New_York". const bdlt::Datetime invalidTest = localTime.datetimeTz().localDatetime(); assert(2010 == invalidTest.year()); assert(15 == invalidTest.hour()); assert( 7 == invalidTest.month()); assert( 0 == invalidTest.minute()); assert( 31 == invalidTest.day()); assert( 0 == invalidTest.second()); assert( -4 * 60 == localTime.datetimeTz().offset()); assert("America/New_York" == localTime.timeZoneId());
assert(baltzo::LocalTimeValidity::e_VALID_UNIQUE == validity);
initLocalTime
for a time value that falls during a during a daylight-saving time transition, the returned baltzo::LocalTimeValidity::Enum
will indicate if the supplied time either does not represent a valid clock time in the time zone (as may occur when clocks are set forward), or does not represent a unique clock time (as may occur when clocks are set back). initLocalTime
for "Mar 14, 2010 02:30"; this clock time does not occurs in New York, as clocks are set forward by an hour at 2am local time: bdlt::Datetime invalidTime(2010, 3, 14, 2, 30, 0); status = baltzo::TimeZoneUtil::initLocalTime(&localTime, &validity, invalidTime, "America/New_York"); if (0 != status) { return 1; }
localTime
represents a valid and unique time of "Mar 14, 2010 03:30:00-04:00" in the "America/New_York" time zone. const bdlt::Datetime test = localTime.datetimeTz().localDatetime(); assert(2010 == test.year()); assert( 3 == test.hour()); assert( 3 == test.month()); assert(30 == test.minute()); assert( 14 == test.day()); assert( 0 == test.second()); assert("America/New_York" == localTime.timeZoneId()); assert( -4 * 60 == localTime.datetimeTz().offset());
invalidTime
is e_INVALID
: assert(baltzo::LocalTimeValidity::e_INVALID == validity);
loadLocalTimePeriod
method. Using loadLocalTimePeriod
a client can determine, for a point in time, the attributes that characterize local time in a given time zone (e.g., the offset from UTC, whether it is daylight-saving time) as well as the interval over which those attributes apply (see baltzo_localtimeperiod
). baltzo::LocalDatetime
object for the New York local time "Jul 31, 2010 15:00:00-04:00". Note that this baltzo::LocalDatetime
may also be created as in example 3. bdlt::DatetimeTz localTimeTz(bdlt::Datetime(2010, 7, 31, 15, 0, 0), -4 * 60); baltzo::LocalDatetime localTime(localTimeTz, "America/New_York");
loadLocalTimePeriod
, which returns a baltzo::LocalTimePeriod
object that is loaded with attributes characterizing local time in New York on "Mar 14, 2010 03:30:00", and the interval over which those attributes are in effect. baltzo::LocalTimePeriod period; int status = baltzo::TimeZoneUtil::loadLocalTimePeriod(&period, localTime); if (0 != status) { // A non-zero 'status' indicates there was an error in the conversion // (e.g., the time zone id was not valid or the environment has not // been correctly configured). return 1; // RETURN }
assert(true == period.descriptor().dstInEffectFlag()); assert(-4 * 60 * 60 == period.descriptor().utcOffsetInSeconds()); assert("EDT" == period.descriptor().description()); assert(bdlt::Datetime(2010, 3, 14, 7, 0, 0) == period.utcStartTime()); assert(bdlt::Datetime(2010, 11, 7, 6, 0, 0) == period.utcEndTime());