icuSources/i18n/unicode/timezone.h

   1 /*
   2 * Copyright (C) {1997-2005}, International Business Machines Corporation and others. All Rights Reserved.
   3 ********************************************************************************
   4 *
   5 * File TIMEZONE.H
   6 *
   7 * Modification History:
   8 *
   9 *   Date        Name        Description
  10 *   04/21/97    aliu        Overhauled header.
  11 *   07/09/97    helena      Changed createInstance to createDefault.
  12 *   08/06/97    aliu        Removed dependency on internal header for Hashtable.
  13 *   08/10/98    stephen        Changed getDisplayName() API conventions to match
  14 *   08/19/98    stephen        Changed createTimeZone() to never return 0
  15 *   09/02/98    stephen        Sync to JDK 1.2 8/31
  16 *                            - Added getOffset(... monthlen ...)
  17 *                            - Added hasSameRules()
  18 *   09/15/98    stephen        Added getStaticClassID
  19 *   12/03/99    aliu        Moved data out of static table into icudata.dll.
  20 *                           Hashtable replaced by new static data structures.
  21 *   12/14/99    aliu        Made GMT public.
  22 *   08/15/01    grhoten     Made GMT private and added the getGMT() function
  23 ********************************************************************************
  24 */
  25
  26 #ifndef TIMEZONE_H
  27 #define TIMEZONE_H
  28
  29 #include "unicode/utypes.h"
  30
  31 /**
  32  * \file
  33  * \brief C++ API: TimeZone object
  34  */
  35
  36 #if !UCONFIG_NO_FORMATTING
  37
  38 #include "unicode/uobject.h"
  39 #include "unicode/unistr.h"
  40 #include "unicode/ures.h"
  41
  42 U_NAMESPACE_BEGIN
  43
  44 class StringEnumeration;
  45
  46 /**
  47  *
  48  * <code>TimeZone</code> represents a time zone offset, and also figures out daylight
  49  * savings.
  50  *
  51  * <p>
  52  * Typically, you get a <code>TimeZone</code> using <code>createDefault</code>
  53  * which creates a <code>TimeZone</code> based on the time zone where the program
  54  * is running. For example, for a program running in Japan, <code>createDefault</code>
  55  * creates a <code>TimeZone</code> object based on Japanese Standard Time.
  56  *
  57  * <p>
  58  * You can also get a <code>TimeZone</code> using <code>createTimeZone</code> along
  59  * with a time zone ID. For instance, the time zone ID for the Pacific
  60  * Standard Time zone is "PST". So, you can get a PST <code>TimeZone</code> object
  61  * with:
  62  * \htmlonly<blockquote>\endhtmlonly
  63  * <pre>
  64  * TimeZone *tz = TimeZone::createTimeZone("PST");
  65  * </pre>
  66  * \htmlonly</blockquote>\endhtmlonly
  67  * You can use <code>getAvailableIDs</code> method to iterate through
  68  * all the supported time zone IDs. You can then choose a
  69  * supported ID to get a <code>TimeZone</code>.
  70  * If the time zone you want is not represented by one of the
  71  * supported IDs, then you can create a custom time zone ID with
  72  * the following syntax:
  73  *
  74  * \htmlonly<blockquote>\endhtmlonly
  75  * <pre>
  76  * GMT[+|-]hh[[:]mm]
  77  * </pre>
  78  * \htmlonly</blockquote>\endhtmlonly
  79  *
  80  * For example, you might specify GMT+14:00 as a custom
  81  * time zone ID.  The <code>TimeZone</code> that is returned
  82  * when you specify a custom time zone ID does not include
  83  * daylight savings time.
  84  *
  85  * TimeZone is an abstract class representing a time zone.  A TimeZone is needed for
  86  * Calendar to produce local time for a particular time zone.  A TimeZone comprises
  87  * three basic pieces of information:
  88  * <ul>
  89  *    <li>A time zone offset; that, is the number of milliseconds to add or subtract
  90  *      from a time expressed in terms of GMT to convert it to the same time in that
  91  *      time zone (without taking daylight savings time into account).</li>
  92  *    <li>Logic necessary to take daylight savings time into account if daylight savings
  93  *      time is observed in that time zone (e.g., the days and hours on which daylight
  94  *      savings time begins and ends).</li>
  95  *    <li>An ID.  This is a text string that uniquely identifies the time zone.</li>
  96  * </ul>
  97  *
  98  * (Only the ID is actually implemented in TimeZone; subclasses of TimeZone may handle
  99  * daylight savings time and GMT offset in different ways.  Currently we only have one
 100  * TimeZone subclass: SimpleTimeZone.)
 101  * <P>
 102  * The TimeZone class contains a static list containing a TimeZone object for every
 103  * combination of GMT offset and daylight-savings time rules currently in use in the
 104  * world, each with a unique ID.  Each ID consists of a region (usually a continent or
 105  * ocean) and a city in that region, separated by a slash, (for example, Pacific
 106  * Standard Time is "America/Los_Angeles.")  Because older versions of this class used
 107  * three- or four-letter abbreviations instead, there is also a table that maps the older
 108  * abbreviations to the newer ones (for example, "PST" maps to "America/LosAngeles").
 109  * Anywhere the API requires an ID, you can use either form.
 110  * <P>
 111  * To create a new TimeZone, you call the factory function TimeZone::createTimeZone()
 112  * and pass it a time zone ID.  You can use the createEnumeration() function to
 113  * obtain a list of all the time zone IDs recognized by createTimeZone().
 114  * <P>
 115  * You can also use TimeZone::createDefault() to create a TimeZone.  This function uses
 116  * platform-specific APIs to produce a TimeZone for the time zone corresponding to
 117  * the client's computer's physical location.  For example, if you're in Japan (assuming
 118  * your machine is set up correctly), TimeZone::createDefault() will return a TimeZone
 119  * for Japanese Standard Time ("Asia/Tokyo").
 120  */
 121 class U_I18N_API TimeZone : public UObject {
 122 public:
 123     /**
 124      * @stable ICU 2.0
 125      */
 126     virtual ~TimeZone();
 127
 128     /**
 129      * The GMT time zone has a raw offset of zero and does not use daylight
 130      * savings time. This is a commonly used time zone.
 131      * @return the GMT time zone.
 132      * @stable ICU 2.0
 133      */
 134     static const TimeZone* U_EXPORT2 getGMT(void);
 135
 136     /**
 137      * Creates a <code>TimeZone</code> for the given ID.
 138      * @param ID the ID for a <code>TimeZone</code>, either an abbreviation such as
 139      * "PST", a full name such as "America/Los_Angeles", or a custom ID
 140      * such as "GMT-8:00".
 141      * @return the specified <code>TimeZone</code>, or the GMT zone if the given ID
 142      * cannot be understood.  Return result guaranteed to be non-null.  If you
 143      * require that the specific zone asked for be returned, check the ID of the
 144      * return result.
 145      * @stable ICU 2.0
 146      */
 147     static TimeZone* U_EXPORT2 createTimeZone(const UnicodeString& ID);
 148
 149     /**
 150      * Returns an enumeration over all recognized time zone IDs. (i.e.,
 151      * all strings that createTimeZone() accepts)
 152      *
 153      * @return an enumeration object, owned by the caller.
 154      * @stable ICU 2.4
 155      */
 156     static StringEnumeration* U_EXPORT2 createEnumeration();
 157
 158     /**
 159      * Returns an enumeration over time zone IDs with a given raw
 160      * offset from GMT.  There may be several times zones with the
 161      * same GMT offset that differ in the way they handle daylight
 162      * savings time.  For example, the state of Arizona doesn't
 163      * observe daylight savings time.  If you ask for the time zone
 164      * IDs corresponding to GMT-7:00, you'll get back an enumeration
 165      * over two time zone IDs: "America/Denver," which corresponds to
 166      * Mountain Standard Time in the winter and Mountain Daylight Time
 167      * in the summer, and "America/Phoenix", which corresponds to
 168      * Mountain Standard Time year-round, even in the summer.
 169      *
 170      * @param rawOffset an offset from GMT in milliseconds, ignoring
 171      * the effect of daylight savings time, if any
 172      * @return an enumeration object, owned by the caller
 173      * @stable ICU 2.4
 174      */
 175     static StringEnumeration* U_EXPORT2 createEnumeration(int32_t rawOffset);
 176
 177     /**
 178      * Returns an enumeration over time zone IDs associated with the
 179      * given country.  Some zones are affiliated with no country
 180      * (e.g., "UTC"); these may also be retrieved, as a group.
 181      *
 182      * @param country The ISO 3166 two-letter country code, or NULL to
 183      * retrieve zones not affiliated with any country.
 184      * @return an enumeration object, owned by the caller
 185      * @stable ICU 2.4
 186      */
 187     static StringEnumeration* U_EXPORT2 createEnumeration(const char* country);
 188
 189 #ifdef U_USE_TIMEZONE_OBSOLETE_2_8
 190     /**
 191      * Returns a list of time zone IDs, one for each time zone with a given GMT offset.
 192      * The return value is a list because there may be several times zones with the same
 193      * GMT offset that differ in the way they handle daylight savings time.  For example,
 194      * the state of Arizona doesn't observe Daylight Savings time.  So if you ask for
 195      * the time zone IDs corresponding to GMT-7:00, you'll get back two time zone IDs:
 196      * "America/Denver," which corresponds to Mountain Standard Time in the winter and
 197      * Mountain Daylight Time in the summer, and "America/Phoenix", which corresponds to
 198      * Mountain Standard Time year-round, even in the summer.
 199      * <P>
 200      * The caller owns the list that is returned, but does not own the strings contained
 201      * in that list.  Delete the array with uprv_free(), but DON'T delete the elements in the array.
 202      *
 203      * <p>NOTE: uprv_free() is declared in the private header source/common/cmemory.h.
 204      *
 205      * @param rawOffset  An offset from GMT in milliseconds.
 206      * @param numIDs     Receives the number of items in the array that is returned.
 207      * @return           An array of UnicodeString pointers, where each UnicodeString is
 208      *                   a time zone ID for a time zone with the given GMT offset.  If
 209      *                   there is no timezone that matches the GMT offset
 210      *                   specified, NULL is returned.
 211      * @obsolete ICU 2.8.  Use createEnumeration(int32_t) instead since this API will be removed in that release.
 212      */
 213     static const UnicodeString** createAvailableIDs(int32_t rawOffset, int32_t& numIDs);
 214
 215     /**
 216      * Returns a list of time zone IDs associated with the given
 217      * country.  Some zones are affiliated with no country (e.g.,
 218      * "UTC"); these may also be retrieved, as a group.
 219      *
 220      * <P>The caller owns the list that is returned, but does not own
 221      * the strings contained in that list.  Delete the array with uprv_free(), but
 222      * <b>DON'T</b> delete the elements in the array.
 223      *
 224      * <p>NOTE: uprv_free() is declared in the private header source/common/cmemory.h.
 225      *
 226      * @param country The ISO 3166 two-letter country code, or NULL to
 227      * retrieve zones not affiliated with any country.
 228      * @param numIDs Receives the number of items in the array that is
 229      * returned.
 230      * @return An array of UnicodeString pointers, where each
 231      * UnicodeString is a time zone ID for a time zone with the given
 232      * country.  If there is no timezone that matches the country
 233      * specified, NULL is returned.
 234      * @obsolete ICU 2.8.  Use createEnumeration(const char*) instead since this API will be removed in that release.
 235      */
 236     static const UnicodeString** createAvailableIDs(const char* country,
 237                                                           int32_t& numIDs);
 238
 239     /**
 240      * Returns a list of all time zone IDs supported by the TimeZone class (i.e., all
 241      * IDs that it's legal to pass to createTimeZone()).  The caller owns the list that
 242      * is returned, but does not own the strings contained in that list.  Delete the array with uprv_free(),
 243      * but DON'T delete the elements in the array.
 244      *
 245      * <p>NOTE: uprv_free() is declared in the private header source/common/cmemory.h.
 246      *
 247      * @param numIDs  Receives the number of zone IDs returned.
 248      * @return        An array of UnicodeString pointers, where each is a time zone ID
 249      *                supported by the TimeZone class.
 250      * @obsolete ICU 2.8.  Use createEnumeration(void) instead since this API will be removed in that release.
 251      */
 252     static const UnicodeString** createAvailableIDs(int32_t& numIDs);
 253 #endif
 254
 255     /**
 256      * Returns the number of IDs in the equivalency group that
 257      * includes the given ID.  An equivalency group contains zones
 258      * that have the same GMT offset and rules.
 259      *
 260      * <p>The returned count includes the given ID; it is always >= 1.
 261      * The given ID must be a system time zone.  If it is not, returns
 262      * zero.
 263      * @param id a system time zone ID
 264      * @return the number of zones in the equivalency group containing
 265      * 'id', or zero if 'id' is not a valid system ID
 266      * @see #getEquivalentID
 267      * @stable ICU 2.0
 268      */
 269     static int32_t U_EXPORT2 countEquivalentIDs(const UnicodeString& id);
 270
 271     /**
 272      * Returns an ID in the equivalency group that
 273      * includes the given ID.  An equivalency group contains zones
 274      * that have the same GMT offset and rules.
 275      *
 276      * <p>The given index must be in the range 0..n-1, where n is the
 277      * value returned by <code>countEquivalentIDs(id)</code>.  For
 278      * some value of 'index', the returned value will be equal to the
 279      * given id.  If the given id is not a valid system time zone, or
 280      * if 'index' is out of range, then returns an empty string.
 281      * @param id a system time zone ID
 282      * @param index a value from 0 to n-1, where n is the value
 283      * returned by <code>countEquivalentIDs(id)</code>
 284      * @return the ID of the index-th zone in the equivalency group
 285      * containing 'id', or an empty string if 'id' is not a valid
 286      * system ID or 'index' is out of range
 287      * @see #countEquivalentIDs
 288      * @stable ICU 2.0
 289      */
 290     static const UnicodeString U_EXPORT2 getEquivalentID(const UnicodeString& id,
 291                                                int32_t index);
 292
 293     /**
 294      * Creates a new copy of the default TimeZone for this host. Unless the default time
 295      * zone has already been set using adoptDefault() or setDefault(), the default is
 296      * determined by querying the system using methods in TPlatformUtilities. If the
 297      * system routines fail, or if they specify a TimeZone or TimeZone offset which is not
 298      * recognized, the TimeZone indicated by the ID kLastResortID is instantiated
 299      * and made the default.
 300      *
 301      * @return   A default TimeZone. Clients are responsible for deleting the time zone
 302      *           object returned.
 303      * @stable ICU 2.0
 304      */
 305     static TimeZone* U_EXPORT2 createDefault(void);
 306
 307     /**
 308      * Sets the default time zone (i.e., what's returned by getDefault()) to be the
 309      * specified time zone.  If NULL is specified for the time zone, the default time
 310      * zone is set to the default host time zone.  This call adopts the TimeZone object
 311      * passed in; the clent is no longer responsible for deleting it.
 312      *
 313      * @param zone  A pointer to the new TimeZone object to use as the default.
 314      * @stable ICU 2.0
 315      */
 316     static void U_EXPORT2 adoptDefault(TimeZone* zone);
 317
 318     /**
 319      * Same as adoptDefault(), except that the TimeZone object passed in is NOT adopted;
 320      * the caller remains responsible for deleting it.
 321      *
 322      * @param zone  The given timezone.
 323      * @system
 324      */
 325     static void U_EXPORT2 setDefault(const TimeZone& zone);
 326
 327     /**
 328      * Returns true if the two TimeZones are equal.  (The TimeZone version only compares
 329      * IDs, but subclasses are expected to also compare the fields they add.)
 330      *
 331      * @param that  The TimeZone object to be compared with.
 332      * @return      True if the given TimeZone is equal to this TimeZone; false
 333      *              otherwise.
 334      * @stable ICU 2.0
 335      */
 336     virtual UBool operator==(const TimeZone& that) const;
 337
 338     /**
 339      * Returns true if the two TimeZones are NOT equal; that is, if operator==() returns
 340      * false.
 341      *
 342      * @param that  The TimeZone object to be compared with.
 343      * @return      True if the given TimeZone is not equal to this TimeZone; false
 344      *              otherwise.
 345      * @stable ICU 2.0
 346      */
 347     UBool operator!=(const TimeZone& that) const {return !operator==(that);}
 348
 349     /**
 350      * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
 351      * to GMT to get local time in this time zone, taking daylight savings time into
 352      * account) as of a particular reference date.  The reference date is used to determine
 353      * whether daylight savings time is in effect and needs to be figured into the offset
 354      * that is returned (in other words, what is the adjusted GMT offset in this time zone
 355      * at this particular date and time?).  For the time zones produced by createTimeZone(),
 356      * the reference data is specified according to the Gregorian calendar, and the date
 357      * and time fields are local standard time.
 358      *
 359      * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
 360      * which returns both the raw and the DST offset for a given time. This method
 361      * is retained only for backward compatibility.
 362      *
 363      * @param era        The reference date's era
 364      * @param year       The reference date's year
 365      * @param month      The reference date's month (0-based; 0 is January)
 366      * @param day        The reference date's day-in-month (1-based)
 367      * @param dayOfWeek  The reference date's day-of-week (1-based; 1 is Sunday)
 368      * @param millis     The reference date's milliseconds in day, local standard time
 369      * @param status     Output param to filled in with a success or an error.
 370      * @return           The offset in milliseconds to add to GMT to get local time.
 371      * @stable ICU 2.0
 372      */
 373     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
 374                               uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const = 0;
 375
 376     /**
 377      * Gets the time zone offset, for current date, modified in case of
 378      * daylight savings. This is the offset to add *to* UTC to get local time.
 379      *
 380      * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
 381      * which returns both the raw and the DST offset for a given time. This method
 382      * is retained only for backward compatibility.
 383      *
 384      * @param era the era of the given date.
 385      * @param year the year in the given date.
 386      * @param month the month in the given date.
 387      * Month is 0-based. e.g., 0 for January.
 388      * @param day the day-in-month of the given date.
 389      * @param dayOfWeek the day-of-week of the given date.
 390      * @param milliseconds the millis in day in <em>standard</em> local time.
 391      * @param monthLength the length of the given month in days.
 392      * @param status     Output param to filled in with a success or an error.
 393      * @return the offset to add *to* GMT to get local time.
 394      * @stable ICU 2.0
 395      */
 396     virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
 397                            uint8_t dayOfWeek, int32_t milliseconds,
 398                            int32_t monthLength, UErrorCode& status) const = 0;
 399
 400     /**
 401      * Returns the time zone raw and GMT offset for the given moment
 402      * in time.  Upon return, local-millis = GMT-millis + rawOffset +
 403      * dstOffset.  All computations are performed in the proleptic
 404      * Gregorian calendar.  The default implementation in the TimeZone
 405      * class delegates to the 8-argument getOffset().
 406      *
 407      * @param date moment in time for which to return offsets, in
 408      * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
 409      * time or local wall time, depending on `local'.
 410      * @param local if true, `date' is local wall time; otherwise it
 411      * is in GMT time.
 412      * @param rawOffset output parameter to receive the raw offset, that
 413      * is, the offset not including DST adjustments
 414      * @param dstOffset output parameter to receive the DST offset,
 415      * that is, the offset to be added to `rawOffset' to obtain the
 416      * total offset between local and GMT time. If DST is not in
 417      * effect, this value is zero; otherwise it is a positive value,
 418      * typically one hour.
 419      * @param ec input-output error code
 420      *
 421      * @stable ICU 2.8
 422      */
 423     virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
 424                            int32_t& dstOffset, UErrorCode& ec) const;
 425
 426     /**
 427      * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
 428      * to GMT to get local time, before taking daylight savings time into account).
 429      *
 430      * @param offsetMillis  The new raw GMT offset for this time zone.
 431      * @stable ICU 2.0
 432      */
 433     virtual void setRawOffset(int32_t offsetMillis) = 0;
 434
 435     /**
 436      * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
 437      * to GMT to get local time, before taking daylight savings time into account).
 438      *
 439      * @return   The TimeZone's raw GMT offset.
 440      * @stable ICU 2.0
 441      */
 442     virtual int32_t getRawOffset(void) const = 0;
 443
 444     /**
 445      * Fills in "ID" with the TimeZone's ID.
 446      *
 447      * @param ID  Receives this TimeZone's ID.
 448      * @return    A reference to 'ID'
 449      * @stable ICU 2.0
 450      */
 451     UnicodeString& getID(UnicodeString& ID) const;
 452
 453     /**
 454      * Sets the TimeZone's ID to the specified value.  This doesn't affect any other
 455      * fields (for example, if you say<
 456      * blockquote><pre>
 457      * .     TimeZone* foo = TimeZone::createTimeZone("America/New_York");
 458      * .     foo.setID("America/Los_Angeles");
 459      * </pre>\htmlonly</blockquote>\endhtmlonly
 460      * the time zone's GMT offset and daylight-savings rules don't change to those for
 461      * Los Angeles.  They're still those for New York.  Only the ID has changed.)
 462      *
 463      * @param ID  The new timezone ID.
 464      * @stable ICU 2.0
 465      */
 466     void setID(const UnicodeString& ID);
 467
 468     /**
 469      * Enum for use with getDisplayName
 470      * @stable ICU 2.4
 471      */
 472     enum EDisplayType {
 473         /**
 474          * Selector for short display name
 475          * @stable ICU 2.4
 476          */
 477         SHORT = 1,
 478         /**
 479          * Selector for long display name
 480          * @stable ICU 2.4
 481          */
 482         LONG
 483     };
 484
 485     /**
 486      * Returns a name of this time zone suitable for presentation to the user
 487      * in the default locale.
 488      * This method returns the long name, not including daylight savings.
 489      * If the display name is not available for the locale,
 490      * then this method returns a string in the format
 491      * <code>GMT[+-]hh:mm</code>.
 492      * @param result the human-readable name of this time zone in the default locale.
 493      * @return       A reference to 'result'.
 494      * @stable ICU 2.0
 495      */
 496     UnicodeString& getDisplayName(UnicodeString& result) const;
 497
 498     /**
 499      * Returns a name of this time zone suitable for presentation to the user
 500      * in the specified locale.
 501      * This method returns the long name, not including daylight savings.
 502      * If the display name is not available for the locale,
 503      * then this method returns a string in the format
 504      * <code>GMT[+-]hh:mm</code>.
 505      * @param locale the locale in which to supply the display name.
 506      * @param result the human-readable name of this time zone in the given locale
 507      *               or in the default locale if the given locale is not recognized.
 508      * @return       A reference to 'result'.
 509      * @stable ICU 2.0
 510      */
 511     UnicodeString& getDisplayName(const Locale& locale, UnicodeString& result) const;
 512
 513     /**
 514      * Returns a name of this time zone suitable for presentation to the user
 515      * in the default locale.
 516      * If the display name is not available for the locale,
 517      * then this method returns a string in the format
 518      * <code>GMT[+-]hh:mm</code>.
 519      * @param daylight if true, return the daylight savings name.
 520      * @param style either <code>LONG</code> or <code>SHORT</code>
 521      * @param result the human-readable name of this time zone in the default locale.
 522      * @return       A reference to 'result'.
 523      * @stable ICU 2.0
 524      */
 525     UnicodeString& getDisplayName(UBool daylight, EDisplayType style, UnicodeString& result) const;
 526
 527     /**
 528      * Returns a name of this time zone suitable for presentation to the user
 529      * in the specified locale.
 530      * If the display name is not available for the locale,
 531      * then this method returns a string in the format
 532      * <code>GMT[+-]hh:mm</code>.
 533      * @param daylight if true, return the daylight savings name.
 534      * @param style either <code>LONG</code> or <code>SHORT</code>
 535      * @param locale the locale in which to supply the display name.
 536      * @param result the human-readable name of this time zone in the given locale
 537      *               or in the default locale if the given locale is not recognized.
 538      * @return       A refence to 'result'.
 539      * @stable ICU 2.0
 540      */
 541     UnicodeString& getDisplayName(UBool daylight, EDisplayType style, const Locale& locale, UnicodeString& result) const;
 542
 543     /**
 544      * Queries if this time zone uses daylight savings time.
 545      * @return true if this time zone uses daylight savings time,
 546      * false, otherwise.
 547      * @stable ICU 2.0
 548      */
 549     virtual UBool useDaylightTime(void) const = 0;
 550
 551     /**
 552      * Queries if the given date is in daylight savings time in
 553      * this time zone.
 554      * This method is wasteful since it creates a new GregorianCalendar and
 555      * deletes it each time it is called. This is a deprecated method
 556      * and provided only for Java compatibility.
 557      *
 558      * @param date the given UDate.
 559      * @param status Output param filled in with success/error code.
 560      * @return true if the given date is in daylight savings time,
 561      * false, otherwise.
 562      * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead.
 563      */
 564     virtual UBool inDaylightTime(UDate date, UErrorCode& status) const = 0;
 565
 566     /**
 567      * Returns true if this zone has the same rule and offset as another zone.
 568      * That is, if this zone differs only in ID, if at all.
 569      * @param other the <code>TimeZone</code> object to be compared with
 570      * @return true if the given zone is the same as this one,
 571      * with the possible exception of the ID
 572      * @stable ICU 2.0
 573      */
 574     virtual UBool hasSameRules(const TimeZone& other) const;
 575
 576     /**
 577      * Clones TimeZone objects polymorphically. Clients are responsible for deleting
 578      * the TimeZone object cloned.
 579      *
 580      * @return   A new copy of this TimeZone object.
 581      * @stable ICU 2.0
 582      */
 583     virtual TimeZone* clone(void) const = 0;
 584
 585     /**
 586      * Return the class ID for this class.  This is useful only for
 587      * comparing to a return value from getDynamicClassID().
 588      * @return The class ID for all objects of this class.
 589      * @stable ICU 2.0
 590      */
 591     static UClassID U_EXPORT2 getStaticClassID(void);
 592
 593     /**
 594      * Returns a unique class ID POLYMORPHICALLY. This method is to
 595      * implement a simple version of RTTI, since not all C++ compilers support genuine
 596      * RTTI. Polymorphic operator==() and clone() methods call this method.
 597      * <P>
 598      * Concrete subclasses of TimeZone must use the UOBJECT_DEFINE_RTTI_IMPLEMENTATION
 599      *  macro from uobject.h in their implementation to provide correct RTTI information.
 600      * @return   The class ID for this object. All objects of a given class have the
 601      *           same class ID. Objects of other classes have different class IDs.
 602      * @stable ICU 2.0
 603      */
 604     virtual UClassID getDynamicClassID(void) const = 0;
 605
 606     /**
 607      * Returns the amount of time to be added to local standard time
 608      * to get local wall clock time.
 609      * <p>
 610      * The default implementation always returns 3600000 milliseconds
 611      * (i.e., one hour) if this time zone observes Daylight Saving
 612      * Time. Otherwise, 0 (zero) is returned.
 613      * <p>
 614      * If an underlying TimeZone implementation subclass supports
 615      * historical Daylight Saving Time changes, this method returns
 616      * the known latest daylight saving value.
 617      *
 618      * @return the amount of saving time in milliseconds
 619      * @draft ICU 3.6
 620      */
 621     virtual int32_t getDSTSavings() const;
 622 protected:
 623
 624     /**
 625      * Default constructor.  ID is initialized to the empty string.
 626      * @stable ICU 2.0
 627      */
 628     TimeZone();
 629
 630     /**
 631      * Construct a timezone with a given ID.
 632      * @param id a system time zone ID
 633      * @stable ICU 2.0
 634      */
 635     TimeZone(const UnicodeString &id);
 636
 637     /**
 638      * Copy constructor.
 639      * @param source the object to be copied.
 640      * @stable ICU 2.0
 641      */
 642     TimeZone(const TimeZone& source);
 643
 644     /**
 645      * Default assignment operator.
 646      * @param right the object to be copied.
 647      * @stable ICU 2.0
 648      */
 649     TimeZone& operator=(const TimeZone& right);
 650
 651     /**
 652      * Utility function. For internally loading rule data.
 653      * @param top Top resource bundle for tz data
 654      * @param ruleid ID of rule to load
 655      * @param oldbundle Old bundle to reuse or NULL
 656      * @param status Status parameter
 657      * @return either a new bundle or *oldbundle
 658      * @internal
 659      */
 660     static UResourceBundle* loadRule(const UResourceBundle* top, const UnicodeString& ruleid, UResourceBundle* oldbundle, UErrorCode&status);
 661
 662 private:
 663     static TimeZone*        createCustomTimeZone(const UnicodeString&); // Creates a time zone based on the string.
 664
 665     /**
 666      * Responsible for setting up DEFAULT_ZONE.  Uses routines in TPlatformUtilities
 667      * (i.e., platform-specific calls) to get the current system time zone.  Failing
 668      * that, uses the platform-specific default time zone.  Failing that, uses GMT.
 669      */
 670     static void             initDefault(void);
 671
 672     // See source file for documentation
 673     /**
 674      * Lookup the given name in our system zone table.  If found,
 675      * instantiate a new zone of that name and return it.  If not
 676      * found, return 0.
 677      * @param name tthe given name of a system time zone.
 678      * @return the timezone indicated by the 'name'.
 679      */
 680     static TimeZone*        createSystemTimeZone(const UnicodeString& name);
 681
 682     UnicodeString           fID;    // this time zone's ID
 683 };
 684
 685
 686 // -------------------------------------
 687
 688 inline UnicodeString&
 689 TimeZone::getID(UnicodeString& ID) const
 690 {
 691     ID = fID;
 692     return ID;
 693 }
 694
 695 // -------------------------------------
 696
 697 inline void
 698 TimeZone::setID(const UnicodeString& ID)
 699 {
 700     fID = ID;
 701 }
 702 U_NAMESPACE_END
 703
 704 #endif /* #if !UCONFIG_NO_FORMATTING */
 705
 706 #endif //_TIMEZONE
 707 //eof