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