1 /*
2 **********************************************************************
3 * Copyright (c) 2003-2011, International Business Machines
4 * Corporation and others. All Rights Reserved.
5 **********************************************************************
6 * Author: Alan Liu
7 * Created: July 21 2003
8 * Since: ICU 2.8
9 **********************************************************************
10 */
11 #ifndef OLSONTZ_H
12 #define OLSONTZ_H
13
14 #include "unicode/utypes.h"
15
16 #if !UCONFIG_NO_FORMATTING
17
18 #include "unicode/basictz.h"
19
20 struct UResourceBundle;
21
22 U_NAMESPACE_BEGIN
23
24 class SimpleTimeZone;
25
26 /**
27 * A time zone based on the Olson tz database. Olson time zones change
28 * behavior over time. The raw offset, rules, presence or absence of
29 * daylight savings time, and even the daylight savings amount can all
30 * vary.
31 *
32 * This class uses a resource bundle named "zoneinfo". Zoneinfo is a
33 * table containing different kinds of resources. In several places,
34 * zones are referred to using integers. A zone's integer is a number
35 * from 0..n-1, where n is the number of zones, with the zones sorted
36 * in lexicographic order.
37 *
38 * 1. Zones. These have keys corresponding to the Olson IDs, e.g.,
39 * "Asia/Shanghai". Each resource describes the behavior of the given
40 * zone. Zones come in two different formats.
41 *
42 * a. Zone (table). A zone is a table resource contains several
43 * type of resources below:
44 *
45 * - typeOffsets:intvector (Required)
46 *
47 * Sets of UTC raw/dst offset pairs in seconds. Entries at
48 * 2n represents raw offset and 2n+1 represents dst offset
49 * paired with the raw offset at 2n. The very first pair represents
50 * the initial zone offset (before the first transition) always.
51 *
52 * - trans:intvector (Optional)
53 *
54 * List of transition times represented by 32bit seconds from the
55 * epoch (1970-01-01T00:00Z) in ascending order.
56 *
57 * - transPre32/transPost32:intvector (Optional)
58 *
59 * List of transition times before/after 32bit minimum seconds.
60 * Each time is represented by a pair of 32bit integer.
61 *
62 * - typeMap:bin (Optional)
63 *
64 * Array of bytes representing the mapping between each transition
65 * time (transPre32/trans/transPost32) and its corresponding offset
66 * data (typeOffsets).
67 *
68 * - finalRule:string (Optional)
69 *
70 * If a recurrent transition rule is applicable to a zone forever
71 * after the final transition time, finalRule represents the rule
72 * in Rules data.
73 *
74 * - finalRaw:int (Optional)
75 *
76 * When finalRule is available, finalRaw is required and specifies
77 * the raw (base) offset of the rule.
78 *
79 * - finalYear:int (Optional)
80 *
81 * When finalRule is available, finalYear is required and specifies
82 * the start year of the rule.
83 *
84 * - links:intvector (Optional)
85 *
86 * When this zone data is shared with other zones, links specifies
87 * all zones including the zone itself. Each zone is referenced by
88 * integer index.
89 *
90 * b. Link (int, length 1). A link zone is an int resource. The
91 * integer is the zone number of the target zone. The key of this
92 * resource is an alternate name for the target zone. This data
93 * is corresponding to Link data in the tz database.
94 *
95 *
96 * 2. Rules. These have keys corresponding to the Olson rule IDs,
97 * with an underscore prepended, e.g., "_EU". Each resource describes
98 * the behavior of the given rule using an intvector, containing the
99 * onset list, the cessation list, and the DST savings. The onset and
100 * cessation lists consist of the month, dowim, dow, time, and time
101 * mode. The end result is that the 11 integers describing the rule
102 * can be passed directly into the SimpleTimeZone 13-argument
103 * constructor (the other two arguments will be the raw offset, taken
104 * from the complex zone element 5, and the ID string, which is not
105 * used), with the times and the DST savings multiplied by 1000 to
106 * scale from seconds to milliseconds.
107 *
108 * 3. Regions. An array specifies mapping between zones and regions.
109 * Each item is either a 2-letter ISO country code or "001"
110 * (UN M.49 - World). This data is generated from "zone.tab"
111 * in the tz database.
112 */
113 class U_I18N_API OlsonTimeZone: public BasicTimeZone {
114 public:
115 /**
116 * Construct from a resource bundle.
117 * @param top the top-level zoneinfo resource bundle. This is used
118 * to lookup the rule that `res' may refer to, if there is one.
119 * @param res the resource bundle of the zone to be constructed
120 * @param tzid the time zone ID
121 * @param ec input-output error code
122 */
123 OlsonTimeZone(const UResourceBundle* top,
124 const UResourceBundle* res,
125 const UnicodeString& tzid,
126 UErrorCode& ec);
127
128 /**
129 * Copy constructor
130 */
131 OlsonTimeZone(const OlsonTimeZone& other);
132
133 /**
134 * Destructor
135 */
136 virtual ~OlsonTimeZone();
137
138 /**
139 * Assignment operator
140 */
141 OlsonTimeZone& operator=(const OlsonTimeZone& other);
142
143 /**
144 * Returns true if the two TimeZone objects are equal.
145 */
146 virtual UBool operator==(const TimeZone& other) const;
147
148 /**
149 * TimeZone API.
150 */
151 virtual TimeZone* clone() const;
152
153 /**
154 * TimeZone API.
155 */
156 static UClassID U_EXPORT2 getStaticClassID();
157
158 /**
159 * TimeZone API.
160 */
161 virtual UClassID getDynamicClassID() const;
162
163 /**
164 * TimeZone API. Do not call this; prefer getOffset(UDate,...).
165 */
166 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month,
167 int32_t day, uint8_t dayOfWeek,
168 int32_t millis, UErrorCode& ec) const;
169
170 /**
171 * TimeZone API. Do not call this; prefer getOffset(UDate,...).
172 */
173 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month,
174 int32_t day, uint8_t dayOfWeek,
175 int32_t millis, int32_t monthLength,
176 UErrorCode& ec) const;
177
178 /**
179 * TimeZone API.
180 */
181 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
182 int32_t& dstOffset, UErrorCode& ec) const;
183
184 /**
185 * BasicTimeZone API.
186 */
187 virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt,
188 int32_t& rawoff, int32_t& dstoff, UErrorCode& ec) /*const*/;
189
190 /**
191 * TimeZone API. This method has no effect since objects of this
192 * class are quasi-immutable (the base class allows the ID to be
193 * changed).
194 */
195 virtual void setRawOffset(int32_t offsetMillis);
196
197 /**
198 * TimeZone API. For a historical zone, the raw offset can change
199 * over time, so this API is not useful. In order to approximate
200 * expected behavior, this method returns the raw offset for the
201 * current moment in time.
202 */
203 virtual int32_t getRawOffset() const;
204
205 /**
206 * TimeZone API. For a historical zone, whether DST is used or
207 * not varies over time. In order to approximate expected
208 * behavior, this method returns TRUE if DST is observed at any
209 * point in the current year.
210 */
211 virtual UBool useDaylightTime() const;
212
213 /**
214 * TimeZone API.
215 */
216 virtual UBool inDaylightTime(UDate date, UErrorCode& ec) const;
217
218 /**
219 * TimeZone API.
220 */
221 virtual int32_t getDSTSavings() const;
222
223 /**
224 * TimeZone API. Also comare historic transitions.
225 */
226 virtual UBool hasSameRules(const TimeZone& other) const;
227
228 /**
229 * BasicTimeZone API.
230 * Gets the first time zone transition after the base time.
231 * @param base The base time.
232 * @param inclusive Whether the base time is inclusive or not.
233 * @param result Receives the first transition after the base time.
234 * @return TRUE if the transition is found.
235 */
236 virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) /*const*/;
237
238 /**
239 * BasicTimeZone API.
240 * Gets the most recent time zone transition before the base time.
241 * @param base The base time.
242 * @param inclusive Whether the base time is inclusive or not.
243 * @param result Receives the most recent transition before the base time.
244 * @return TRUE if the transition is found.
245 */
246 virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) /*const*/;
247
248 /**
249 * BasicTimeZone API.
250 * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
251 * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
252 * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value.
253 * @param status Receives error status code.
254 * @return The number of <code>TimeZoneRule</code>s representing time transitions.
255 */
256 virtual int32_t countTransitionRules(UErrorCode& status) /*const*/;
257
258 /**
259 * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
260 * which represent time transitions for this time zone. On successful return,
261 * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
262 * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
263 * instances up to the size specified by trscount. The results are referencing the
264 * rule instance held by this time zone instance. Therefore, after this time zone
265 * is destructed, they are no longer available.
266 * @param initial Receives the initial timezone rule
267 * @param trsrules Receives the timezone transition rules
268 * @param trscount On input, specify the size of the array 'transitions' receiving
269 * the timezone transition rules. On output, actual number of
270 * rules filled in the array will be set.
271 * @param status Receives error status code.
272 */
273 virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
274 const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) /*const*/;
275
276 /**
277 * Internal API returning the canonical ID of this zone.
278 * This ID won't be affected by setID().
279 */
280 const UChar *getCanonicalID() const;
281
282 private:
283 /**
284 * Default constructor. Creates a time zone with an empty ID and
285 * a fixed GMT offset of zero.
286 */
287 OlsonTimeZone();
288
289 private:
290
291 void constructEmpty();
292
293 void getHistoricalOffset(UDate date, UBool local,
294 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt,
295 int32_t& rawoff, int32_t& dstoff) const;
296
297 int16_t transitionCount() const;
298
299 int64_t transitionTimeInSeconds(int16_t transIdx) const;
300 double transitionTime(int16_t transIdx) const;
301
302 /*
303 * Following 3 methods return an offset at the given transition time index.
304 * When the index is negative, return the initial offset.
305 */
306 int32_t zoneOffsetAt(int16_t transIdx) const;
307 int32_t rawOffsetAt(int16_t transIdx) const;
308 int32_t dstOffsetAt(int16_t transIdx) const;
309
310 /*
311 * Following methods return the initial offset.
312 */
313 int32_t initialRawOffset() const;
314 int32_t initialDstOffset() const;
315
316 /**
317 * Number of transitions in each time range
318 */
319 int16_t transitionCountPre32;
320 int16_t transitionCount32;
321 int16_t transitionCountPost32;
322
323 /**
324 * Time of each transition in seconds from 1970 epoch before 32bit second range (<= 1900).
325 * Each transition in this range is represented by a pair of int32_t.
326 * Length is transitionCount int32_t's. NULL if no transitions in this range.
327 */
328 const int32_t *transitionTimesPre32; // alias into res; do not delete
329
330 /**
331 * Time of each transition in seconds from 1970 epoch in 32bit second range.
332 * Length is transitionCount int32_t's. NULL if no transitions in this range.
333 */
334 const int32_t *transitionTimes32; // alias into res; do not delete
335
336 /**
337 * Time of each transition in seconds from 1970 epoch after 32bit second range (>= 2038).
338 * Each transition in this range is represented by a pair of int32_t.
339 * Length is transitionCount int32_t's. NULL if no transitions in this range.
340 */
341 const int32_t *transitionTimesPost32; // alias into res; do not delete
342
343 /**
344 * Number of types, 1..255
345 */
346 int16_t typeCount;
347
348 /**
349 * Offset from GMT in seconds for each type.
350 * Length is typeCount int32_t's. At least one type (a pair of int32_t)
351 * is required.
352 */
353 const int32_t *typeOffsets; // alias into res; do not delete
354
355 /**
356 * Type description data, consisting of transitionCount uint8_t
357 * type indices (from 0..typeCount-1).
358 * Length is transitionCount int16_t's. NULL if no transitions.
359 */
360 const uint8_t *typeMapData; // alias into res; do not delete
361
362 /**
363 * A SimpleTimeZone that governs the behavior for date >= finalMillis.
364 */
365 SimpleTimeZone *finalZone; // owned, may be NULL
366
367 /**
368 * For date >= finalMillis, the finalZone will be used.
369 */
370 double finalStartMillis;
371
372 /**
373 * For year >= finalYear, the finalZone will be used.
374 */
375 int32_t finalStartYear;
376
377 /*
378 * Canonical (CLDR) ID of this zone
379 */
380 const UChar *canonicalID;
381
382 /* BasicTimeZone support */
383 void clearTransitionRules(void);
384 void deleteTransitionRules(void);
385 void initTransitionRules(UErrorCode& status);
386
387 InitialTimeZoneRule *initialRule;
388 TimeZoneTransition *firstTZTransition;
389 int16_t firstTZTransitionIdx;
390 TimeZoneTransition *firstFinalTZTransition;
391 TimeArrayTimeZoneRule **historicRules;
392 int16_t historicRuleCount;
393 SimpleTimeZone *finalZoneWithStartYear; // hack
394 UBool transitionRulesInitialized;
395 };
396
397 inline int16_t
transitionCount()398 OlsonTimeZone::transitionCount() const {
399 return transitionCountPre32 + transitionCount32 + transitionCountPost32;
400 }
401
402 inline double
transitionTime(int16_t transIdx)403 OlsonTimeZone::transitionTime(int16_t transIdx) const {
404 return (double)transitionTimeInSeconds(transIdx) * U_MILLIS_PER_SECOND;
405 }
406
407 inline int32_t
zoneOffsetAt(int16_t transIdx)408 OlsonTimeZone::zoneOffsetAt(int16_t transIdx) const {
409 int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
410 return typeOffsets[typeIdx] + typeOffsets[typeIdx + 1];
411 }
412
413 inline int32_t
rawOffsetAt(int16_t transIdx)414 OlsonTimeZone::rawOffsetAt(int16_t transIdx) const {
415 int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
416 return typeOffsets[typeIdx];
417 }
418
419 inline int32_t
dstOffsetAt(int16_t transIdx)420 OlsonTimeZone::dstOffsetAt(int16_t transIdx) const {
421 int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
422 return typeOffsets[typeIdx + 1];
423 }
424
425 inline int32_t
initialRawOffset()426 OlsonTimeZone::initialRawOffset() const {
427 return typeOffsets[0];
428 }
429
430 inline int32_t
initialDstOffset()431 OlsonTimeZone::initialDstOffset() const {
432 return typeOffsets[1];
433 }
434
435 inline const UChar*
getCanonicalID()436 OlsonTimeZone::getCanonicalID() const {
437 return canonicalID;
438 }
439
440
441 U_NAMESPACE_END
442
443 #endif // !UCONFIG_NO_FORMATTING
444 #endif // OLSONTZ_H
445
446 //eof
447