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 398 OlsonTimeZone::transitionCount() const { 399 return transitionCountPre32 + transitionCount32 + transitionCountPost32; 400 } 401 402 inline double 403 OlsonTimeZone::transitionTime(int16_t transIdx) const { 404 return (double)transitionTimeInSeconds(transIdx) * U_MILLIS_PER_SECOND; 405 } 406 407 inline int32_t 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 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 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 426 OlsonTimeZone::initialRawOffset() const { 427 return typeOffsets[0]; 428 } 429 430 inline int32_t 431 OlsonTimeZone::initialDstOffset() const { 432 return typeOffsets[1]; 433 } 434 435 inline const UChar* 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
