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
