]>
Commit | Line | Data |
---|---|---|
46f4442e A |
1 | /* |
2 | ******************************************************************************* | |
3 | * Copyright (C) 2007-2008, International Business Machines Corporation and * | |
4 | * others. All Rights Reserved. * | |
5 | ******************************************************************************* | |
6 | */ | |
7 | #ifndef VTZONE_H | |
8 | #define VTZONE_H | |
9 | ||
10 | #include "unicode/utypes.h" | |
11 | ||
12 | /** | |
13 | * \file | |
14 | * \brief C++ API: RFC2445 VTIMEZONE support | |
15 | */ | |
16 | ||
17 | #if !UCONFIG_NO_FORMATTING | |
18 | ||
19 | #include "unicode/basictz.h" | |
20 | ||
21 | U_NAMESPACE_BEGIN | |
22 | ||
23 | class VTZWriter; | |
24 | class VTZReader; | |
25 | class UVector; | |
26 | ||
27 | /** | |
28 | * <code>VTimeZone</code> is a class implementing RFC2445 VTIMEZONE. You can create a | |
29 | * <code>VTimeZone</code> instance from a time zone ID supported by <code>TimeZone</code>. | |
30 | * With the <code>VTimeZone</code> instance created from the ID, you can write out the rule | |
31 | * in RFC2445 VTIMEZONE format. Also, you can create a <code>VTimeZone</code> instance | |
32 | * from RFC2445 VTIMEZONE data stream, which allows you to calculate time | |
33 | * zone offset by the rules defined by the data.<br><br> | |
34 | * Note: The consumer of this class reading or writing VTIMEZONE data is responsible to | |
35 | * decode or encode Non-ASCII text. Methods reading/writing VTIMEZONE data in this class | |
36 | * do nothing with MIME encoding. | |
37 | * @stable ICU 4.0 | |
38 | */ | |
39 | class U_I18N_API VTimeZone : public BasicTimeZone { | |
40 | public: | |
41 | /** | |
42 | * Copy constructor. | |
43 | * @param source The <code>VTimeZone</code> object to be copied. | |
44 | * @stable ICU 4.0 | |
45 | */ | |
46 | VTimeZone(const VTimeZone& source); | |
47 | ||
48 | /** | |
49 | * Destructor. | |
50 | * @stable ICU 4.0 | |
51 | */ | |
52 | virtual ~VTimeZone(); | |
53 | ||
54 | /** | |
55 | * Assignment operator. | |
56 | * @param right The object to be copied. | |
57 | * @stable ICU 4.0 | |
58 | */ | |
59 | VTimeZone& operator=(const VTimeZone& right); | |
60 | ||
61 | /** | |
62 | * Return true if the given <code>TimeZone</code> objects are | |
63 | * semantically equal. Objects of different subclasses are considered unequal. | |
64 | * @param that The object to be compared with. | |
65 | * @return true if the given <code>TimeZone</code> objects are | |
66 | *semantically equal. | |
67 | * @stable ICU 4.0 | |
68 | */ | |
69 | virtual UBool operator==(const TimeZone& that) const; | |
70 | ||
71 | /** | |
72 | * Return true if the given <code>TimeZone</code> objects are | |
73 | * semantically unequal. Objects of different subclasses are considered unequal. | |
74 | * @param that The object to be compared with. | |
75 | * @return true if the given <code>TimeZone</code> objects are | |
76 | * semantically unequal. | |
77 | * @stable ICU 4.0 | |
78 | */ | |
79 | virtual UBool operator!=(const TimeZone& that) const; | |
80 | ||
81 | /** | |
82 | * Create a <code>VTimeZone</code> instance by the time zone ID. | |
83 | * @param ID The time zone ID, such as America/New_York | |
84 | * @return A <code>VTimeZone</code> object initialized by the time zone ID, | |
85 | * or NULL when the ID is unknown. | |
86 | * @stable ICU 4.0 | |
87 | */ | |
88 | static VTimeZone* createVTimeZoneByID(const UnicodeString& ID); | |
89 | ||
90 | /** | |
91 | * Create a <code>VTimeZone</code> instance by RFC2445 VTIMEZONE data | |
92 | * | |
93 | * @param vtzdata The string including VTIMEZONE data block | |
94 | * @param status Output param to filled in with a success or an error. | |
95 | * @return A <code>VTimeZone</code> initialized by the VTIMEZONE data or | |
96 | * NULL if failed to load the rule from the VTIMEZONE data. | |
97 | * @stable ICU 4.0 | |
98 | */ | |
99 | static VTimeZone* createVTimeZone(const UnicodeString& vtzdata, UErrorCode& status); | |
100 | ||
101 | /** | |
102 | * Gets the RFC2445 TZURL property value. When a <code>VTimeZone</code> instance was | |
103 | * created from VTIMEZONE data, the initial value is set by the TZURL property value | |
104 | * in the data. Otherwise, the initial value is not set. | |
105 | * @param url Receives the RFC2445 TZURL property value. | |
106 | * @return TRUE if TZURL attribute is available and value is set. | |
107 | * @stable ICU 4.0 | |
108 | */ | |
109 | UBool getTZURL(UnicodeString& url) const; | |
110 | ||
111 | /** | |
112 | * Sets the RFC2445 TZURL property value. | |
113 | * @param url The TZURL property value. | |
114 | * @stable ICU 4.0 | |
115 | */ | |
116 | void setTZURL(const UnicodeString& url); | |
117 | ||
118 | /** | |
119 | * Gets the RFC2445 LAST-MODIFIED property value. When a <code>VTimeZone</code> instance | |
120 | * was created from VTIMEZONE data, the initial value is set by the LAST-MODIFIED property | |
121 | * value in the data. Otherwise, the initial value is not set. | |
122 | * @param lastModified Receives the last modified date. | |
123 | * @return TRUE if lastModified attribute is available and value is set. | |
124 | * @stable ICU 4.0 | |
125 | */ | |
126 | UBool getLastModified(UDate& lastModified) const; | |
127 | ||
128 | /** | |
129 | * Sets the RFC2445 LAST-MODIFIED property value. | |
130 | * @param lastModified The LAST-MODIFIED date. | |
131 | * @stable ICU 4.0 | |
132 | */ | |
133 | void setLastModified(UDate lastModified); | |
134 | ||
135 | /** | |
136 | * Writes RFC2445 VTIMEZONE data for this time zone | |
137 | * @param result Output param to filled in with the VTIMEZONE data. | |
138 | * @param status Output param to filled in with a success or an error. | |
139 | * @stable ICU 4.0 | |
140 | */ | |
141 | void write(UnicodeString& result, UErrorCode& status) const; | |
142 | ||
143 | /** | |
144 | * Writes RFC2445 VTIMEZONE data for this time zone applicalbe | |
145 | * for dates after the specified start time. | |
146 | * @param start The start date. | |
147 | * @param result Output param to filled in with the VTIMEZONE data. | |
148 | * @param status Output param to filled in with a success or an error. | |
149 | * @stable ICU 4.0 | |
150 | */ | |
151 | void write(UDate start, UnicodeString& result, UErrorCode& status) /*const*/; | |
152 | ||
153 | /** | |
154 | * Writes RFC2445 VTIMEZONE data applicalbe for the specified date. | |
155 | * Some common iCalendar implementations can only handle a single time | |
156 | * zone property or a pair of standard and daylight time properties using | |
157 | * BYDAY rule with day of week (such as BYDAY=1SUN). This method produce | |
158 | * the VTIMEZONE data which can be handled these implementations. The rules | |
159 | * produced by this method can be used only for calculating time zone offset | |
160 | * around the specified date. | |
161 | * @param time The date used for rule extraction. | |
162 | * @param result Output param to filled in with the VTIMEZONE data. | |
163 | * @param status Output param to filled in with a success or an error. | |
164 | * @stable ICU 4.0 | |
165 | */ | |
166 | void writeSimple(UDate time, UnicodeString& result, UErrorCode& status) /*const*/; | |
167 | ||
168 | /** | |
169 | * Clones TimeZone objects polymorphically. Clients are responsible for deleting | |
170 | * the TimeZone object cloned. | |
171 | * @return A new copy of this TimeZone object. | |
172 | * @stable ICU 4.0 | |
173 | */ | |
174 | virtual TimeZone* clone(void) const; | |
175 | ||
176 | /** | |
177 | * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add | |
178 | * to GMT to get local time in this time zone, taking daylight savings time into | |
179 | * account) as of a particular reference date. The reference date is used to determine | |
180 | * whether daylight savings time is in effect and needs to be figured into the offset | |
181 | * that is returned (in other words, what is the adjusted GMT offset in this time zone | |
182 | * at this particular date and time?). For the time zones produced by createTimeZone(), | |
183 | * the reference data is specified according to the Gregorian calendar, and the date | |
184 | * and time fields are local standard time. | |
185 | * | |
186 | * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, | |
187 | * which returns both the raw and the DST offset for a given time. This method | |
188 | * is retained only for backward compatibility. | |
189 | * | |
190 | * @param era The reference date's era | |
191 | * @param year The reference date's year | |
192 | * @param month The reference date's month (0-based; 0 is January) | |
193 | * @param day The reference date's day-in-month (1-based) | |
194 | * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) | |
195 | * @param millis The reference date's milliseconds in day, local standard time | |
196 | * @param status Output param to filled in with a success or an error. | |
197 | * @return The offset in milliseconds to add to GMT to get local time. | |
198 | * @stable ICU 4.0 | |
199 | */ | |
200 | virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, | |
201 | uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const; | |
202 | ||
203 | /** | |
204 | * Gets the time zone offset, for current date, modified in case of | |
205 | * daylight savings. This is the offset to add *to* UTC to get local time. | |
206 | * | |
207 | * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload, | |
208 | * which returns both the raw and the DST offset for a given time. This method | |
209 | * is retained only for backward compatibility. | |
210 | * | |
211 | * @param era The reference date's era | |
212 | * @param year The reference date's year | |
213 | * @param month The reference date's month (0-based; 0 is January) | |
214 | * @param day The reference date's day-in-month (1-based) | |
215 | * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) | |
216 | * @param millis The reference date's milliseconds in day, local standard time | |
217 | * @param monthLength The length of the given month in days. | |
218 | * @param status Output param to filled in with a success or an error. | |
219 | * @return The offset in milliseconds to add to GMT to get local time. | |
220 | * @stable ICU 4.0 | |
221 | */ | |
222 | virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, | |
223 | uint8_t dayOfWeek, int32_t millis, | |
224 | int32_t monthLength, UErrorCode& status) const; | |
225 | ||
226 | /** | |
227 | * Returns the time zone raw and GMT offset for the given moment | |
228 | * in time. Upon return, local-millis = GMT-millis + rawOffset + | |
229 | * dstOffset. All computations are performed in the proleptic | |
230 | * Gregorian calendar. The default implementation in the TimeZone | |
231 | * class delegates to the 8-argument getOffset(). | |
232 | * | |
233 | * @param date moment in time for which to return offsets, in | |
234 | * units of milliseconds from January 1, 1970 0:00 GMT, either GMT | |
235 | * time or local wall time, depending on `local'. | |
236 | * @param local if true, `date' is local wall time; otherwise it | |
237 | * is in GMT time. | |
238 | * @param rawOffset output parameter to receive the raw offset, that | |
239 | * is, the offset not including DST adjustments | |
240 | * @param dstOffset output parameter to receive the DST offset, | |
241 | * that is, the offset to be added to `rawOffset' to obtain the | |
242 | * total offset between local and GMT time. If DST is not in | |
243 | * effect, this value is zero; otherwise it is a positive value, | |
244 | * typically one hour. | |
245 | * @param ec input-output error code | |
246 | * @stable ICU 4.0 | |
247 | */ | |
248 | virtual void getOffset(UDate date, UBool local, int32_t& rawOffset, | |
249 | int32_t& dstOffset, UErrorCode& ec) const; | |
250 | ||
251 | /** | |
252 | * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add | |
253 | * to GMT to get local time, before taking daylight savings time into account). | |
254 | * | |
255 | * @param offsetMillis The new raw GMT offset for this time zone. | |
256 | * @stable ICU 4.0 | |
257 | */ | |
258 | virtual void setRawOffset(int32_t offsetMillis); | |
259 | ||
260 | /** | |
261 | * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add | |
262 | * to GMT to get local time, before taking daylight savings time into account). | |
263 | * | |
264 | * @return The TimeZone's raw GMT offset. | |
265 | * @stable ICU 4.0 | |
266 | */ | |
267 | virtual int32_t getRawOffset(void) const; | |
268 | ||
269 | /** | |
270 | * Queries if this time zone uses daylight savings time. | |
271 | * @return true if this time zone uses daylight savings time, | |
272 | * false, otherwise. | |
273 | * @stable ICU 4.0 | |
274 | */ | |
275 | virtual UBool useDaylightTime(void) const; | |
276 | ||
277 | /** | |
278 | * Queries if the given date is in daylight savings time in | |
279 | * this time zone. | |
280 | * This method is wasteful since it creates a new GregorianCalendar and | |
281 | * deletes it each time it is called. This is a deprecated method | |
282 | * and provided only for Java compatibility. | |
283 | * | |
284 | * @param date the given UDate. | |
285 | * @param status Output param filled in with success/error code. | |
286 | * @return true if the given date is in daylight savings time, | |
287 | * false, otherwise. | |
288 | * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead. | |
289 | */ | |
290 | virtual UBool inDaylightTime(UDate date, UErrorCode& status) const; | |
291 | ||
292 | /** | |
293 | * Returns true if this zone has the same rule and offset as another zone. | |
294 | * That is, if this zone differs only in ID, if at all. | |
295 | * @param other the <code>TimeZone</code> object to be compared with | |
296 | * @return true if the given zone is the same as this one, | |
297 | * with the possible exception of the ID | |
298 | * @stable ICU 4.0 | |
299 | */ | |
300 | virtual UBool hasSameRules(const TimeZone& other) const; | |
301 | ||
302 | /** | |
303 | * Gets the first time zone transition after the base time. | |
304 | * @param base The base time. | |
305 | * @param inclusive Whether the base time is inclusive or not. | |
306 | * @param result Receives the first transition after the base time. | |
307 | * @return TRUE if the transition is found. | |
308 | * @stable ICU 4.0 | |
309 | */ | |
310 | virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) /*const*/; | |
311 | ||
312 | /** | |
313 | * Gets the most recent time zone transition before the base time. | |
314 | * @param base The base time. | |
315 | * @param inclusive Whether the base time is inclusive or not. | |
316 | * @param result Receives the most recent transition before the base time. | |
317 | * @return TRUE if the transition is found. | |
318 | * @stable ICU 4.0 | |
319 | */ | |
320 | virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) /*const*/; | |
321 | ||
322 | /** | |
323 | * Returns the number of <code>TimeZoneRule</code>s which represents time transitions, | |
324 | * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except | |
325 | * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value. | |
326 | * @param status Receives error status code. | |
327 | * @return The number of <code>TimeZoneRule</code>s representing time transitions. | |
328 | * @stable ICU 4.0 | |
329 | */ | |
330 | virtual int32_t countTransitionRules(UErrorCode& status) /*const*/; | |
331 | ||
332 | /** | |
333 | * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code> | |
334 | * which represent time transitions for this time zone. On successful return, | |
335 | * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and | |
336 | * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code> | |
337 | * instances up to the size specified by trscount. The results are referencing the | |
338 | * rule instance held by this time zone instance. Therefore, after this time zone | |
339 | * is destructed, they are no longer available. | |
340 | * @param initial Receives the initial timezone rule | |
341 | * @param trsrules Receives the timezone transition rules | |
342 | * @param trscount On input, specify the size of the array 'transitions' receiving | |
343 | * the timezone transition rules. On output, actual number of | |
344 | * rules filled in the array will be set. | |
345 | * @param status Receives error status code. | |
346 | * @stable ICU 4.0 | |
347 | */ | |
348 | virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial, | |
349 | const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) /*const*/; | |
350 | ||
351 | private: | |
352 | enum { DEFAULT_VTIMEZONE_LINES = 100 }; | |
353 | ||
354 | /** | |
355 | * Default constructor. | |
356 | */ | |
357 | VTimeZone(); | |
358 | static VTimeZone* createVTimeZone(VTZReader* reader); | |
359 | void write(VTZWriter& writer, UErrorCode& status) const; | |
360 | void write(UDate start, VTZWriter& writer, UErrorCode& status) /*const*/; | |
361 | void writeSimple(UDate time, VTZWriter& writer, UErrorCode& status) /*const*/; | |
362 | void load(VTZReader& reader, UErrorCode& status); | |
363 | void parse(UErrorCode& status); | |
364 | ||
365 | void writeZone(VTZWriter& w, BasicTimeZone& basictz, UVector* customProps, | |
366 | UErrorCode& status) const; | |
367 | ||
368 | void writeHeaders(VTZWriter& w, UErrorCode& status) const; | |
369 | void writeFooter(VTZWriter& writer, UErrorCode& status) const; | |
370 | ||
371 | void writeZonePropsByTime(VTZWriter& writer, UBool isDst, const UnicodeString& tzname, | |
372 | int32_t fromOffset, int32_t toOffset, UDate time, UBool withRDATE, | |
373 | UErrorCode& status) const; | |
374 | void writeZonePropsByDOM(VTZWriter& writer, UBool isDst, const UnicodeString& tzname, | |
375 | int32_t fromOffset, int32_t toOffset, | |
376 | int32_t month, int32_t dayOfMonth, UDate startTime, UDate untilTime, | |
377 | UErrorCode& status) const; | |
378 | void writeZonePropsByDOW(VTZWriter& writer, UBool isDst, const UnicodeString& tzname, | |
379 | int32_t fromOffset, int32_t toOffset, | |
380 | int32_t month, int32_t weekInMonth, int32_t dayOfWeek, | |
381 | UDate startTime, UDate untilTime, UErrorCode& status) const; | |
382 | void writeZonePropsByDOW_GEQ_DOM(VTZWriter& writer, UBool isDst, const UnicodeString& tzname, | |
383 | int32_t fromOffset, int32_t toOffset, | |
384 | int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, | |
385 | UDate startTime, UDate untilTime, UErrorCode& status) const; | |
386 | void writeZonePropsByDOW_GEQ_DOM_sub(VTZWriter& writer, int32_t month, int32_t dayOfMonth, | |
387 | int32_t dayOfWeek, int32_t numDays, | |
388 | UDate untilTime, int32_t fromOffset, UErrorCode& status) const; | |
389 | void writeZonePropsByDOW_LEQ_DOM(VTZWriter& writer, UBool isDst, const UnicodeString& tzname, | |
390 | int32_t fromOffset, int32_t toOffset, | |
391 | int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, | |
392 | UDate startTime, UDate untilTime, UErrorCode& status) const; | |
393 | void writeFinalRule(VTZWriter& writer, UBool isDst, const AnnualTimeZoneRule* rule, | |
394 | int32_t fromRawOffset, int32_t fromDSTSavings, | |
395 | UDate startTime, UErrorCode& status) const; | |
396 | ||
397 | void beginZoneProps(VTZWriter& writer, UBool isDst, const UnicodeString& tzname, | |
398 | int32_t fromOffset, int32_t toOffset, UDate startTime, UErrorCode& status) const; | |
399 | void endZoneProps(VTZWriter& writer, UBool isDst, UErrorCode& status) const; | |
400 | void beginRRULE(VTZWriter& writer, int32_t month, UErrorCode& status) const; | |
401 | void appendUNTIL(VTZWriter& writer, const UnicodeString& until, UErrorCode& status) const; | |
402 | ||
403 | BasicTimeZone *tz; | |
404 | UVector *vtzlines; | |
405 | UnicodeString tzurl; | |
406 | UDate lastmod; | |
407 | UnicodeString olsonzid; | |
408 | UnicodeString icutzver; | |
409 | ||
410 | public: | |
411 | /** | |
412 | * Return the class ID for this class. This is useful only for comparing to | |
413 | * a return value from getDynamicClassID(). For example: | |
414 | * <pre> | |
415 | * . Base* polymorphic_pointer = createPolymorphicObject(); | |
416 | * . if (polymorphic_pointer->getDynamicClassID() == | |
417 | * . erived::getStaticClassID()) ... | |
418 | * </pre> | |
419 | * @return The class ID for all objects of this class. | |
420 | * @stable ICU 4.0 | |
421 | */ | |
422 | static UClassID U_EXPORT2 getStaticClassID(void); | |
423 | ||
424 | /** | |
425 | * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This | |
426 | * method is to implement a simple version of RTTI, since not all C++ | |
427 | * compilers support genuine RTTI. Polymorphic operator==() and clone() | |
428 | * methods call this method. | |
429 | * | |
430 | * @return The class ID for this object. All objects of a | |
431 | * given class have the same class ID. Objects of | |
432 | * other classes have different class IDs. | |
433 | * @stable ICU 4.0 | |
434 | */ | |
435 | virtual UClassID getDynamicClassID(void) const; | |
436 | }; | |
437 | ||
438 | U_NAMESPACE_END | |
439 | ||
440 | #endif /* #if !UCONFIG_NO_FORMATTING */ | |
441 | ||
442 | #endif // VTZONE_H | |
443 | //eof |