OLD | NEW |
| (Empty) |
1 /* | |
2 ******************************************************************************* | |
3 * Copyright (C) 2007-2008, International Business Machines Corporation and * | |
4 * others. All Rights Reserved. * | |
5 ******************************************************************************* | |
6 */ | |
7 #ifndef RBTZ_H | |
8 #define RBTZ_H | |
9 | |
10 #include "unicode/utypes.h" | |
11 | |
12 /** | |
13 * \file | |
14 * \brief C++ API: Rule based customizable time zone | |
15 */ | |
16 | |
17 #if !UCONFIG_NO_FORMATTING | |
18 | |
19 #include "unicode/basictz.h" | |
20 #include "unicode/unistr.h" | |
21 | |
22 U_NAMESPACE_BEGIN | |
23 | |
24 // forward declaration | |
25 class UVector; | |
26 struct Transition; | |
27 | |
28 /** | |
29 * a BasicTimeZone subclass implemented in terms of InitialTimeZoneRule and Time
ZoneRule instances | |
30 * @see BasicTimeZone | |
31 * @see InitialTimeZoneRule | |
32 * @see TimeZoneRule | |
33 */ | |
34 class U_I18N_API RuleBasedTimeZone : public BasicTimeZone { | |
35 public: | |
36 /** | |
37 * Constructs a <code>RuleBasedTimeZone</code> object with the ID and the | |
38 * <code>InitialTimeZoneRule</code>. The input <code>InitialTimeZoneRule</c
ode> | |
39 * is adopted by this <code>RuleBasedTimeZone</code>, thus the caller must n
ot | |
40 * delete it. | |
41 * @param id The time zone ID. | |
42 * @param initialRule The initial time zone rule. | |
43 * @stable ICU 3.8 | |
44 */ | |
45 RuleBasedTimeZone(const UnicodeString& id, InitialTimeZoneRule* initialRule)
; | |
46 | |
47 /** | |
48 * Copy constructor. | |
49 * @param source The RuleBasedTimeZone object to be copied. | |
50 * @stable ICU 3.8 | |
51 */ | |
52 RuleBasedTimeZone(const RuleBasedTimeZone& source); | |
53 | |
54 /** | |
55 * Destructor. | |
56 * @stable ICU 3.8 | |
57 */ | |
58 virtual ~RuleBasedTimeZone(); | |
59 | |
60 /** | |
61 * Assignment operator. | |
62 * @param right The object to be copied. | |
63 * @stable ICU 3.8 | |
64 */ | |
65 RuleBasedTimeZone& operator=(const RuleBasedTimeZone& right); | |
66 | |
67 /** | |
68 * Return true if the given <code>TimeZone</code> objects are | |
69 * semantically equal. Objects of different subclasses are considered unequa
l. | |
70 * @param that The object to be compared with. | |
71 * @return true if the given <code>TimeZone</code> objects are | |
72 *semantically equal. | |
73 * @stable ICU 3.8 | |
74 */ | |
75 virtual UBool operator==(const TimeZone& that) const; | |
76 | |
77 /** | |
78 * Return true if the given <code>TimeZone</code> objects are | |
79 * semantically unequal. Objects of different subclasses are considered uneq
ual. | |
80 * @param that The object to be compared with. | |
81 * @return true if the given <code>TimeZone</code> objects are | |
82 * semantically unequal. | |
83 * @stable ICU 3.8 | |
84 */ | |
85 virtual UBool operator!=(const TimeZone& that) const; | |
86 | |
87 /** | |
88 * Adds the <code>TimeZoneRule</code> which represents time transitions. | |
89 * The <code>TimeZoneRule</code> must have start times, that is, the result | |
90 * of isTransitionRule() must be true. Otherwise, U_ILLEGAL_ARGUMENT_ERROR | |
91 * is set to the error code. | |
92 * The input <code>TimeZoneRule</code> is adopted by this | |
93 * <code>RuleBasedTimeZone</code> on successful completion of this method, | |
94 * thus, the caller must not delete it when no error is returned. | |
95 * After all rules are added, the caller must call complete() method to | |
96 * make this <code>RuleBasedTimeZone</code> ready to handle common time | |
97 * zone functions. | |
98 * @param rule The <code>TimeZoneRule</code>. | |
99 * @param status Output param to filled in with a success or an error. | |
100 * @stable ICU 3.8 | |
101 */ | |
102 void addTransitionRule(TimeZoneRule* rule, UErrorCode& status); | |
103 | |
104 /** | |
105 * Makes the <code>TimeZoneRule</code> ready to handle actual timezone | |
106 * calcuation APIs. This method collects time zone rules specified | |
107 * by the caller via the constructor and addTransitionRule() and | |
108 * builds internal structure for making the object ready to support | |
109 * time zone APIs such as getOffset(), getNextTransition() and others. | |
110 * @param status Output param to filled in with a success or an error. | |
111 * @stable ICU 3.8 | |
112 */ | |
113 void complete(UErrorCode& status); | |
114 | |
115 /** | |
116 * Clones TimeZone objects polymorphically. Clients are responsible for dele
ting | |
117 * the TimeZone object cloned. | |
118 * | |
119 * @return A new copy of this TimeZone object. | |
120 * @stable ICU 3.8 | |
121 */ | |
122 virtual TimeZone* clone(void) const; | |
123 | |
124 /** | |
125 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseco
nds to add | |
126 * to GMT to get local time in this time zone, taking daylight savings time
into | |
127 * account) as of a particular reference date. The reference date is used t
o determine | |
128 * whether daylight savings time is in effect and needs to be figured into t
he offset | |
129 * that is returned (in other words, what is the adjusted GMT offset in this
time zone | |
130 * at this particular date and time?). For the time zones produced by creat
eTimeZone(), | |
131 * the reference data is specified according to the Gregorian calendar, and
the date | |
132 * and time fields are local standard time. | |
133 * | |
134 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) ov
erload, | |
135 * which returns both the raw and the DST offset for a given time. This meth
od | |
136 * is retained only for backward compatibility. | |
137 * | |
138 * @param era The reference date's era | |
139 * @param year The reference date's year | |
140 * @param month The reference date's month (0-based; 0 is January) | |
141 * @param day The reference date's day-in-month (1-based) | |
142 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) | |
143 * @param millis The reference date's milliseconds in day, local standar
d time | |
144 * @param status Output param to filled in with a success or an error. | |
145 * @return The offset in milliseconds to add to GMT to get local t
ime. | |
146 * @stable ICU 3.8 | |
147 */ | |
148 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t
day, | |
149 uint8_t dayOfWeek, int32_t millis, UErrorCode& sta
tus) const; | |
150 | |
151 /** | |
152 * Gets the time zone offset, for current date, modified in case of | |
153 * daylight savings. This is the offset to add *to* UTC to get local time. | |
154 * | |
155 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) ov
erload, | |
156 * which returns both the raw and the DST offset for a given time. This meth
od | |
157 * is retained only for backward compatibility. | |
158 * | |
159 * @param era The reference date's era | |
160 * @param year The reference date's year | |
161 * @param month The reference date's month (0-based; 0 is January) | |
162 * @param day The reference date's day-in-month (1-based) | |
163 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) | |
164 * @param millis The reference date's milliseconds in day, local standar
d time | |
165 * @param monthLength The length of the given month in days. | |
166 * @param status Output param to filled in with a success or an error. | |
167 * @return The offset in milliseconds to add to GMT to get local t
ime. | |
168 * @stable ICU 3.8 | |
169 */ | |
170 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t
day, | |
171 uint8_t dayOfWeek, int32_t millis, | |
172 int32_t monthLength, UErrorCode& status) const; | |
173 | |
174 /** | |
175 * Returns the time zone raw and GMT offset for the given moment | |
176 * in time. Upon return, local-millis = GMT-millis + rawOffset + | |
177 * dstOffset. All computations are performed in the proleptic | |
178 * Gregorian calendar. The default implementation in the TimeZone | |
179 * class delegates to the 8-argument getOffset(). | |
180 * | |
181 * @param date moment in time for which to return offsets, in | |
182 * units of milliseconds from January 1, 1970 0:00 GMT, either GMT | |
183 * time or local wall time, depending on `local'. | |
184 * @param local if true, `date' is local wall time; otherwise it | |
185 * is in GMT time. | |
186 * @param rawOffset output parameter to receive the raw offset, that | |
187 * is, the offset not including DST adjustments | |
188 * @param dstOffset output parameter to receive the DST offset, | |
189 * that is, the offset to be added to `rawOffset' to obtain the | |
190 * total offset between local and GMT time. If DST is not in | |
191 * effect, this value is zero; otherwise it is a positive value, | |
192 * typically one hour. | |
193 * @param ec input-output error code | |
194 * @stable ICU 3.8 | |
195 */ | |
196 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset, | |
197 int32_t& dstOffset, UErrorCode& ec) const; | |
198 | |
199 /** | |
200 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to a
dd | |
201 * to GMT to get local time, before taking daylight savings time into accoun
t). | |
202 * | |
203 * @param offsetMillis The new raw GMT offset for this time zone. | |
204 * @stable ICU 3.8 | |
205 */ | |
206 virtual void setRawOffset(int32_t offsetMillis); | |
207 | |
208 /** | |
209 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds t
o add | |
210 * to GMT to get local time, before taking daylight savings time into accoun
t). | |
211 * | |
212 * @return The TimeZone's raw GMT offset. | |
213 * @stable ICU 3.8 | |
214 */ | |
215 virtual int32_t getRawOffset(void) const; | |
216 | |
217 /** | |
218 * Queries if this time zone uses daylight savings time. | |
219 * @return true if this time zone uses daylight savings time, | |
220 * false, otherwise. | |
221 * @stable ICU 3.8 | |
222 */ | |
223 virtual UBool useDaylightTime(void) const; | |
224 | |
225 /** | |
226 * Queries if the given date is in daylight savings time in | |
227 * this time zone. | |
228 * This method is wasteful since it creates a new GregorianCalendar and | |
229 * deletes it each time it is called. This is a deprecated method | |
230 * and provided only for Java compatibility. | |
231 * | |
232 * @param date the given UDate. | |
233 * @param status Output param filled in with success/error code. | |
234 * @return true if the given date is in daylight savings time, | |
235 * false, otherwise. | |
236 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead. | |
237 */ | |
238 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const; | |
239 | |
240 /** | |
241 * Returns true if this zone has the same rule and offset as another zone. | |
242 * That is, if this zone differs only in ID, if at all. | |
243 * @param other the <code>TimeZone</code> object to be compared with | |
244 * @return true if the given zone is the same as this one, | |
245 * with the possible exception of the ID | |
246 * @stable ICU 3.8 | |
247 */ | |
248 virtual UBool hasSameRules(const TimeZone& other) const; | |
249 | |
250 /** | |
251 * Gets the first time zone transition after the base time. | |
252 * @param base The base time. | |
253 * @param inclusive Whether the base time is inclusive or not. | |
254 * @param result Receives the first transition after the base time. | |
255 * @return TRUE if the transition is found. | |
256 * @stable ICU 3.8 | |
257 */ | |
258 virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransit
ion& result) /*const*/; | |
259 | |
260 /** | |
261 * Gets the most recent time zone transition before the base time. | |
262 * @param base The base time. | |
263 * @param inclusive Whether the base time is inclusive or not. | |
264 * @param result Receives the most recent transition before the base time
. | |
265 * @return TRUE if the transition is found. | |
266 * @stable ICU 3.8 | |
267 */ | |
268 virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTra
nsition& result) /*const*/; | |
269 | |
270 /** | |
271 * Returns the number of <code>TimeZoneRule</code>s which represents time tr
ansitions, | |
272 * for this time zone, that is, all <code>TimeZoneRule</code>s for this time
zone except | |
273 * <code>InitialTimeZoneRule</code>. The return value range is 0 or any pos
itive value. | |
274 * @param status Receives error status code. | |
275 * @return The number of <code>TimeZoneRule</code>s representing time transi
tions. | |
276 * @stable ICU 3.8 | |
277 */ | |
278 virtual int32_t countTransitionRules(UErrorCode& status) /*const*/; | |
279 | |
280 /** | |
281 * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRu
le</code> | |
282 * which represent time transitions for this time zone. On successful retur
n, | |
283 * the argument initial points to non-NULL <code>InitialTimeZoneRule</code>
and | |
284 * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code> | |
285 * instances up to the size specified by trscount. The results are referenc
ing the | |
286 * rule instance held by this time zone instance. Therefore, after this tim
e zone | |
287 * is destructed, they are no longer available. | |
288 * @param initial Receives the initial timezone rule | |
289 * @param trsrules Receives the timezone transition rules | |
290 * @param trscount On input, specify the size of the array 'transitions
' receiving | |
291 * the timezone transition rules. On output, actual nu
mber of | |
292 * rules filled in the array will be set. | |
293 * @param status Receives error status code. | |
294 * @stable ICU 3.8 | |
295 */ | |
296 virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial, | |
297 const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) /
*const*/; | |
298 | |
299 /** | |
300 * Get time zone offsets from local wall time. | |
301 * @internal | |
302 */ | |
303 virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int3
2_t duplicatedTimeOpt, | |
304 int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) /*const*/; | |
305 | |
306 private: | |
307 void deleteRules(void); | |
308 void deleteTransitions(void); | |
309 UVector* copyRules(UVector* source); | |
310 TimeZoneRule* findRuleInFinal(UDate date, UBool local, | |
311 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt) const; | |
312 UBool findNext(UDate base, UBool inclusive, UDate& time, TimeZoneRule*& from
, TimeZoneRule*& to) const; | |
313 UBool findPrev(UDate base, UBool inclusive, UDate& time, TimeZoneRule*& from
, TimeZoneRule*& to) const; | |
314 int32_t getLocalDelta(int32_t rawBefore, int32_t dstBefore, int32_t rawAfter
, int32_t dstAfter, | |
315 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt) const; | |
316 UDate getTransitionTime(Transition* transition, UBool local, | |
317 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt) const; | |
318 void getOffsetInternal(UDate date, UBool local, int32_t NonExistingTimeOpt,
int32_t DuplicatedTimeOpt, | |
319 int32_t& rawOffset, int32_t& dstOffset, UErrorCode& ec) const; | |
320 | |
321 InitialTimeZoneRule *fInitialRule; | |
322 UVector *fHistoricRules; | |
323 UVector *fFinalRules; | |
324 UVector *fHistoricTransitions; | |
325 UBool fUpToDate; | |
326 | |
327 public: | |
328 /** | |
329 * Return the class ID for this class. This is useful only for comparing to | |
330 * a return value from getDynamicClassID(). For example: | |
331 * <pre> | |
332 * . Base* polymorphic_pointer = createPolymorphicObject(); | |
333 * . if (polymorphic_pointer->getDynamicClassID() == | |
334 * . erived::getStaticClassID()) ... | |
335 * </pre> | |
336 * @return The class ID for all objects of this class. | |
337 * @stable ICU 3.8 | |
338 */ | |
339 static UClassID U_EXPORT2 getStaticClassID(void); | |
340 | |
341 /** | |
342 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This | |
343 * method is to implement a simple version of RTTI, since not all C++ | |
344 * compilers support genuine RTTI. Polymorphic operator==() and clone() | |
345 * methods call this method. | |
346 * | |
347 * @return The class ID for this object. All objects of a | |
348 * given class have the same class ID. Objects of | |
349 * other classes have different class IDs. | |
350 * @stable ICU 3.8 | |
351 */ | |
352 virtual UClassID getDynamicClassID(void) const; | |
353 }; | |
354 | |
355 U_NAMESPACE_END | |
356 | |
357 #endif /* #if !UCONFIG_NO_FORMATTING */ | |
358 | |
359 #endif // RBTZ_H | |
360 | |
361 //eof | |
OLD | NEW |