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