OLD | NEW |
| (Empty) |
1 /************************************************************************* | |
2 * Copyright (c) 1997-2010, 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 day
light | |
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 progra
m | |
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> al
ong | |
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>Time
Zone</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 compri
ses | |
88 * three basic pieces of information: | |
89 * <ul> | |
90 * <li>A time zone offset; that, is the number of milliseconds to add or subt
ract | |
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 da
ylight | |
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 ha
ve one | |
101 * TimeZone subclass: SimpleTimeZone.) | |
102 * <P> | |
103 * The TimeZone class contains a static list containing a TimeZone object for ev
ery | |
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 contin
ent or | |
106 * ocean) and a city in that region, separated by a slash, (for example, US Paci
fic | |
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_Ange
les"). | |
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::createTimeZ
one() | |
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 functi
on 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 Ti
meZone | |
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_Angele
s", | |
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 /** | |
190 * Returns the number of IDs in the equivalency group that | |
191 * includes the given ID. An equivalency group contains zones | |
192 * that have the same GMT offset and rules. | |
193 * | |
194 * <p>The returned count includes the given ID; it is always >= 1. | |
195 * The given ID must be a system time zone. If it is not, returns | |
196 * zero. | |
197 * @param id a system time zone ID | |
198 * @return the number of zones in the equivalency group containing | |
199 * 'id', or zero if 'id' is not a valid system ID | |
200 * @see #getEquivalentID | |
201 * @stable ICU 2.0 | |
202 */ | |
203 static int32_t U_EXPORT2 countEquivalentIDs(const UnicodeString& id); | |
204 | |
205 /** | |
206 * Returns an ID in the equivalency group that | |
207 * includes the given ID. An equivalency group contains zones | |
208 * that have the same GMT offset and rules. | |
209 * | |
210 * <p>The given index must be in the range 0..n-1, where n is the | |
211 * value returned by <code>countEquivalentIDs(id)</code>. For | |
212 * some value of 'index', the returned value will be equal to the | |
213 * given id. If the given id is not a valid system time zone, or | |
214 * if 'index' is out of range, then returns an empty string. | |
215 * @param id a system time zone ID | |
216 * @param index a value from 0 to n-1, where n is the value | |
217 * returned by <code>countEquivalentIDs(id)</code> | |
218 * @return the ID of the index-th zone in the equivalency group | |
219 * containing 'id', or an empty string if 'id' is not a valid | |
220 * system ID or 'index' is out of range | |
221 * @see #countEquivalentIDs | |
222 * @stable ICU 2.0 | |
223 */ | |
224 static const UnicodeString U_EXPORT2 getEquivalentID(const UnicodeString& id
, | |
225 int32_t index); | |
226 | |
227 /** | |
228 * Creates a new copy of the default TimeZone for this host. Unless the defa
ult time | |
229 * zone has already been set using adoptDefault() or setDefault(), the defau
lt is | |
230 * determined by querying the system using methods in TPlatformUtilities. If
the | |
231 * system routines fail, or if they specify a TimeZone or TimeZone offset wh
ich is not | |
232 * recognized, the TimeZone indicated by the ID kLastResortID is instantiate
d | |
233 * and made the default. | |
234 * | |
235 * @return A default TimeZone. Clients are responsible for deleting the ti
me zone | |
236 * object returned. | |
237 * @stable ICU 2.0 | |
238 */ | |
239 static TimeZone* U_EXPORT2 createDefault(void); | |
240 | |
241 /** | |
242 * Sets the default time zone (i.e., what's returned by createDefault()) to
be the | |
243 * specified time zone. If NULL is specified for the time zone, the default
time | |
244 * zone is set to the default host time zone. This call adopts the TimeZone
object | |
245 * passed in; the clent is no longer responsible for deleting it. | |
246 * | |
247 * @param zone A pointer to the new TimeZone object to use as the default. | |
248 * @stable ICU 2.0 | |
249 */ | |
250 static void U_EXPORT2 adoptDefault(TimeZone* zone); | |
251 | |
252 /** | |
253 * Same as adoptDefault(), except that the TimeZone object passed in is NOT
adopted; | |
254 * the caller remains responsible for deleting it. | |
255 * | |
256 * @param zone The given timezone. | |
257 * @system | |
258 */ | |
259 static void U_EXPORT2 setDefault(const TimeZone& zone); | |
260 | |
261 /** | |
262 * Returns the timezone data version currently used by ICU. | |
263 * @param status Output param to filled in with a success or an error. | |
264 * @return the version string, such as "2007f" | |
265 * @stable ICU 3.8 | |
266 */ | |
267 static const char* U_EXPORT2 getTZDataVersion(UErrorCode& status); | |
268 | |
269 /** | |
270 * Returns the canonical system timezone ID or the normalized | |
271 * custom time zone ID for the given time zone ID. | |
272 * @param id The input time zone ID to be canonicalized. | |
273 * @param canonicalID Receives the canonical system time zone ID | |
274 * or the custom time zone ID in normalized format. | |
275 * @param status Recevies the status. When the given time zone ID | |
276 * is neither a known system time zone ID nor a | |
277 * valid custom time zone ID, U_ILLEGAL_ARGUMENT_ERROR | |
278 * is set. | |
279 * @return A reference to the result. | |
280 * @stable ICU 4.0 | |
281 */ | |
282 static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id, | |
283 UnicodeString& canonicalID, UErrorCode& status); | |
284 | |
285 /** | |
286 * Returns the canonical system time zone ID or the normalized | |
287 * custom time zone ID for the given time zone ID. | |
288 * @param id The input time zone ID to be canonicalized. | |
289 * @param canonicalID Receives the canonical system time zone ID | |
290 * or the custom time zone ID in normalized format. | |
291 * @param isSystemID Receives if the given ID is a known system | |
292 * time zone ID. | |
293 * @param status Recevies the status. When the given time zone ID | |
294 * is neither a known system time zone ID nor a | |
295 * valid custom time zone ID, U_ILLEGAL_ARGUMENT_ERROR | |
296 * is set. | |
297 * @return A reference to the result. | |
298 * @stable ICU 4.0 | |
299 */ | |
300 static UnicodeString& U_EXPORT2 getCanonicalID(const UnicodeString& id, | |
301 UnicodeString& canonicalID, UBool& isSystemID, UErrorCode& status); | |
302 | |
303 /** | |
304 * Returns true if the two TimeZones are equal. (The TimeZone version only
compares | |
305 * IDs, but subclasses are expected to also compare the fields they add.) | |
306 * | |
307 * @param that The TimeZone object to be compared with. | |
308 * @return True if the given TimeZone is equal to this TimeZone; false | |
309 * otherwise. | |
310 * @stable ICU 2.0 | |
311 */ | |
312 virtual UBool operator==(const TimeZone& that) const; | |
313 | |
314 /** | |
315 * Returns true if the two TimeZones are NOT equal; that is, if operator==()
returns | |
316 * false. | |
317 * | |
318 * @param that The TimeZone object to be compared with. | |
319 * @return True if the given TimeZone is not equal to this TimeZone; fa
lse | |
320 * otherwise. | |
321 * @stable ICU 2.0 | |
322 */ | |
323 UBool operator!=(const TimeZone& that) const {return !operator==(that);} | |
324 | |
325 /** | |
326 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseco
nds to add | |
327 * to GMT to get local time in this time zone, taking daylight savings time
into | |
328 * account) as of a particular reference date. The reference date is used t
o determine | |
329 * whether daylight savings time is in effect and needs to be figured into t
he offset | |
330 * that is returned (in other words, what is the adjusted GMT offset in this
time zone | |
331 * at this particular date and time?). For the time zones produced by creat
eTimeZone(), | |
332 * the reference data is specified according to the Gregorian calendar, and
the date | |
333 * and time fields are local standard time. | |
334 * | |
335 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) ov
erload, | |
336 * which returns both the raw and the DST offset for a given time. This meth
od | |
337 * is retained only for backward compatibility. | |
338 * | |
339 * @param era The reference date's era | |
340 * @param year The reference date's year | |
341 * @param month The reference date's month (0-based; 0 is January) | |
342 * @param day The reference date's day-in-month (1-based) | |
343 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) | |
344 * @param millis The reference date's milliseconds in day, local standar
d time | |
345 * @param status Output param to filled in with a success or an error. | |
346 * @return The offset in milliseconds to add to GMT to get local t
ime. | |
347 * @stable ICU 2.0 | |
348 */ | |
349 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t
day, | |
350 uint8_t dayOfWeek, int32_t millis, UErrorCode& sta
tus) const = 0; | |
351 | |
352 /** | |
353 * Gets the time zone offset, for current date, modified in case of | |
354 * daylight savings. This is the offset to add *to* UTC to get local time. | |
355 * | |
356 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) ov
erload, | |
357 * which returns both the raw and the DST offset for a given time. This meth
od | |
358 * is retained only for backward compatibility. | |
359 * | |
360 * @param era the era of the given date. | |
361 * @param year the year in the given date. | |
362 * @param month the month in the given date. | |
363 * Month is 0-based. e.g., 0 for January. | |
364 * @param day the day-in-month of the given date. | |
365 * @param dayOfWeek the day-of-week of the given date. | |
366 * @param milliseconds the millis in day in <em>standard</em> local time. | |
367 * @param monthLength the length of the given month in days. | |
368 * @param status Output param to filled in with a success or an error. | |
369 * @return the offset to add *to* GMT to get local time. | |
370 * @stable ICU 2.0 | |
371 */ | |
372 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t
day, | |
373 uint8_t dayOfWeek, int32_t milliseconds, | |
374 int32_t monthLength, UErrorCode& status) const = 0; | |
375 | |
376 /** | |
377 * Returns the time zone raw and GMT offset for the given moment | |
378 * in time. Upon return, local-millis = GMT-millis + rawOffset + | |
379 * dstOffset. All computations are performed in the proleptic | |
380 * Gregorian calendar. The default implementation in the TimeZone | |
381 * class delegates to the 8-argument getOffset(). | |
382 * | |
383 * @param date moment in time for which to return offsets, in | |
384 * units of milliseconds from January 1, 1970 0:00 GMT, either GMT | |
385 * time or local wall time, depending on `local'. | |
386 * @param local if true, `date' is local wall time; otherwise it | |
387 * is in GMT time. | |
388 * @param rawOffset output parameter to receive the raw offset, that | |
389 * is, the offset not including DST adjustments | |
390 * @param dstOffset output parameter to receive the DST offset, | |
391 * that is, the offset to be added to `rawOffset' to obtain the | |
392 * total offset between local and GMT time. If DST is not in | |
393 * effect, this value is zero; otherwise it is a positive value, | |
394 * typically one hour. | |
395 * @param ec input-output error code | |
396 * | |
397 * @stable ICU 2.8 | |
398 */ | |
399 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset, | |
400 int32_t& dstOffset, UErrorCode& ec) const; | |
401 | |
402 /** | |
403 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to a
dd | |
404 * to GMT to get local time, before taking daylight savings time into accoun
t). | |
405 * | |
406 * @param offsetMillis The new raw GMT offset for this time zone. | |
407 * @stable ICU 2.0 | |
408 */ | |
409 virtual void setRawOffset(int32_t offsetMillis) = 0; | |
410 | |
411 /** | |
412 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds t
o add | |
413 * to GMT to get local time, before taking daylight savings time into accoun
t). | |
414 * | |
415 * @return The TimeZone's raw GMT offset. | |
416 * @stable ICU 2.0 | |
417 */ | |
418 virtual int32_t getRawOffset(void) const = 0; | |
419 | |
420 /** | |
421 * Fills in "ID" with the TimeZone's ID. | |
422 * | |
423 * @param ID Receives this TimeZone's ID. | |
424 * @return A reference to 'ID' | |
425 * @stable ICU 2.0 | |
426 */ | |
427 UnicodeString& getID(UnicodeString& ID) const; | |
428 | |
429 /** | |
430 * Sets the TimeZone's ID to the specified value. This doesn't affect any o
ther | |
431 * fields (for example, if you say< | |
432 * blockquote><pre> | |
433 * . TimeZone* foo = TimeZone::createTimeZone("America/New_York"); | |
434 * . foo.setID("America/Los_Angeles"); | |
435 * </pre>\htmlonly</blockquote>\endhtmlonly | |
436 * the time zone's GMT offset and daylight-savings rules don't change to tho
se for | |
437 * Los Angeles. They're still those for New York. Only the ID has changed.
) | |
438 * | |
439 * @param ID The new time zone ID. | |
440 * @stable ICU 2.0 | |
441 */ | |
442 void setID(const UnicodeString& ID); | |
443 | |
444 /** | |
445 * Enum for use with getDisplayName | |
446 * @stable ICU 2.4 | |
447 */ | |
448 enum EDisplayType { | |
449 /** | |
450 * Selector for short display name | |
451 * @stable ICU 2.4 | |
452 */ | |
453 SHORT = 1, | |
454 /** | |
455 * Selector for long display name | |
456 * @stable ICU 2.4 | |
457 */ | |
458 LONG, | |
459 /** | |
460 * Selector for short generic display name | |
461 * @stable ICU 4.4 | |
462 */ | |
463 SHORT_GENERIC, | |
464 /** | |
465 * Selector for long generic display name | |
466 * @stable ICU 4.4 | |
467 */ | |
468 LONG_GENERIC, | |
469 /** | |
470 * Selector for short display name derived | |
471 * from time zone offset | |
472 * @stable ICU 4.4 | |
473 */ | |
474 SHORT_GMT, | |
475 /** | |
476 * Selector for long display name derived | |
477 * from time zone offset | |
478 * @stable ICU 4.4 | |
479 */ | |
480 LONG_GMT, | |
481 /** | |
482 * Selector for short display name derived | |
483 * from the time zone's fallback name | |
484 * @stable ICU 4.4 | |
485 */ | |
486 SHORT_COMMONLY_USED, | |
487 /** | |
488 * Selector for long display name derived | |
489 * from the time zone's fallback name | |
490 * @stable ICU 4.4 | |
491 */ | |
492 GENERIC_LOCATION | |
493 }; | |
494 | |
495 /** | |
496 * Returns a name of this time zone suitable for presentation to the user | |
497 * in the default locale. | |
498 * This method returns the long name, not including daylight savings. | |
499 * If the display name is not available for the locale, | |
500 * then this method returns a string in the format | |
501 * <code>GMT[+-]hh:mm</code>. | |
502 * @param result the human-readable name of this time zone in the default lo
cale. | |
503 * @return A reference to 'result'. | |
504 * @stable ICU 2.0 | |
505 */ | |
506 UnicodeString& getDisplayName(UnicodeString& result) const; | |
507 | |
508 /** | |
509 * Returns a name of this time zone suitable for presentation to the user | |
510 * in the specified locale. | |
511 * This method returns the long name, not including daylight savings. | |
512 * If the display name is not available for the locale, | |
513 * then this method returns a string in the format | |
514 * <code>GMT[+-]hh:mm</code>. | |
515 * @param locale the locale in which to supply the display name. | |
516 * @param result the human-readable name of this time zone in the given loca
le | |
517 * or in the default locale if the given locale is not recogni
zed. | |
518 * @return A reference to 'result'. | |
519 * @stable ICU 2.0 | |
520 */ | |
521 UnicodeString& getDisplayName(const Locale& locale, UnicodeString& result) c
onst; | |
522 | |
523 /** | |
524 * Returns a name of this time zone suitable for presentation to the user | |
525 * in the default locale. | |
526 * If the display name is not available for the locale, | |
527 * then this method returns a string in the format | |
528 * <code>GMT[+-]hh:mm</code>. | |
529 * @param daylight if true, return the daylight savings name. | |
530 * @param style | |
531 * @param result the human-readable name of this time zone in the default lo
cale. | |
532 * @return A reference to 'result'. | |
533 * @stable ICU 2.0 | |
534 */ | |
535 UnicodeString& getDisplayName(UBool daylight, EDisplayType style, UnicodeStr
ing& result) const; | |
536 | |
537 /** | |
538 * Returns a name of this time zone suitable for presentation to the user | |
539 * in the specified locale. | |
540 * If the display name is not available for the locale, | |
541 * then this method returns a string in the format | |
542 * <code>GMT[+-]hh:mm</code>. | |
543 * @param daylight if true, return the daylight savings name. | |
544 * @param style | |
545 * @param locale the locale in which to supply the display name. | |
546 * @param result the human-readable name of this time zone in the given loca
le | |
547 * or in the default locale if the given locale is not recogni
zed. | |
548 * @return A refence to 'result'. | |
549 * @stable ICU 2.0 | |
550 */ | |
551 UnicodeString& getDisplayName(UBool daylight, EDisplayType style, const Loca
le& locale, UnicodeString& result) const; | |
552 | |
553 /** | |
554 * Queries if this time zone uses daylight savings time. | |
555 * @return true if this time zone uses daylight savings time, | |
556 * false, otherwise. | |
557 * @stable ICU 2.0 | |
558 */ | |
559 virtual UBool useDaylightTime(void) const = 0; | |
560 | |
561 /** | |
562 * Queries if the given date is in daylight savings time in | |
563 * this time zone. | |
564 * This method is wasteful since it creates a new GregorianCalendar and | |
565 * deletes it each time it is called. This is a deprecated method | |
566 * and provided only for Java compatibility. | |
567 * | |
568 * @param date the given UDate. | |
569 * @param status Output param filled in with success/error code. | |
570 * @return true if the given date is in daylight savings time, | |
571 * false, otherwise. | |
572 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead. | |
573 */ | |
574 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const = 0; | |
575 | |
576 /** | |
577 * Returns true if this zone has the same rule and offset as another zone. | |
578 * That is, if this zone differs only in ID, if at all. | |
579 * @param other the <code>TimeZone</code> object to be compared with | |
580 * @return true if the given zone is the same as this one, | |
581 * with the possible exception of the ID | |
582 * @stable ICU 2.0 | |
583 */ | |
584 virtual UBool hasSameRules(const TimeZone& other) const; | |
585 | |
586 /** | |
587 * Clones TimeZone objects polymorphically. Clients are responsible for dele
ting | |
588 * the TimeZone object cloned. | |
589 * | |
590 * @return A new copy of this TimeZone object. | |
591 * @stable ICU 2.0 | |
592 */ | |
593 virtual TimeZone* clone(void) const = 0; | |
594 | |
595 /** | |
596 * Return the class ID for this class. This is useful only for | |
597 * comparing to a return value from getDynamicClassID(). | |
598 * @return The class ID for all objects of this class. | |
599 * @stable ICU 2.0 | |
600 */ | |
601 static UClassID U_EXPORT2 getStaticClassID(void); | |
602 | |
603 /** | |
604 * Returns a unique class ID POLYMORPHICALLY. This method is to | |
605 * implement a simple version of RTTI, since not all C++ compilers support g
enuine | |
606 * RTTI. Polymorphic operator==() and clone() methods call this method. | |
607 * <P> | |
608 * Concrete subclasses of TimeZone must use the UOBJECT_DEFINE_RTTI_IMPLEMEN
TATION | |
609 * macro from uobject.h in their implementation to provide correct RTTI inf
ormation. | |
610 * @return The class ID for this object. All objects of a given class have
the | |
611 * same class ID. Objects of other classes have different class ID
s. | |
612 * @stable ICU 2.0 | |
613 */ | |
614 virtual UClassID getDynamicClassID(void) const = 0; | |
615 | |
616 /** | |
617 * Returns the amount of time to be added to local standard time | |
618 * to get local wall clock time. | |
619 * <p> | |
620 * The default implementation always returns 3600000 milliseconds | |
621 * (i.e., one hour) if this time zone observes Daylight Saving | |
622 * Time. Otherwise, 0 (zero) is returned. | |
623 * <p> | |
624 * If an underlying TimeZone implementation subclass supports | |
625 * historical Daylight Saving Time changes, this method returns | |
626 * the known latest daylight saving value. | |
627 * | |
628 * @return the amount of saving time in milliseconds | |
629 * @stable ICU 3.6 | |
630 */ | |
631 virtual int32_t getDSTSavings() const; | |
632 | |
633 protected: | |
634 | |
635 /** | |
636 * Default constructor. ID is initialized to the empty string. | |
637 * @stable ICU 2.0 | |
638 */ | |
639 TimeZone(); | |
640 | |
641 /** | |
642 * Construct a TimeZone with a given ID. | |
643 * @param id a system time zone ID | |
644 * @stable ICU 2.0 | |
645 */ | |
646 TimeZone(const UnicodeString &id); | |
647 | |
648 /** | |
649 * Copy constructor. | |
650 * @param source the object to be copied. | |
651 * @stable ICU 2.0 | |
652 */ | |
653 TimeZone(const TimeZone& source); | |
654 | |
655 /** | |
656 * Default assignment operator. | |
657 * @param right the object to be copied. | |
658 * @stable ICU 2.0 | |
659 */ | |
660 TimeZone& operator=(const TimeZone& right); | |
661 | |
662 /** | |
663 * Utility function. For internally loading rule data. | |
664 * @param top Top resource bundle for tz data | |
665 * @param ruleid ID of rule to load | |
666 * @param oldbundle Old bundle to reuse or NULL | |
667 * @param status Status parameter | |
668 * @return either a new bundle or *oldbundle | |
669 * @internal | |
670 */ | |
671 static UResourceBundle* loadRule(const UResourceBundle* top, const UnicodeSt
ring& ruleid, UResourceBundle* oldbundle, UErrorCode&status); | |
672 | |
673 private: | |
674 friend class ZoneMeta; | |
675 | |
676 | |
677 static TimeZone* createCustomTimeZone(const UnicodeString&); // Creat
es a time zone based on the string. | |
678 | |
679 /** | |
680 * Resolve a link in Olson tzdata. When the given id is known and it's not
a link, | |
681 * the id itself is returned. When the given id is known and it is a link,
then | |
682 * dereferenced zone id is returned. When the given id is unknown, then it
returns | |
683 * NULL. | |
684 * @param id zone id string | |
685 * @return the dereferenced zone or NULL | |
686 */ | |
687 static const UChar* dereferOlsonLink(const UnicodeString& id); | |
688 | |
689 /** | |
690 * Returns the region code associated with the given zone. | |
691 * @param id zone id string | |
692 * @return the region associated with the given zone | |
693 */ | |
694 static const UChar* getRegion(const UnicodeString& id); | |
695 | |
696 /** | |
697 * Parses the given custom time zone identifier | |
698 * @param id id A string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or | |
699 * GMT[+-]hh. | |
700 * @param sign Receves parsed sign, 1 for positive, -1 for negative. | |
701 * @param hour Receives parsed hour field | |
702 * @param minute Receives parsed minute field | |
703 * @param second Receives parsed second field | |
704 * @return Returns TRUE when the given custom id is valid. | |
705 */ | |
706 static UBool parseCustomID(const UnicodeString& id, int32_t& sign, int32_t&
hour, | |
707 int32_t& min, int32_t& sec); | |
708 | |
709 /** | |
710 * Parse a custom time zone identifier and return the normalized | |
711 * custom time zone identifier for the given custom id string. | |
712 * @param id a string of the form GMT[+-]hh:mm, GMT[+-]hhmm, or | |
713 * GMT[+-]hh. | |
714 * @param normalized Receives the normalized custom ID | |
715 * @param status Receives the status. When the input ID string is invalid, | |
716 * U_ILLEGAL_ARGUMENT_ERROR is set. | |
717 * @return The normalized custom id string. | |
718 */ | |
719 static UnicodeString& getCustomID(const UnicodeString& id, UnicodeString& no
rmalized, | |
720 UErrorCode& status); | |
721 | |
722 /** | |
723 * Returns the normalized custome time zone ID for the given offset fields. | |
724 * @param hour offset hours | |
725 * @param min offset minutes | |
726 * @param sec offset seconds | |
727 * @param netative sign of the offset, TRUE for negative offset. | |
728 * @param id Receves the format result (normalized custom ID) | |
729 * @return The reference to id | |
730 */ | |
731 static UnicodeString& formatCustomID(int32_t hour, int32_t min, int32_t sec, | |
732 UBool negative, UnicodeString& id); | |
733 | |
734 /** | |
735 * Responsible for setting up DEFAULT_ZONE. Uses routines in TPlatformUtili
ties | |
736 * (i.e., platform-specific calls) to get the current system time zone. Fai
ling | |
737 * that, uses the platform-specific default time zone. Failing that, uses G
MT. | |
738 */ | |
739 static void initDefault(void); | |
740 | |
741 // See source file for documentation | |
742 /** | |
743 * Lookup the given name in our system zone table. If found, | |
744 * instantiate a new zone of that name and return it. If not | |
745 * found, return 0. | |
746 * @param name tthe given name of a system time zone. | |
747 * @return the TimeZone indicated by the 'name'. | |
748 */ | |
749 static TimeZone* createSystemTimeZone(const UnicodeString& name); | |
750 | |
751 UnicodeString fID; // this time zone's ID | |
752 | |
753 }; | |
754 | |
755 | |
756 // ------------------------------------- | |
757 | |
758 inline UnicodeString& | |
759 TimeZone::getID(UnicodeString& ID) const | |
760 { | |
761 ID = fID; | |
762 return ID; | |
763 } | |
764 | |
765 // ------------------------------------- | |
766 | |
767 inline void | |
768 TimeZone::setID(const UnicodeString& ID) | |
769 { | |
770 fID = ID; | |
771 } | |
772 U_NAMESPACE_END | |
773 | |
774 #endif /* #if !UCONFIG_NO_FORMATTING */ | |
775 | |
776 #endif //_TIMEZONE | |
777 //eof | |
OLD | NEW |