1 // Copyright (C) 2016 and later: Unicode, Inc. and others.
2 // License & terms of use: http://www.unicode.org/copyright.html
4 *******************************************************************************
5 * Copyright (C) 2007-2013, International Business Machines Corporation and *
6 * others. All Rights Reserved. *
7 *******************************************************************************
12 #include "unicode/utypes.h"
16 * \brief C++ API: Rule based customizable time zone
19 #if !UCONFIG_NO_FORMATTING
21 #include "unicode/basictz.h"
22 #include "unicode/unistr.h"
26 // forward declaration
31 * a BasicTimeZone subclass implemented in terms of InitialTimeZoneRule and TimeZoneRule instances
33 * @see InitialTimeZoneRule
36 class U_I18N_API RuleBasedTimeZone : public BasicTimeZone {
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
43 * @param id The time zone ID.
44 * @param initialRule The initial time zone rule.
47 RuleBasedTimeZone(const UnicodeString& id, InitialTimeZoneRule* initialRule);
51 * @param source The RuleBasedTimeZone object to be copied.
54 RuleBasedTimeZone(const RuleBasedTimeZone& source);
60 virtual ~RuleBasedTimeZone();
63 * Assignment operator.
64 * @param right The object to be copied.
67 RuleBasedTimeZone& operator=(const RuleBasedTimeZone& right);
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
77 virtual UBool operator==(const TimeZone& that) const;
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.
87 virtual UBool operator!=(const TimeZone& that) const;
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
100 * @param rule The <code>TimeZoneRule</code>.
101 * @param status Output param to filled in with a success or an error.
104 void addTransitionRule(TimeZoneRule* rule, UErrorCode& status);
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.
115 void complete(UErrorCode& status);
118 * Clones TimeZone objects polymorphically. Clients are responsible for deleting
119 * the TimeZone object cloned.
121 * @return A new copy of this TimeZone object.
124 virtual TimeZone* clone(void) const;
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.
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.
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.
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;
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.
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.
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.
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;
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().
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
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
198 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
199 int32_t& dstOffset, UErrorCode& ec) const;
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).
205 * @param offsetMillis The new raw GMT offset for this time zone.
208 virtual void setRawOffset(int32_t offsetMillis);
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).
214 * @return The TimeZone's raw GMT offset.
217 virtual int32_t getRawOffset(void) const;
220 * Queries if this time zone uses daylight savings time.
221 * @return true if this time zone uses daylight savings time,
225 virtual UBool useDaylightTime(void) const;
228 * Queries if the given date is in daylight savings time in
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.
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,
238 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead.
240 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const;
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
250 virtual UBool hasSameRules(const TimeZone& other) const;
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.
260 virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;
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.
270 virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;
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.
280 virtual int32_t countTransitionRules(UErrorCode& status) const;
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.
298 virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
299 const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const;
302 * Get time zone offsets from local wall time.
305 virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt,
306 int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) const;
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;
324 InitialTimeZoneRule *fInitialRule;
325 UVector *fHistoricRules;
326 UVector *fFinalRules;
327 UVector *fHistoricTransitions;
332 * Return the class ID for this class. This is useful only for comparing to
333 * a return value from getDynamicClassID(). For example:
335 * . Base* polymorphic_pointer = createPolymorphicObject();
336 * . if (polymorphic_pointer->getDynamicClassID() ==
337 * . erived::getStaticClassID()) ...
339 * @return The class ID for all objects of this class.
342 static UClassID U_EXPORT2 getStaticClassID(void);
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.
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.
355 virtual UClassID getDynamicClassID(void) const;
360 #endif /* #if !UCONFIG_NO_FORMATTING */