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