• 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 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 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
217