basictz.h (10228B)
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 override = 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 transition 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-nullptr <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 nullptr. 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, nullptr 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, nullptr 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 * Get time zone offsets from local wall time. 157 * @stable ICU 69 158 */ 159 virtual void getOffsetFromLocal( 160 UDate date, UTimeZoneLocalOption nonExistingTimeOpt, 161 UTimeZoneLocalOption duplicatedTimeOpt, int32_t& rawOffset, 162 int32_t& dstOffset, UErrorCode& status) const; 163 164 165 #ifndef U_HIDE_INTERNAL_API 166 /** 167 * The time type option bit flags used by getOffsetFromLocal 168 * @internal 169 */ 170 enum { 171 kStandard = 0x01, 172 kDaylight = 0x03, 173 kFormer = 0x04, /* UCAL_TZ_LOCAL_FORMER */ 174 kLatter = 0x0C /* UCAL_TZ_LOCAL_LATTER */ 175 }; 176 177 /** 178 * Get time zone offsets from local wall time. 179 * @internal 180 */ 181 void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt, 182 int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) const; 183 #endif /* U_HIDE_INTERNAL_API */ 184 185 protected: 186 187 #ifndef U_HIDE_INTERNAL_API 188 /** 189 * A time type option bit mask used by getOffsetFromLocal. 190 * @internal 191 */ 192 static constexpr int32_t kStdDstMask = kDaylight; 193 /** 194 * A time type option bit mask used by getOffsetFromLocal. 195 * @internal 196 */ 197 static constexpr int32_t kFormerLatterMask = kLatter; 198 #endif /* U_HIDE_INTERNAL_API */ 199 200 /** 201 * Default constructor. 202 * @stable ICU 3.8 203 */ 204 BasicTimeZone(); 205 206 /** 207 * Construct a timezone with a given ID. 208 * @param id a system time zone ID 209 * @stable ICU 3.8 210 */ 211 BasicTimeZone(const UnicodeString &id); 212 213 /** 214 * Copy constructor. 215 * @param source the object to be copied. 216 * @stable ICU 3.8 217 */ 218 BasicTimeZone(const BasicTimeZone& source); 219 220 /** 221 * Copy assignment. 222 * @stable ICU 3.8 223 */ 224 BasicTimeZone& operator=(const BasicTimeZone&) = default; 225 226 /** 227 * Gets the set of TimeZoneRule instances applicable to the specified time and after. 228 * @param start The start date used for extracting time zone rules 229 * @param initial Output parameter, receives the InitialTimeZone. 230 * Always not nullptr (except in case of error) 231 * @param transitionRules Output parameter, a UVector of transition rules. 232 * May be nullptr, if there are no transition rules. 233 * The caller owns the returned vector; the UVector owns the rules. 234 * @param status Receives error status code 235 */ 236 void getTimeZoneRulesAfter(UDate start, InitialTimeZoneRule*& initial, UVector*& transitionRules, 237 UErrorCode& status) const; 238 }; 239 240 U_NAMESPACE_END 241 242 #endif /* #if !UCONFIG_NO_FORMATTING */ 243 244 #endif /* U_SHOW_CPLUSPLUS_API */ 245 246 #endif // BASICTZ_H 247 248 //eof