Line data Source code
1 : /*************************************************************************
2 : * Copyright (c) 1997-2009, International Business Machines Corporation
3 : * and others. All Rights Reserved.
4 : **************************************************************************
5 : *
6 : * File TIMEZONE.H
7 : *
8 : * Modification History:
9 : *
10 : * Date Name Description
11 : * 04/21/97 aliu Overhauled header.
12 : * 07/09/97 helena Changed createInstance to createDefault.
13 : * 08/06/97 aliu Removed dependency on internal header for Hashtable.
14 : * 08/10/98 stephen Changed getDisplayName() API conventions to match
15 : * 08/19/98 stephen Changed createTimeZone() to never return 0
16 : * 09/02/98 stephen Sync to JDK 1.2 8/31
17 : * - Added getOffset(... monthlen ...)
18 : * - Added hasSameRules()
19 : * 09/15/98 stephen Added getStaticClassID
20 : * 12/03/99 aliu Moved data out of static table into icudata.dll.
21 : * Hashtable replaced by new static data structures.
22 : * 12/14/99 aliu Made GMT public.
23 : * 08/15/01 grhoten Made GMT private and added the getGMT() function
24 : **************************************************************************
25 : */
26 :
27 : #ifndef TIMEZONE_H
28 : #define TIMEZONE_H
29 :
30 : #include "unicode/utypes.h"
31 :
32 : /**
33 : * \file
34 : * \brief C++ API: TimeZone object
35 : */
36 :
37 : #if !UCONFIG_NO_FORMATTING
38 :
39 : #include "unicode/uobject.h"
40 : #include "unicode/unistr.h"
41 : #include "unicode/ures.h"
42 :
43 : U_NAMESPACE_BEGIN
44 :
45 : class StringEnumeration;
46 :
47 : /**
48 : *
49 : * <code>TimeZone</code> represents a time zone offset, and also figures out daylight
50 : * savings.
51 : *
52 : * <p>
53 : * Typically, you get a <code>TimeZone</code> using <code>createDefault</code>
54 : * which creates a <code>TimeZone</code> based on the time zone where the program
55 : * is running. For example, for a program running in Japan, <code>createDefault</code>
56 : * creates a <code>TimeZone</code> object based on Japanese Standard Time.
57 : *
58 : * <p>
59 : * You can also get a <code>TimeZone</code> using <code>createTimeZone</code> along
60 : * with a time zone ID. For instance, the time zone ID for the US Pacific
61 : * Time zone is "America/Los_Angeles". So, you can get a Pacific Time <code>TimeZone</code> object
62 : * with:
63 : * \htmlonly<blockquote>\endhtmlonly
64 : * <pre>
65 : * TimeZone *tz = TimeZone::createTimeZone("America/Los_Angeles");
66 : * </pre>
67 : * \htmlonly</blockquote>\endhtmlonly
68 : * You can use <code>getAvailableIDs</code> method to iterate through
69 : * all the supported time zone IDs. You can then choose a
70 : * supported ID to get a <code>TimeZone</code>.
71 : * If the time zone you want is not represented by one of the
72 : * supported IDs, then you can create a custom time zone ID with
73 : * the following syntax:
74 : *
75 : * \htmlonly<blockquote>\endhtmlonly
76 : * <pre>
77 : * GMT[+|-]hh[[:]mm]
78 : * </pre>
79 : * \htmlonly</blockquote>\endhtmlonly
80 : *
81 : * For example, you might specify GMT+14:00 as a custom
82 : * time zone ID. The <code>TimeZone</code> that is returned
83 : * when you specify a custom time zone ID does not include
84 : * daylight savings time.
85 : *
86 : * TimeZone is an abstract class representing a time zone. A TimeZone is needed for
87 : * Calendar to produce local time for a particular time zone. A TimeZone comprises
88 : * three basic pieces of information:
89 : * <ul>
90 : * <li>A time zone offset; that, is the number of milliseconds to add or subtract
91 : * from a time expressed in terms of GMT to convert it to the same time in that
92 : * time zone (without taking daylight savings time into account).</li>
93 : * <li>Logic necessary to take daylight savings time into account if daylight savings
94 : * time is observed in that time zone (e.g., the days and hours on which daylight
95 : * savings time begins and ends).</li>
96 : * <li>An ID. This is a text string that uniquely identifies the time zone.</li>
97 : * </ul>
98 : *
99 : * (Only the ID is actually implemented in TimeZone; subclasses of TimeZone may handle
100 : * daylight savings time and GMT offset in different ways. Currently we only have one
101 : * TimeZone subclass: SimpleTimeZone.)
102 : * <P>
103 : * The TimeZone class contains a static list containing a TimeZone object for every
104 : * combination of GMT offset and daylight-savings time rules currently in use in the
105 : * world, each with a unique ID. Each ID consists of a region (usually a continent or
106 : * ocean) and a city in that region, separated by a slash, (for example, US Pacific
107 : * Time is "America/Los_Angeles.") Because older versions of this class used
108 : * three- or four-letter abbreviations instead, there is also a table that maps the older
109 : * abbreviations to the newer ones (for example, "PST" maps to "America/Los_Angeles").
110 : * Anywhere the API requires an ID, you can use either form.
111 : * <P>
112 : * To create a new TimeZone, you call the factory function TimeZone::createTimeZone()
113 : * and pass it a time zone ID. You can use the createEnumeration() function to
114 : * obtain a list of all the time zone IDs recognized by createTimeZone().
115 : * <P>
116 : * You can also use TimeZone::createDefault() to create a TimeZone. This function uses
117 : * platform-specific APIs to produce a TimeZone for the time zone corresponding to
118 : * the client's computer's physical location. For example, if you're in Japan (assuming
119 : * your machine is set up correctly), TimeZone::createDefault() will return a TimeZone
120 : * for Japanese Standard Time ("Asia/Tokyo").
121 : */
122 : class U_I18N_API TimeZone : public UObject {
123 : public:
124 : /**
125 : * @stable ICU 2.0
126 : */
127 : virtual ~TimeZone();
128 :
129 : /**
130 : * The GMT time zone has a raw offset of zero and does not use daylight
131 : * savings time. This is a commonly used time zone.
132 : * @return the GMT time zone.
133 : * @stable ICU 2.0
134 : */
135 : static const TimeZone* U_EXPORT2 getGMT(void);
136 :
137 : /**
138 : * Creates a <code>TimeZone</code> for the given ID.
139 : * @param ID the ID for a <code>TimeZone</code>, such as "America/Los_Angeles",
140 : * or a custom ID 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 time zone 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 time zone 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 createDefault()) 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 the timezone data version currently used by ICU.
329 : * @param status Output param to filled in with a success or an error.
330 : * @return the version string, such as "2007f"
331 : * @stable ICU 3.8
332 : */
333 : static const char* U_EXPORT2 getTZDataVersion(UErrorCode& status);
334 :
335 : /**
336 : * Returns the canonical system timezone ID or the normalized
337 : * custom time zone ID for the given time zone ID.
338 : * @param id The input time zone ID to be canonicalized.
339 : * @param canonicalID Receives the canonical system time zone ID
340 : * or the custom time zone ID in normalized format.
341 : * @param status Recevies the status. When the given time zone ID
342 : * is neither a known system time zone ID nor a
343 : * valid custom time zone ID, U_ILLEGAL_ARGUMENT_ERROR
344 : * is set.
345 : * @return A reference to the result.
346 : * @stable ICU 4.0
347 : */
348 : static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id,
349 : UnicodeString& canonicalID, UErrorCode& status);
350 :
351 : /**
352 : * Returns the canonical system time zone ID or the normalized
353 : * custom time zone ID for the given time zone ID.
354 : * @param id The input time zone ID to be canonicalized.
355 : * @param canonicalID Receives the canonical system time zone ID
356 : * or the custom time zone ID in normalized format.
357 : * @param isSystemID Receives if the given ID is a known system
358 : * time zone ID.
359 : * @param status Recevies the status. When the given time zone ID
360 : * is neither a known system time zone ID nor a
361 : * valid custom time zone ID, U_ILLEGAL_ARGUMENT_ERROR
362 : * is set.
363 : * @return A reference to the result.
364 : * @stable ICU 4.0
365 : */
366 : static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id,
367 : UnicodeString& canonicalID, UBool& isSystemID, UErrorCode& status);
368 :
369 : /**
370 : * Returns true if the two TimeZones are equal. (The TimeZone version only compares
371 : * IDs, but subclasses are expected to also compare the fields they add.)
372 : *
373 : * @param that The TimeZone object to be compared with.
374 : * @return True if the given TimeZone is equal to this TimeZone; false
375 : * otherwise.
376 : * @stable ICU 2.0
377 : */
378 : virtual UBool operator==(const TimeZone& that) const;
379 :
380 : /**
381 : * Returns true if the two TimeZones are NOT equal; that is, if operator==() returns
382 : * false.
383 : *
384 : * @param that The TimeZone object to be compared with.
385 : * @return True if the given TimeZone is not equal to this TimeZone; false
386 : * otherwise.
387 : * @stable ICU 2.0
388 : */
389 : UBool operator!=(const TimeZone& that) const {return !operator==(that);}
390 :
391 : /**
392 : * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
393 : * to GMT to get local time in this time zone, taking daylight savings time into
394 : * account) as of a particular reference date. The reference date is used to determine
395 : * whether daylight savings time is in effect and needs to be figured into the offset
396 : * that is returned (in other words, what is the adjusted GMT offset in this time zone
397 : * at this particular date and time?). For the time zones produced by createTimeZone(),
398 : * the reference data is specified according to the Gregorian calendar, and the date
399 : * and time fields are local standard time.
400 : *
401 : * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
402 : * which returns both the raw and the DST offset for a given time. This method
403 : * is retained only for backward compatibility.
404 : *
405 : * @param era The reference date's era
406 : * @param year The reference date's year
407 : * @param month The reference date's month (0-based; 0 is January)
408 : * @param day The reference date's day-in-month (1-based)
409 : * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
410 : * @param millis The reference date's milliseconds in day, local standard time
411 : * @param status Output param to filled in with a success or an error.
412 : * @return The offset in milliseconds to add to GMT to get local time.
413 : * @stable ICU 2.0
414 : */
415 : virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
416 : uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const = 0;
417 :
418 : /**
419 : * Gets the time zone offset, for current date, modified in case of
420 : * daylight savings. This is the offset to add *to* UTC to get local time.
421 : *
422 : * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
423 : * which returns both the raw and the DST offset for a given time. This method
424 : * is retained only for backward compatibility.
425 : *
426 : * @param era the era of the given date.
427 : * @param year the year in the given date.
428 : * @param month the month in the given date.
429 : * Month is 0-based. e.g., 0 for January.
430 : * @param day the day-in-month of the given date.
431 : * @param dayOfWeek the day-of-week of the given date.
432 : * @param milliseconds the millis in day in <em>standard</em> local time.
433 : * @param monthLength the length of the given month in days.
434 : * @param status Output param to filled in with a success or an error.
435 : * @return the offset to add *to* GMT to get local time.
436 : * @stable ICU 2.0
437 : */
438 : virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
439 : uint8_t dayOfWeek, int32_t milliseconds,
440 : int32_t monthLength, UErrorCode& status) const = 0;
441 :
442 : /**
443 : * Returns the time zone raw and GMT offset for the given moment
444 : * in time. Upon return, local-millis = GMT-millis + rawOffset +
445 : * dstOffset. All computations are performed in the proleptic
446 : * Gregorian calendar. The default implementation in the TimeZone
447 : * class delegates to the 8-argument getOffset().
448 : *
449 : * @param date moment in time for which to return offsets, in
450 : * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
451 : * time or local wall time, depending on `local'.
452 : * @param local if true, `date' is local wall time; otherwise it
453 : * is in GMT time.
454 : * @param rawOffset output parameter to receive the raw offset, that
455 : * is, the offset not including DST adjustments
456 : * @param dstOffset output parameter to receive the DST offset,
457 : * that is, the offset to be added to `rawOffset' to obtain the
458 : * total offset between local and GMT time. If DST is not in
459 : * effect, this value is zero; otherwise it is a positive value,
460 : * typically one hour.
461 : * @param ec input-output error code
462 : *
463 : * @stable ICU 2.8
464 : */
465 : virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
466 : int32_t& dstOffset, UErrorCode& ec) const;
467 :
468 : /**
469 : * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
470 : * to GMT to get local time, before taking daylight savings time into account).
471 : *
472 : * @param offsetMillis The new raw GMT offset for this time zone.
473 : * @stable ICU 2.0
474 : */
475 : virtual void setRawOffset(int32_t offsetMillis) = 0;
476 :
477 : /**
478 : * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
479 : * to GMT to get local time, before taking daylight savings time into account).
480 : *
481 : * @return The TimeZone's raw GMT offset.
482 : * @stable ICU 2.0
483 : */
484 : virtual int32_t getRawOffset(void) const = 0;
485 :
486 : /**
487 : * Fills in "ID" with the TimeZone's ID.
488 : *
489 : * @param ID Receives this TimeZone's ID.
490 : * @return A reference to 'ID'
491 : * @stable ICU 2.0
492 : */
493 : UnicodeString& getID(UnicodeString& ID) const;
494 :
495 : /**
496 : * Sets the TimeZone's ID to the specified value. This doesn't affect any other
497 : * fields (for example, if you say<
498 : * blockquote><pre>
499 : * . TimeZone* foo = TimeZone::createTimeZone("America/New_York");
500 : * . foo.setID("America/Los_Angeles");
501 : * </pre>\htmlonly</blockquote>\endhtmlonly
502 : * the time zone's GMT offset and daylight-savings rules don't change to those for
503 : * Los Angeles. They're still those for New York. Only the ID has changed.)
504 : *
505 : * @param ID The new time zone ID.
506 : * @stable ICU 2.0
507 : */
508 : void setID(const UnicodeString& ID);
509 :
510 : /**
511 : * Enum for use with getDisplayName
512 : * @stable ICU 2.4
513 : */
514 : enum EDisplayType {
515 : /**
516 : * Selector for short display name
517 : * @stable ICU 2.4
518 : */
519 : SHORT = 1,
520 : /**
521 : * Selector for long display name
522 : * @stable ICU 2.4
523 : */
524 : LONG
525 : };
526 :
527 : /**
528 : * Returns a name of this time zone suitable for presentation to the user
529 : * in the default locale.
530 : * This method returns the long name, not including daylight savings.
531 : * If the display name is not available for the locale,
532 : * then this method returns a string in the format
533 : * <code>GMT[+-]hh:mm</code>.
534 : * @param result the human-readable name of this time zone in the default locale.
535 : * @return A reference to 'result'.
536 : * @stable ICU 2.0
537 : */
538 : UnicodeString& getDisplayName(UnicodeString& result) const;
539 :
540 : /**
541 : * Returns a name of this time zone suitable for presentation to the user
542 : * in the specified locale.
543 : * This method returns the long name, not including daylight savings.
544 : * If the display name is not available for the locale,
545 : * then this method returns a string in the format
546 : * <code>GMT[+-]hh:mm</code>.
547 : * @param locale the locale in which to supply the display name.
548 : * @param result the human-readable name of this time zone in the given locale
549 : * or in the default locale if the given locale is not recognized.
550 : * @return A reference to 'result'.
551 : * @stable ICU 2.0
552 : */
553 : UnicodeString& getDisplayName(const Locale& locale, UnicodeString& result) const;
554 :
555 : /**
556 : * Returns a name of this time zone suitable for presentation to the user
557 : * in the default locale.
558 : * If the display name is not available for the locale,
559 : * then this method returns a string in the format
560 : * <code>GMT[+-]hh:mm</code>.
561 : * @param daylight if true, return the daylight savings name.
562 : * @param style either <code>LONG</code> or <code>SHORT</code>
563 : * @param result the human-readable name of this time zone in the default locale.
564 : * @return A reference to 'result'.
565 : * @stable ICU 2.0
566 : */
567 : UnicodeString& getDisplayName(UBool daylight, EDisplayType style, UnicodeString& result) const;
568 :
569 : /**
570 : * Returns a name of this time zone suitable for presentation to the user
571 : * in the specified locale.
572 : * If the display name is not available for the locale,
573 : * then this method returns a string in the format
574 : * <code>GMT[+-]hh:mm</code>.
575 : * @param daylight if true, return the daylight savings name.
576 : * @param style either <code>LONG</code> or <code>SHORT</code>
577 : * @param locale the locale in which to supply the display name.
578 : * @param result the human-readable name of this time zone in the given locale
579 : * or in the default locale if the given locale is not recognized.
580 : * @return A refence to 'result'.
581 : * @stable ICU 2.0
582 : */
583 : UnicodeString& getDisplayName(UBool daylight, EDisplayType style, const Locale& locale, UnicodeString& result) const;
584 :
585 : /**
586 : * Queries if this time zone uses daylight savings time.
587 : * @return true if this time zone uses daylight savings time,
588 : * false, otherwise.
589 : * @stable ICU 2.0
590 : */
591 : virtual UBool useDaylightTime(void) const = 0;
592 :
593 : /**
594 : * Queries if the given date is in daylight savings time in
595 : * this time zone.
596 : * This method is wasteful since it creates a new GregorianCalendar and
597 : * deletes it each time it is called. This is a deprecated method
598 : * and provided only for Java compatibility.
599 : *
600 : * @param date the given UDate.
601 : * @param status Output param filled in with success/error code.
602 : * @return true if the given date is in daylight savings time,
603 : * false, otherwise.
604 : * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead.
605 : */
606 : virtual UBool inDaylightTime(UDate date, UErrorCode& status) const = 0;
607 :
608 : /**
609 : * Returns true if this zone has the same rule and offset as another zone.
610 : * That is, if this zone differs only in ID, if at all.
611 : * @param other the <code>TimeZone</code> object to be compared with
612 : * @return true if the given zone is the same as this one,
613 : * with the possible exception of the ID
614 : * @stable ICU 2.0
615 : */
616 : virtual UBool hasSameRules(const TimeZone& other) const;
617 :
618 : /**
619 : * Clones TimeZone objects polymorphically. Clients are responsible for deleting
620 : * the TimeZone object cloned.
621 : *
622 : * @return A new copy of this TimeZone object.
623 : * @stable ICU 2.0
624 : */
625 : virtual TimeZone* clone(void) const = 0;
626 :
627 : /**
628 : * Return the class ID for this class. This is useful only for
629 : * comparing to a return value from getDynamicClassID().
630 : * @return The class ID for all objects of this class.
631 : * @stable ICU 2.0
632 : */
633 : static UClassID U_EXPORT2 getStaticClassID(void);
634 :
635 : /**
636 : * Returns a unique class ID POLYMORPHICALLY. This method is to
637 : * implement a simple version of RTTI, since not all C++ compilers support genuine
638 : * RTTI. Polymorphic operator==() and clone() methods call this method.
639 : * <P>
640 : * Concrete subclasses of TimeZone must use the UOBJECT_DEFINE_RTTI_IMPLEMENTATION
641 : * macro from uobject.h in their implementation to provide correct RTTI information.
642 : * @return The class ID for this object. All objects of a given class have the
643 : * same class ID. Objects of other classes have different class IDs.
644 : * @stable ICU 2.0
645 : */
646 : virtual UClassID getDynamicClassID(void) const = 0;
647 :
648 : /**
649 : * Returns the amount of time to be added to local standard time
650 : * to get local wall clock time.
651 : * <p>
652 : * The default implementation always returns 3600000 milliseconds
653 : * (i.e., one hour) if this time zone observes Daylight Saving
654 : * Time. Otherwise, 0 (zero) is returned.
655 : * <p>
656 : * If an underlying TimeZone implementation subclass supports
657 : * historical Daylight Saving Time changes, this method returns
658 : * the known latest daylight saving value.
659 : *
660 : * @return the amount of saving time in milliseconds
661 : * @stable ICU 3.6
662 : */
663 : virtual int32_t getDSTSavings() const;
664 :
665 : protected:
666 :
667 : /**
668 : * Default constructor. ID is initialized to the empty string.
669 : * @stable ICU 2.0
670 : */
671 : TimeZone();
672 :
673 : /**
674 : * Construct a TimeZone with a given ID.
675 : * @param id a system time zone ID
676 : * @stable ICU 2.0
677 : */
678 : TimeZone(const UnicodeString &id);
679 :
680 : /**
681 : * Copy constructor.
682 : * @param source the object to be copied.
683 : * @stable ICU 2.0
684 : */
685 : TimeZone(const TimeZone& source);
686 :
687 : /**
688 : * Default assignment operator.
689 : * @param right the object to be copied.
690 : * @stable ICU 2.0
691 : */
692 : TimeZone& operator=(const TimeZone& right);
693 :
694 : /**
695 : * Utility function. For internally loading rule data.
696 : * @param top Top resource bundle for tz data
697 : * @param ruleid ID of rule to load
698 : * @param oldbundle Old bundle to reuse or NULL
699 : * @param status Status parameter
700 : * @return either a new bundle or *oldbundle
701 : * @internal
702 : */
703 : static UResourceBundle* loadRule(const UResourceBundle* top, const UnicodeString& ruleid, UResourceBundle* oldbundle, UErrorCode&status);
704 :
705 : private:
706 : friend class ZoneMeta;
707 :
708 :
709 : static TimeZone* createCustomTimeZone(const UnicodeString&); // Creates a time zone based on the string.
710 :
711 : /**
712 : * Resolve a link in Olson tzdata. When the given id is known and it's not a link,
713 : * the id itself is returned. When the given id is known and it is a link, then
714 : * dereferenced zone id is returned. When the given id is unknown, then it returns
715 : * empty string.
716 : * @param linkTo Input zone id string
717 : * @param linkFrom Receives the dereferenced zone id string
718 : * @return The reference to the result (linkFrom)
719 : */
720 : static UnicodeString& dereferOlsonLink(const UnicodeString& linkTo, UnicodeString& linkFrom);
721 :
722 : /**
723 : * Parses the given custom time zone identifier
724 : * @param id id A string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or
725 : * GMT[+-]hh.
726 : * @param sign Receves parsed sign, 1 for positive, -1 for negative.
727 : * @param hour Receives parsed hour field
728 : * @param minute Receives parsed minute field
729 : * @param second Receives parsed second field
730 : * @return Returns TRUE when the given custom id is valid.
731 : */
732 : static UBool parseCustomID(const UnicodeString& id, int32_t& sign, int32_t& hour,
733 : int32_t& min, int32_t& sec);
734 :
735 : /**
736 : * Parse a custom time zone identifier and return the normalized
737 : * custom time zone identifier for the given custom id string.
738 : * @param id a string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or
739 : * GMT[+-]hh.
740 : * @param normalized Receives the normalized custom ID
741 : * @param status Receives the status. When the input ID string is invalid,
742 : * U_ILLEGAL_ARGUMENT_ERROR is set.
743 : * @return The normalized custom id string.
744 : */
745 : static UnicodeString& getCustomID(const UnicodeString& id, UnicodeString& normalized,
746 : UErrorCode& status);
747 :
748 : /**
749 : * Returns the normalized custome time zone ID for the given offset fields.
750 : * @param hour offset hours
751 : * @param min offset minutes
752 : * @param sec offset seconds
753 : * @param netative sign of the offset, TRUE for negative offset.
754 : * @param id Receves the format result (normalized custom ID)
755 : * @return The reference to id
756 : */
757 : static UnicodeString& formatCustomID(int32_t hour, int32_t min, int32_t sec,
758 : UBool negative, UnicodeString& id);
759 :
760 : /**
761 : * Responsible for setting up DEFAULT_ZONE. Uses routines in TPlatformUtilities
762 : * (i.e., platform-specific calls) to get the current system time zone. Failing
763 : * that, uses the platform-specific default time zone. Failing that, uses GMT.
764 : */
765 : static void initDefault(void);
766 :
767 : // See source file for documentation
768 : /**
769 : * Lookup the given name in our system zone table. If found,
770 : * instantiate a new zone of that name and return it. If not
771 : * found, return 0.
772 : * @param name tthe given name of a system time zone.
773 : * @return the TimeZone indicated by the 'name'.
774 : */
775 : static TimeZone* createSystemTimeZone(const UnicodeString& name);
776 :
777 : UnicodeString fID; // this time zone's ID
778 : };
779 :
780 :
781 : // -------------------------------------
782 :
783 : inline UnicodeString&
784 0 : TimeZone::getID(UnicodeString& ID) const
785 : {
786 0 : ID = fID;
787 0 : return ID;
788 : }
789 :
790 : // -------------------------------------
791 :
792 : inline void
793 : TimeZone::setID(const UnicodeString& ID)
794 : {
795 : fID = ID;
796 : }
797 : U_NAMESPACE_END
798 :
799 : #endif /* #if !UCONFIG_NO_FORMATTING */
800 :
801 : #endif //_TIMEZONE
802 : //eof
|
