Line data Source code
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 BASICTZ_H
10 : #define BASICTZ_H
11 :
12 : /**
13 : * \file
14 : * \brief C++ API: ICU TimeZone base class
15 : */
16 :
17 : #include "unicode/utypes.h"
18 :
19 : #if !UCONFIG_NO_FORMATTING
20 :
21 : #include "unicode/timezone.h"
22 : #include "unicode/tzrule.h"
23 : #include "unicode/tztrans.h"
24 :
25 : U_NAMESPACE_BEGIN
26 :
27 : // forward declarations
28 : class UVector;
29 :
30 : /**
31 : * <code>BasicTimeZone</code> is an abstract class extending <code>TimeZone</code>.
32 : * This class provides some additional methods to access time zone transitions and rules.
33 : * All ICU <code>TimeZone</code> concrete subclasses extend this class.
34 : * @stable ICU 3.8
35 : */
36 0 : class U_I18N_API BasicTimeZone: public TimeZone {
37 : public:
38 : /**
39 : * Destructor.
40 : * @stable ICU 3.8
41 : */
42 : virtual ~BasicTimeZone();
43 :
44 : /**
45 : * Gets the first time zone transition after the base time.
46 : * @param base The base time.
47 : * @param inclusive Whether the base time is inclusive or not.
48 : * @param result Receives the first transition after the base time.
49 : * @return TRUE if the transition is found.
50 : * @stable ICU 3.8
51 : */
52 : virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const = 0;
53 :
54 : /**
55 : * Gets the most recent time zone transition before the base time.
56 : * @param base The base time.
57 : * @param inclusive Whether the base time is inclusive or not.
58 : * @param result Receives the most recent transition before the base time.
59 : * @return TRUE if the transition is found.
60 : * @stable ICU 3.8
61 : */
62 : virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const = 0;
63 :
64 : /**
65 : * Checks if the time zone has equivalent transitions in the time range.
66 : * This method returns true when all of transition times, from/to standard
67 : * offsets and DST savings used by this time zone match the other in the
68 : * time range.
69 : * @param tz The <code>BasicTimeZone</code> object to be compared with.
70 : * @param start The start time of the evaluated time range (inclusive)
71 : * @param end The end time of the evaluated time range (inclusive)
72 : * @param ignoreDstAmount
73 : * When true, any transitions with only daylight saving amount
74 : * changes will be ignored, except either of them is zero.
75 : * For example, a transition from rawoffset 3:00/dstsavings 1:00
76 : * to rawoffset 2:00/dstsavings 2:00 is excluded from the comparison,
77 : * but a transtion from rawoffset 2:00/dstsavings 1:00 to
78 : * rawoffset 3:00/dstsavings 0:00 is included.
79 : * @param ec Output param to filled in with a success or an error.
80 : * @return true if the other time zone has the equivalent transitions in the
81 : * time range.
82 : * @stable ICU 3.8
83 : */
84 : virtual UBool hasEquivalentTransitions(const BasicTimeZone& tz, UDate start, UDate end,
85 : UBool ignoreDstAmount, UErrorCode& ec) const;
86 :
87 : /**
88 : * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
89 : * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
90 : * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value.
91 : * @param status Receives error status code.
92 : * @return The number of <code>TimeZoneRule</code>s representing time transitions.
93 : * @stable ICU 3.8
94 : */
95 : virtual int32_t countTransitionRules(UErrorCode& status) const = 0;
96 :
97 : /**
98 : * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
99 : * which represent time transitions for this time zone. On successful return,
100 : * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
101 : * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
102 : * instances up to the size specified by trscount. The results are referencing the
103 : * rule instance held by this time zone instance. Therefore, after this time zone
104 : * is destructed, they are no longer available.
105 : * @param initial Receives the initial timezone rule
106 : * @param trsrules Receives the timezone transition rules
107 : * @param trscount On input, specify the size of the array 'transitions' receiving
108 : * the timezone transition rules. On output, actual number of
109 : * rules filled in the array will be set.
110 : * @param status Receives error status code.
111 : * @stable ICU 3.8
112 : */
113 : virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
114 : const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const = 0;
115 :
116 : /**
117 : * Gets the set of time zone rules valid at the specified time. Some known external time zone
118 : * implementations are not capable to handle historic time zone rule changes. Also some
119 : * implementations can only handle certain type of rule definitions.
120 : * If this time zone does not use any daylight saving time within about 1 year from the specified
121 : * time, only the <code>InitialTimeZone</code> is returned. Otherwise, the rule for standard
122 : * time and daylight saving time transitions are returned in addition to the
123 : * <code>InitialTimeZoneRule</code>. The standard and daylight saving time transition rules are
124 : * represented by <code>AnnualTimeZoneRule</code> with <code>DateTimeRule::DOW</code> for its date
125 : * rule and <code>DateTimeRule::WALL_TIME</code> for its time rule. Because daylight saving time
126 : * rule is changing time to time in many time zones and also mapping a transition time rule to
127 : * different type is lossy transformation, the set of rules returned by this method may be valid
128 : * for short period of time.
129 : * The time zone rule objects returned by this method is owned by the caller, so the caller is
130 : * responsible for deleting them after use.
131 : * @param date The date used for extracting time zone rules.
132 : * @param initial Receives the <code>InitialTimeZone</code>, always not NULL.
133 : * @param std Receives the <code>AnnualTimeZoneRule</code> for standard time transitions.
134 : * When this time time zone does not observe daylight saving times around the
135 : * specified date, NULL is set.
136 : * @param dst Receives the <code>AnnualTimeZoneRule</code> for daylight saving time
137 : * transitions. When this time zone does not observer daylight saving times
138 : * around the specified date, NULL is set.
139 : * @param status Receives error status code.
140 : * @stable ICU 3.8
141 : */
142 : virtual void getSimpleRulesNear(UDate date, InitialTimeZoneRule*& initial,
143 : AnnualTimeZoneRule*& std, AnnualTimeZoneRule*& dst, UErrorCode& status) const;
144 :
145 :
146 : #ifndef U_HIDE_INTERNAL_API
147 : /**
148 : * The time type option bit flags used by getOffsetFromLocal
149 : * @internal
150 : */
151 : enum {
152 : kStandard = 0x01,
153 : kDaylight = 0x03,
154 : kFormer = 0x04,
155 : kLatter = 0x0C
156 : };
157 : #endif /* U_HIDE_INTERNAL_API */
158 :
159 : /**
160 : * Get time zone offsets from local wall time.
161 : * @internal
162 : */
163 : virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt,
164 : int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) const;
165 :
166 : protected:
167 :
168 : #ifndef U_HIDE_INTERNAL_API
169 : /**
170 : * The time type option bit masks used by getOffsetFromLocal
171 : * @internal
172 : */
173 : enum {
174 : kStdDstMask = kDaylight,
175 : kFormerLatterMask = kLatter
176 : };
177 : #endif /* U_HIDE_INTERNAL_API */
178 :
179 : /**
180 : * Default constructor.
181 : * @stable ICU 3.8
182 : */
183 : BasicTimeZone();
184 :
185 : /**
186 : * Construct a timezone with a given ID.
187 : * @param id a system time zone ID
188 : * @stable ICU 3.8
189 : */
190 : BasicTimeZone(const UnicodeString &id);
191 :
192 : /**
193 : * Copy constructor.
194 : * @param source the object to be copied.
195 : * @stable ICU 3.8
196 : */
197 : BasicTimeZone(const BasicTimeZone& source);
198 :
199 : /**
200 : * Gets the set of TimeZoneRule instances applicable to the specified time and after.
201 : * @param start The start date used for extracting time zone rules
202 : * @param initial Receives the InitialTimeZone, always not NULL
203 : * @param transitionRules Receives the transition rules, could be NULL
204 : * @param status Receives error status code
205 : */
206 : void getTimeZoneRulesAfter(UDate start, InitialTimeZoneRule*& initial, UVector*& transitionRules,
207 : UErrorCode& status) const;
208 : };
209 :
210 : U_NAMESPACE_END
211 :
212 : #endif /* #if !UCONFIG_NO_FORMATTING */
213 :
214 : #endif // BASICTZ_H
215 :
216 : //eof
|
