icuSources/i18n/olsontz.h

   1 /*
   2 **********************************************************************
   3 * Copyright (c) 2003-2013, 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 checkTransitionRules(UErrorCode& status) const;
 386     void initTransitionRules(UErrorCode& status);
 387
 388     InitialTimeZoneRule *initialRule;
 389     TimeZoneTransition  *firstTZTransition;
 390     int16_t             firstTZTransitionIdx;
 391     TimeZoneTransition  *firstFinalTZTransition;
 392     TimeArrayTimeZoneRule   **historicRules;
 393     int16_t             historicRuleCount;
 394     SimpleTimeZone      *finalZoneWithStartYear; // hack
 395     UBool               transitionRulesInitialized;
 396 };
 397
 398 inline int16_t
 399 OlsonTimeZone::transitionCount() const {
 400     return transitionCountPre32 + transitionCount32 + transitionCountPost32;
 401 }
 402
 403 inline double
 404 OlsonTimeZone::transitionTime(int16_t transIdx) const {
 405     return (double)transitionTimeInSeconds(transIdx) * U_MILLIS_PER_SECOND;
 406 }
 407
 408 inline int32_t
 409 OlsonTimeZone::zoneOffsetAt(int16_t transIdx) const {
 410     int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
 411     return typeOffsets[typeIdx] + typeOffsets[typeIdx + 1];
 412 }
 413
 414 inline int32_t
 415 OlsonTimeZone::rawOffsetAt(int16_t transIdx) const {
 416     int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
 417     return typeOffsets[typeIdx];
 418 }
 419
 420 inline int32_t
 421 OlsonTimeZone::dstOffsetAt(int16_t transIdx) const {
 422     int16_t typeIdx = (transIdx >= 0 ? typeMapData[transIdx] : 0) << 1;
 423     return typeOffsets[typeIdx + 1];
 424 }
 425
 426 inline int32_t
 427 OlsonTimeZone::initialRawOffset() const {
 428     return typeOffsets[0];
 429 }
 430
 431 inline int32_t
 432 OlsonTimeZone::initialDstOffset() const {
 433     return typeOffsets[1];
 434 }
 435
 436 inline const UChar*
 437 OlsonTimeZone::getCanonicalID() const {
 438     return canonicalID;
 439 }
 440
 441
 442 U_NAMESPACE_END
 443
 444 #endif // !UCONFIG_NO_FORMATTING
 445 #endif // OLSONTZ_H
 446
 447 //eof