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