icuSources/i18n/olsontz.h

   1 /*
   2 **********************************************************************
   3 * Copyright (c) 2003-2007, 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 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 several formats, which are differentiated
  41  * based on length.
  42  *
  43  *  a. Alias (int, length 1).  An alias zone is an int resource.  The
  44  *  integer is the zone number of the target zone.  The key of this
  45  *  resource is an alternate name for the target zone.  Aliases
  46  *  represent Olson links and ICU compatibility IDs.
  47  *
  48  *  b. Simple zone (array, length 3).  The three subelements are:
  49  *
  50  *   i. An intvector of transitions.  These are given in epoch
  51  *   seconds.  This may be an empty invector (length 0).  If the
  52  *   transtions list is empty, then the zone's behavior is fixed and
  53  *   given by the offset list, which will contain exactly one pair.
  54  *   Otherwise each transtion indicates a time after which (inclusive)
  55  *   the associated offset pair is in effect.
  56  *
  57  *   ii. An intvector of offsets.  These are in pairs of raw offset /
  58  *   DST offset, in units of seconds.  There will be at least one pair
  59  *   (length >= 2 && length % 2 == 0).
  60  *
  61  *   iii. A binary resource.  This is of the same length as the
  62  *   transitions vector, so length may be zero.  Each unsigned byte
  63  *   corresponds to one transition, and has a value of 0..n-1, where n
  64  *   is the number of pairs in the offset vector.  This forms a map
  65  *   between transitions and offset pairs.
  66  *
  67  *  c. Simple zone with aliases (array, length 4).  This is like a
  68  *  simple zone, but also contains a fourth element:
  69  *
  70  *   iv. An intvector of aliases.  This list includes this zone
  71  *   itself, and lists all aliases of this zone.
  72  *
  73  *  d. Complex zone (array, length 5).  This is like a simple zone,
  74  *  but contains two more elements:
  75  *
  76  *   iv. A string, giving the name of a rule.  This is the "final
  77  *   rule", which governs the zone's behavior beginning in the "final
  78  *   year".  The rule ID is given without leading underscore, e.g.,
  79  *   "EU".
  80  *
  81  *   v. An intvector of length 2, containing the raw offset for the
  82  *   final rule (in seconds), and the final year.  The final rule
  83  *   takes effect for years >= the final year.
  84  *
  85  *  e. Complex zone with aliases (array, length 6).  This is like a
  86  *  complex zone, but also contains a sixth element:
  87  *
  88  *   vi. An intvector of aliases.  This list includes this zone
  89  *   itself, and lists all aliases of this zone.
  90  *
  91  * 2. Rules.  These have keys corresponding to the Olson rule IDs,
  92  * with an underscore prepended, e.g., "_EU".  Each resource describes
  93  * the behavior of the given rule using an intvector, containing the
  94  * onset list, the cessation list, and the DST savings.  The onset and
  95  * cessation lists consist of the month, dowim, dow, time, and time
  96  * mode.  The end result is that the 11 integers describing the rule
  97  * can be passed directly into the SimpleTimeZone 13-argument
  98  * constructor (the other two arguments will be the raw offset, taken
  99  * from the complex zone element 5, and the ID string, which is not
 100  * used), with the times and the DST savings multiplied by 1000 to
 101  * scale from seconds to milliseconds.
 102  *
 103  * 3. Countries.  These have keys corresponding to the 2-letter ISO
 104  * country codes, with a percent sign prepended, e.g., "%US".  Each
 105  * resource is an intvector listing the zones associated with the
 106  * given country.  The special entry "%" corresponds to "no country",
 107  * that is, the category of zones assigned to no country in the Olson
 108  * DB.
 109  *
 110  * 4. Metadata.  Metadata is stored under the key "_".  It is an
 111  * intvector of length three containing the number of zones resources,
 112  * rule resources, and country resources.  For the purposes of this
 113  * count, the metadata entry itself is considered a rule resource,
 114  * since its key begins with an underscore.
 115  */
 116 class 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 ec input-output error code
 124      */
 125     OlsonTimeZone(const UResourceBundle* top,
 126                   const UResourceBundle* res, 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     U_I18N_API 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      * @draft ICU 3.8
 273      */
 274     virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
 275         const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) /*const*/;
 276
 277 private:
 278     /**
 279      * Default constructor.  Creates a time zone with an empty ID and
 280      * a fixed GMT offset of zero.
 281      */
 282     OlsonTimeZone();
 283
 284 private:
 285
 286     void constructEmpty();
 287
 288     void getHistoricalOffset(UDate date, UBool local,
 289         int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt,
 290         int32_t& rawoff, int32_t& dstoff) const;
 291
 292     int32_t zoneOffset(int16_t index) const;
 293     int32_t rawOffset(int16_t index) const;
 294     int32_t dstOffset(int16_t index) const;
 295
 296     /**
 297      * Number of transitions, 0..~370
 298      */
 299     int16_t transitionCount;
 300
 301     /**
 302      * Number of types, 1..255
 303      */
 304     int16_t typeCount;
 305
 306     /**
 307      * Time of each transition in seconds from 1970 epoch.
 308      * Length is transitionCount int32_t's.
 309      */
 310     const int32_t *transitionTimes; // alias into res; do not delete
 311
 312     /**
 313      * Offset from GMT in seconds for each type.
 314      * Length is typeCount int32_t's.
 315      */
 316     const int32_t *typeOffsets; // alias into res; do not delete
 317
 318     /**
 319      * Type description data, consisting of transitionCount uint8_t
 320      * type indices (from 0..typeCount-1).
 321      * Length is transitionCount int8_t's.
 322      */
 323     const uint8_t *typeData; // alias into res; do not delete
 324
 325     /**
 326      * The last year for which the transitions data are to be used
 327      * rather than the finalZone.  If there is no finalZone, then this
 328      * is set to INT32_MAX.  NOTE: This corresponds to the year _before_
 329      * the one indicated by finalMillis.
 330      */
 331     int32_t finalYear;
 332
 333     /**
 334      * The millis for the start of the first year for which finalZone
 335      * is to be used, or DBL_MAX if finalZone is 0.  NOTE: This is
 336      * 0:00 GMT Jan 1, <finalYear + 1> (not <finalMillis>).
 337      */
 338     double finalMillis;
 339
 340     /**
 341      * A SimpleTimeZone that governs the behavior for years > finalYear.
 342      * If and only if finalYear == INT32_MAX then finalZone == 0.
 343      */
 344     SimpleTimeZone *finalZone; // owned, may be NULL
 345
 346     /* BasicTimeZone support */
 347     void clearTransitionRules(void);
 348     void deleteTransitionRules(void);
 349     void initTransitionRules(UErrorCode& status);
 350
 351     InitialTimeZoneRule *initialRule;
 352     TimeZoneTransition  *firstTZTransition;
 353     int16_t             firstTZTransitionIdx;
 354     TimeZoneTransition  *firstFinalTZTransition;
 355     TimeArrayTimeZoneRule   **historicRules;
 356     int16_t             historicRuleCount;
 357     SimpleTimeZone      *finalZoneWithStartYear; // hack
 358     UBool               transitionRulesInitialized;
 359 };
 360
 361 inline int32_t
 362 OlsonTimeZone::zoneOffset(int16_t index) const {
 363     index <<= 1;
 364     return typeOffsets[index] + typeOffsets[index+1];
 365 }
 366
 367 inline int32_t
 368 OlsonTimeZone::rawOffset(int16_t index) const {
 369     return typeOffsets[(uint32_t)(index << 1)];
 370 }
 371
 372 inline int32_t
 373 OlsonTimeZone::dstOffset(int16_t index) const {
 374     return typeOffsets[(uint32_t)((index << 1) + 1)];
 375 }
 376
 377 U_NAMESPACE_END
 378
 379 #endif // !UCONFIG_NO_FORMATTING
 380 #endif // OLSONTZ_H
 381
 382 //eof