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