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