1 /*
2 **********************************************************************
3 * Copyright (c) 2003-2010, 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 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 ec input-output error code
121 */
122 OlsonTimeZone(const UResourceBundle* top,
123 const UResourceBundle* res, UErrorCode& ec);
124
125 /**
126 * Copy constructor
127 */
128 OlsonTimeZone(const OlsonTimeZone& other);
129
130 /**
131 * Destructor
132 */
133 virtual ~OlsonTimeZone();
134
135 /**
136 * Assignment operator
137 */
138 OlsonTimeZone& operator=(const OlsonTimeZone& other);
139
140 /**
141 * Returns true if the two TimeZone objects are equal.
142 */
143 virtual UBool operator==(const TimeZone& other) const;
144
145 /**
146 * TimeZone API.
147 */
148 virtual TimeZone* clone() const;
149
150 /**
151 * TimeZone API.
152 */
153 U_I18N_API static UClassID U_EXPORT2 getStaticClassID();
154
155 /**
156 * TimeZone API.
157 */
158 virtual UClassID getDynamicClassID() const;
159
160 /**
161 * TimeZone API. Do not call this; prefer getOffset(UDate,...).
162 */
163 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month,
164 int32_t day, uint8_t dayOfWeek,
165 int32_t millis, UErrorCode& ec) const;
166
167 /**
168 * TimeZone API. Do not call this; prefer getOffset(UDate,...).
169 */
170 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month,
171 int32_t day, uint8_t dayOfWeek,
172 int32_t millis, int32_t monthLength,
173 UErrorCode& ec) const;
174
175 /**
176 * TimeZone API.
177 */
178 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
179 int32_t& dstOffset, UErrorCode& ec) const;
180
181 /**
182 * BasicTimeZone API.
183 */
184 virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt,
185 int32_t& rawoff, int32_t& dstoff, UErrorCode& ec) /*const*/;
186
187 /**
188 * TimeZone API. This method has no effect since objects of this
189 * class are quasi-immutable (the base class allows the ID to be
190 * changed).
191 */
192 virtual void setRawOffset(int32_t offsetMillis);
193
194 /**
195 * TimeZone API. For a historical zone, the raw offset can change
196 * over time, so this API is not useful. In order to approximate
197 * expected behavior, this method returns the raw offset for the
198 * current moment in time.
199 */
200 virtual int32_t getRawOffset() const;
201
202 /**
203 * TimeZone API. For a historical zone, whether DST is used or
204 * not varies over time. In order to approximate expected
205 * behavior, this method returns TRUE if DST is observed at any
206 * point in the current year.
207 */
208 virtual UBool useDaylightTime() const;
209
210 /**
211 * TimeZone API.
212 */
213 virtual UBool inDaylightTime(UDate date, UErrorCode& ec) const;
214
215 /**
216 * TimeZone API.
217 */
218 virtual int32_t getDSTSavings() const;
219
220 /**
221 * TimeZone API. Also comare historic transitions.
222 */
223 virtual UBool hasSameRules(const TimeZone& other) const;
224
225 /**
226 * BasicTimeZone API.
227 * Gets the first time zone transition after the base time.
228 * @param base The base time.
229 * @param inclusive Whether the base time is inclusive or not.
230 * @param result Receives the first transition after the base time.
231 * @return TRUE if the transition is found.
232 */
233 virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) /*const*/;
234
235 /**
236 * BasicTimeZone API.
237 * Gets the most recent time zone transition before the base time.
238 * @param base The base time.
239 * @param inclusive Whether the base time is inclusive or not.
240 * @param result Receives the most recent transition before the base time.
241 * @return TRUE if the transition is found.
242 */
243 virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) /*const*/;
244
245 /**
246 * BasicTimeZone API.
247 * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
248 * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
249 * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value.
250 * @param status Receives error status code.
251 * @return The number of <code>TimeZoneRule</code>s representing time transitions.
252 */
253 virtual int32_t countTransitionRules(UErrorCode& status) /*const*/;
254
255 /**
256 * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
257 * which represent time transitions for this time zone. On successful return,
258 * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
259 * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
260 * instances up to the size specified by trscount. The results are referencing the
261 * rule instance held by this time zone instance. Therefore, after this time zone
262 * is destructed, they are no longer available.
263 * @param initial Receives the initial timezone rule
264 * @param trsrules Receives the timezone transition rules
265 * @param trscount On input, specify the size of the array 'transitions' receiving
266 * the timezone transition rules. On output, actual number of
267 * rules filled in the array will be set.
268 * @param status Receives error status code.
269 * @draft ICU 3.8
270 */
271 virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
272 const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) /*const*/;
273
274 private:
275 /**
276 * Default constructor. Creates a time zone with an empty ID and
277 * a fixed GMT offset of zero.
278 */
279 OlsonTimeZone();
280
281 private:
282
283 void constructEmpty();
284
285 void getHistoricalOffset(UDate date, UBool local,
286 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt,
287 int32_t& rawoff, int32_t& dstoff) const;
288
289 int16_t transitionCount() const;
290
291 int64_t transitionTimeInSeconds(int16_t transIdx) const;
292 double transitionTime(int16_t transIdx) const;
293
294 /*
295 * Following 3 methods return an offset at the given transition time index.
296 * When the index is negative, return the initial offset.
297 */
298 int32_t zoneOffsetAt(int16_t transIdx) const;
299 int32_t rawOffsetAt(int16_t transIdx) const;
300 int32_t dstOffsetAt(int16_t transIdx) const;
301
302 /*
303 * Following methods return the initial offset.
304 */
305 int32_t initialRawOffset() const;
306 int32_t initialDstOffset() const;
307
308 /**
309 * Number of transitions in each time range
310 */
311 int16_t transitionCountPre32;
312 int16_t transitionCount32;
313 int16_t transitionCountPost32;
314
315 /**
316 * Time of each transition in seconds from 1970 epoch before 32bit second range (<= 1900).
317 * Each transition in this range is represented by a pair of int32_t.
318 * Length is transitionCount int32_t's. NULL if no transitions in this range.
319 */
320 const int32_t *transitionTimesPre32; // alias into res; do not delete
321
322 /**
323 * Time of each transition in seconds from 1970 epoch in 32bit second range.
324 * Length is transitionCount int32_t's. NULL if no transitions in this range.
325 */
326 const int32_t *transitionTimes32; // alias into res; do not delete
327
328 /**
329 * Time of each transition in seconds from 1970 epoch after 32bit second range (>= 2038).
330 * Each transition in this range is represented by a pair of int32_t.
331 * Length is transitionCount int32_t's. NULL if no transitions in this range.
332 */
333 const int32_t *transitionTimesPost32; // alias into res; do not delete
334
335 /**
336 * Number of types, 1..255
337 */
338 int16_t typeCount;
339
340 /**
341 * Offset from GMT in seconds for each type.
342 * Length is typeCount int32_t's. At least one type (a pair of int32_t)
343 * is required.
344 */
345 const int32_t *typeOffsets; // alias into res; do not delete
346
347 /**
348 * Type description data, consisting of transitionCount uint8_t
349 * type indices (from 0..typeCount-1).
350 * Length is transitionCount int16_t's. NULL if no transitions.
351 */
352 const uint8_t *typeMapData; // alias into res; do not delete
353
354 /**
355 * A SimpleTimeZone that governs the behavior for date >= finalMillis.
356 */
357 SimpleTimeZone *finalZone; // owned, may be NULL
358
359 /**
360 * For date >= finalMillis, the finalZone will be used.
361 */
362 double finalStartMillis;
363
364 /**
365 * For year >= finalYear, the finalZone will be used.
366 */
367 int32_t finalStartYear;
368
369 /* BasicTimeZone support */
370 void clearTransitionRules(void);
371 void deleteTransitionRules(void);
372 void initTransitionRules(UErrorCode& status);
373
374 InitialTimeZoneRule *initialRule;
375 TimeZoneTransition *firstTZTransition;
376 int16_t firstTZTransitionIdx;
377 TimeZoneTransition *firstFinalTZTransition;
378 TimeArrayTimeZoneRule **historicRules;
379 int16_t historicRuleCount;
380 SimpleTimeZone *finalZoneWithStartYear; // hack
381 UBool transitionRulesInitialized;
382 };
383
384 inline int16_t
transitionCount()385 OlsonTimeZone::transitionCount() const {
386 return transitionCountPre32 + transitionCount32 + transitionCountPost32;
387 }
388
389 inline double
transitionTime(int16_t transIdx)390 OlsonTimeZone::transitionTime(int16_t transIdx) const {
391 return (double)transitionTimeInSeconds(transIdx) * U_MILLIS_PER_SECOND;
392 }
393
394 inline int32_t
zoneOffsetAt(int16_t transIdx)395 OlsonTimeZone::zoneOffsetAt(int16_t transIdx) const {
396 int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
397 return typeOffsets[typeIdx] + typeOffsets[typeIdx + 1];
398 }
399
400 inline int32_t
rawOffsetAt(int16_t transIdx)401 OlsonTimeZone::rawOffsetAt(int16_t transIdx) const {
402 int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
403 return typeOffsets[typeIdx];
404 }
405
406 inline int32_t
dstOffsetAt(int16_t transIdx)407 OlsonTimeZone::dstOffsetAt(int16_t transIdx) const {
408 int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
409 return typeOffsets[typeIdx + 1];
410 }
411
412 inline int32_t
initialRawOffset()413 OlsonTimeZone::initialRawOffset() const {
414 return typeOffsets[0];
415 }
416
417 inline int32_t
initialDstOffset()418 OlsonTimeZone::initialDstOffset() const {
419 return typeOffsets[1];
420 }
421
422 U_NAMESPACE_END
423
424 #endif // !UCONFIG_NO_FORMATTING
425 #endif // OLSONTZ_H
426
427 //eof
428