- Generated by
1.9.8
|
BDE 4.14.0 Production release
|
Provide utility operations on baltzo::Zoneinfo objects.
baltzo::Zoneinfo objectThis component provides a suite of pure functions that operate on objects of type baltzo::Zoneinfo. A baltzo::Zoneinfo is a value semantic-type providing information about a time zone, mirroring the information found in the Zoneinfo Database, a public-domain distribution of time zone data (see baltzo_zoneinfo for more information). The primary functions provided by baltzo::ZoneinfoUtil are convertUtcToLocalTime and loadRelevantTransitions: convertUtcToLocalTime converts a UTC time into its corresponding local time in the time zone described by the supplied baltzo::Zoneinfo object; loadRelevantTransitions returns the transition, from the supplied baltzo::Zoneinfo object's list of transitions that describes the attributes of local time in effect at supplied local time; returning two possible transitions in instances where the supplied local time is either invalid or ambiguous (see baltzo_localtimevalidity ). Note that the time supplied as input to convertUtcToLocalTime is a UTC time, whereas the time supplied as input to loadRelevantTransitions is a local time.
The function loadRelevantTransitions is used to find the transition in a baltzo::Zoneinfo object that describes the properties of a client supplied local time value. In instances where the client supplied local time is either ambiguous or invalid loadRelevantTransitions returns an alternative transition that refers to a second set of properties that could be used to describe the supplied local time. To understand why multiple transitions might be needed, consider the impact of daylight-saving time transitions on local time in New York:
In New York, clocks are set forward an hour in the spring, creating the discontinuity between T2 and T3 in the diagram. A New York local time value in the range [T2, T3) is considered invalid, because a correctly set clock in New York would never display that value. Similarly, clocks are set back an hour in the fall, creating the discontinuity between T4 and T5 in the diagram. A New York local time value in the range [T4, T5) is considered ambiguous, as local times in that range occur twice. For either invalid or ambiguous times, loadRelevantTransitions will return two distinct iterators referring to the adjacent transitions holding the two descriptions that might be applied to that local time.
For example, consider the returned validity and transitions for the following New York local times:
The primary operations provided by this component require the supplied Zoneinfo value meet certain constraints that are not enforced by the baltzo::Zoneinfo type itself. A Zoneinfo meeting these constraints is considered well-formed, and baltzo::ZoneinfoUtil::isWellFormed will return true for such a value. Specifically, a baltzo::Zoneinfo object is considered well-formed only if all of the following are true:
bdlt::Datetime value, "Jan 01, 0001 00:00" – i.e., bdlt::Datetime(1, 1, 1).Note that baltzo::ZoneinfoUtil::isWellFormed has linear complexity with respect to the number of transitions that the Zoneinfo value defines.
In order to better understand the 3rd constraint (above) on a well-formed Zoneinfo object, first, notice that Figure 1 above (showing local time in New York) illustrates a well-formed sequence of transitions. Both Transition 2 (to EDT) and Transition 3 (to EST) introduce a range of ambiguous or invalid times (ambiguous when clocks are adjusted backwards, invalid when clocks are adjusted forward), but those two ranges of ambiguous and invalid local times do not overlap.
However, a Zoneinfo object is not well-formed if two transitions occur so close together that the respective ranges of invalid or ambiguous times that those transitions introduce, overlap with one and other, as illustrated in Figure 2.
Notice that between [ 00:30 .. 01:00 ] local time, the range of invalid times introduced by Transition 1, overlaps with the range of ambiguous times introduced by Transition 2. The above time zone would therefore not be well-formed.
The following examples demonstrate how to use a ZoneinfoUtil to perform common operations on time values using a Zoneinfo description of a time zone.
We start by creating a Zoneinfo time zone description for New York, which we will use in subsequent examples. Note that, in practice, clients should obtain time zone information from a data source (see baltzo_zoneinfocache ).
First we create a Zoneinfo object for New York, and populate newYork with the correct time zone identifier:
Next we create two local-time descriptors, one for standard time and one for daylight-saving time:
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-Formed (see isWellFormed):
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:
Finally we verify that the time zone information we've created is considered well-formed (as discussed above):
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":
Now, we call convertUtcToLocalTime and supply as input both utcTime and the Zoneinfo description for newYork (which we initialized in the prologue above):
Then 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".
Finally, we verify that the returned iterator refers to the local-time transition immediately before utcTime, and that that transition refers to a local-time descriptor characterizing standard-time in New York:
In this next example we use loadRelevantTransitions to determine the local-time descriptor (see baltzo_localtimedescriptor ) that applies to a local time value, represented using a bdlt::Datetime object.
We start by defining a bdlt::Datetime object for "Jan 1, 2011 12:00" in New York:
Then, we call loadRelevantTransitions, and supply, as input, both nyLocalTime and the Zoneinfo description for newYork (which we initialized in the prologue above):
"Jan 1, 2011 12:00" in New York, is not near a daylight-saving time transition, so it uniquely describes a valid time (in New York) which falls during Eastern Standard Time, and whose local time offset from UTC is -5:00. Because "Jan 1, 2011 12:00" is both a valid and unique local time, the returned validity will be baltzo::LocalTimeValidity::e_VALID_UNIQUE and the two returned transition iterators will be equal:
Next, we create a second bdlt::Datetime object to represent "Nov 7, 2010
1:30" in New York. Note that the clock time "Nov 7, 2010 1:30" occurred twice in New York, as clocks were set back by an hour an instant before the local clock would have reached "Nov 7, 2010 02:00 EDT", and it is therefore ambiguous which of those two values that local time is meant to refer.
Now, we call loadRelevantTransitions, this time supplying ambiguousLocalTime:
Finally we observe that the local time was ambiguous and that the returned transitions are distinct:
Because ambiguousLocalTime may refer to either the standard or the daylight-saving time value "Nov 7, 2010 01:30", the returned validity will be e_VALID_AMBIGUOUS, and the first and second iterators will differ. first will refer to a description of the local time before the transition (daylight-saving time) and second will refer to a description of local time after the transition (standard-time):
Note that the two transitions returned are adjacent:
1.9.8