Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/include/unicode/rbtz.h @ 69:33d812a61356

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d
author jpayne
date Tue, 18 Mar 2025 17:55:14 -0400
parents
children
rev   line source
jpayne@69 1 // © 2016 and later: Unicode, Inc. and others.
jpayne@69 2 // License & terms of use: http://www.unicode.org/copyright.html
jpayne@69 3 /*
jpayne@69 4 *******************************************************************************
jpayne@69 5 * Copyright (C) 2007-2013, International Business Machines Corporation and *
jpayne@69 6 * others. All Rights Reserved. *
jpayne@69 7 *******************************************************************************
jpayne@69 8 */
jpayne@69 9 #ifndef RBTZ_H
jpayne@69 10 #define RBTZ_H
jpayne@69 11
jpayne@69 12 #include "unicode/utypes.h"
jpayne@69 13
jpayne@69 14 #if U_SHOW_CPLUSPLUS_API
jpayne@69 15
jpayne@69 16 /**
jpayne@69 17 * \file
jpayne@69 18 * \brief C++ API: Rule based customizable time zone
jpayne@69 19 */
jpayne@69 20
jpayne@69 21 #if !UCONFIG_NO_FORMATTING
jpayne@69 22
jpayne@69 23 #include "unicode/basictz.h"
jpayne@69 24 #include "unicode/unistr.h"
jpayne@69 25
jpayne@69 26 U_NAMESPACE_BEGIN
jpayne@69 27
jpayne@69 28 // forward declaration
jpayne@69 29 class UVector;
jpayne@69 30 struct Transition;
jpayne@69 31
jpayne@69 32 /**
jpayne@69 33 * a BasicTimeZone subclass implemented in terms of InitialTimeZoneRule and TimeZoneRule instances
jpayne@69 34 * @see BasicTimeZone
jpayne@69 35 * @see InitialTimeZoneRule
jpayne@69 36 * @see TimeZoneRule
jpayne@69 37 */
jpayne@69 38 class U_I18N_API RuleBasedTimeZone : public BasicTimeZone {
jpayne@69 39 public:
jpayne@69 40 /**
jpayne@69 41 * Constructs a <code>RuleBasedTimeZone</code> object with the ID and the
jpayne@69 42 * <code>InitialTimeZoneRule</code>. The input <code>InitialTimeZoneRule</code>
jpayne@69 43 * is adopted by this <code>RuleBasedTimeZone</code>, thus the caller must not
jpayne@69 44 * delete it.
jpayne@69 45 * @param id The time zone ID.
jpayne@69 46 * @param initialRule The initial time zone rule.
jpayne@69 47 * @stable ICU 3.8
jpayne@69 48 */
jpayne@69 49 RuleBasedTimeZone(const UnicodeString& id, InitialTimeZoneRule* initialRule);
jpayne@69 50
jpayne@69 51 /**
jpayne@69 52 * Copy constructor.
jpayne@69 53 * @param source The RuleBasedTimeZone object to be copied.
jpayne@69 54 * @stable ICU 3.8
jpayne@69 55 */
jpayne@69 56 RuleBasedTimeZone(const RuleBasedTimeZone& source);
jpayne@69 57
jpayne@69 58 /**
jpayne@69 59 * Destructor.
jpayne@69 60 * @stable ICU 3.8
jpayne@69 61 */
jpayne@69 62 virtual ~RuleBasedTimeZone();
jpayne@69 63
jpayne@69 64 /**
jpayne@69 65 * Assignment operator.
jpayne@69 66 * @param right The object to be copied.
jpayne@69 67 * @stable ICU 3.8
jpayne@69 68 */
jpayne@69 69 RuleBasedTimeZone& operator=(const RuleBasedTimeZone& right);
jpayne@69 70
jpayne@69 71 /**
jpayne@69 72 * Return true if the given <code>TimeZone</code> objects are
jpayne@69 73 * semantically equal. Objects of different subclasses are considered unequal.
jpayne@69 74 * @param that The object to be compared with.
jpayne@69 75 * @return true if the given <code>TimeZone</code> objects are
jpayne@69 76 *semantically equal.
jpayne@69 77 * @stable ICU 3.8
jpayne@69 78 */
jpayne@69 79 virtual UBool operator==(const TimeZone& that) const;
jpayne@69 80
jpayne@69 81 /**
jpayne@69 82 * Return true if the given <code>TimeZone</code> objects are
jpayne@69 83 * semantically unequal. Objects of different subclasses are considered unequal.
jpayne@69 84 * @param that The object to be compared with.
jpayne@69 85 * @return true if the given <code>TimeZone</code> objects are
jpayne@69 86 * semantically unequal.
jpayne@69 87 * @stable ICU 3.8
jpayne@69 88 */
jpayne@69 89 virtual UBool operator!=(const TimeZone& that) const;
jpayne@69 90
jpayne@69 91 /**
jpayne@69 92 * Adds the <code>TimeZoneRule</code> which represents time transitions.
jpayne@69 93 * The <code>TimeZoneRule</code> must have start times, that is, the result
jpayne@69 94 * of isTransitionRule() must be true. Otherwise, U_ILLEGAL_ARGUMENT_ERROR
jpayne@69 95 * is set to the error code.
jpayne@69 96 * The input <code>TimeZoneRule</code> is adopted by this
jpayne@69 97 * <code>RuleBasedTimeZone</code> on successful completion of this method,
jpayne@69 98 * thus, the caller must not delete it when no error is returned.
jpayne@69 99 * After all rules are added, the caller must call complete() method to
jpayne@69 100 * make this <code>RuleBasedTimeZone</code> ready to handle common time
jpayne@69 101 * zone functions.
jpayne@69 102 * @param rule The <code>TimeZoneRule</code>.
jpayne@69 103 * @param status Output param to filled in with a success or an error.
jpayne@69 104 * @stable ICU 3.8
jpayne@69 105 */
jpayne@69 106 void addTransitionRule(TimeZoneRule* rule, UErrorCode& status);
jpayne@69 107
jpayne@69 108 /**
jpayne@69 109 * Makes the <code>TimeZoneRule</code> ready to handle actual timezone
jpayne@69 110 * calcuation APIs. This method collects time zone rules specified
jpayne@69 111 * by the caller via the constructor and addTransitionRule() and
jpayne@69 112 * builds internal structure for making the object ready to support
jpayne@69 113 * time zone APIs such as getOffset(), getNextTransition() and others.
jpayne@69 114 * @param status Output param to filled in with a success or an error.
jpayne@69 115 * @stable ICU 3.8
jpayne@69 116 */
jpayne@69 117 void complete(UErrorCode& status);
jpayne@69 118
jpayne@69 119 /**
jpayne@69 120 * Clones TimeZone objects polymorphically. Clients are responsible for deleting
jpayne@69 121 * the TimeZone object cloned.
jpayne@69 122 *
jpayne@69 123 * @return A new copy of this TimeZone object.
jpayne@69 124 * @stable ICU 3.8
jpayne@69 125 */
jpayne@69 126 virtual RuleBasedTimeZone* clone() const;
jpayne@69 127
jpayne@69 128 /**
jpayne@69 129 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
jpayne@69 130 * to GMT to get local time in this time zone, taking daylight savings time into
jpayne@69 131 * account) as of a particular reference date. The reference date is used to determine
jpayne@69 132 * whether daylight savings time is in effect and needs to be figured into the offset
jpayne@69 133 * that is returned (in other words, what is the adjusted GMT offset in this time zone
jpayne@69 134 * at this particular date and time?). For the time zones produced by createTimeZone(),
jpayne@69 135 * the reference data is specified according to the Gregorian calendar, and the date
jpayne@69 136 * and time fields are local standard time.
jpayne@69 137 *
jpayne@69 138 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
jpayne@69 139 * which returns both the raw and the DST offset for a given time. This method
jpayne@69 140 * is retained only for backward compatibility.
jpayne@69 141 *
jpayne@69 142 * @param era The reference date's era
jpayne@69 143 * @param year The reference date's year
jpayne@69 144 * @param month The reference date's month (0-based; 0 is January)
jpayne@69 145 * @param day The reference date's day-in-month (1-based)
jpayne@69 146 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
jpayne@69 147 * @param millis The reference date's milliseconds in day, local standard time
jpayne@69 148 * @param status Output param to filled in with a success or an error.
jpayne@69 149 * @return The offset in milliseconds to add to GMT to get local time.
jpayne@69 150 * @stable ICU 3.8
jpayne@69 151 */
jpayne@69 152 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
jpayne@69 153 uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const;
jpayne@69 154
jpayne@69 155 /**
jpayne@69 156 * Gets the time zone offset, for current date, modified in case of
jpayne@69 157 * daylight savings. This is the offset to add *to* UTC to get local time.
jpayne@69 158 *
jpayne@69 159 * <p>Note: Don't call this method. Instead, call the getOffset(UDate...) overload,
jpayne@69 160 * which returns both the raw and the DST offset for a given time. This method
jpayne@69 161 * is retained only for backward compatibility.
jpayne@69 162 *
jpayne@69 163 * @param era The reference date's era
jpayne@69 164 * @param year The reference date's year
jpayne@69 165 * @param month The reference date's month (0-based; 0 is January)
jpayne@69 166 * @param day The reference date's day-in-month (1-based)
jpayne@69 167 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
jpayne@69 168 * @param millis The reference date's milliseconds in day, local standard time
jpayne@69 169 * @param monthLength The length of the given month in days.
jpayne@69 170 * @param status Output param to filled in with a success or an error.
jpayne@69 171 * @return The offset in milliseconds to add to GMT to get local time.
jpayne@69 172 * @stable ICU 3.8
jpayne@69 173 */
jpayne@69 174 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
jpayne@69 175 uint8_t dayOfWeek, int32_t millis,
jpayne@69 176 int32_t monthLength, UErrorCode& status) const;
jpayne@69 177
jpayne@69 178 /**
jpayne@69 179 * Returns the time zone raw and GMT offset for the given moment
jpayne@69 180 * in time. Upon return, local-millis = GMT-millis + rawOffset +
jpayne@69 181 * dstOffset. All computations are performed in the proleptic
jpayne@69 182 * Gregorian calendar. The default implementation in the TimeZone
jpayne@69 183 * class delegates to the 8-argument getOffset().
jpayne@69 184 *
jpayne@69 185 * @param date moment in time for which to return offsets, in
jpayne@69 186 * units of milliseconds from January 1, 1970 0:00 GMT, either GMT
jpayne@69 187 * time or local wall time, depending on `local'.
jpayne@69 188 * @param local if true, `date' is local wall time; otherwise it
jpayne@69 189 * is in GMT time.
jpayne@69 190 * @param rawOffset output parameter to receive the raw offset, that
jpayne@69 191 * is, the offset not including DST adjustments
jpayne@69 192 * @param dstOffset output parameter to receive the DST offset,
jpayne@69 193 * that is, the offset to be added to `rawOffset' to obtain the
jpayne@69 194 * total offset between local and GMT time. If DST is not in
jpayne@69 195 * effect, this value is zero; otherwise it is a positive value,
jpayne@69 196 * typically one hour.
jpayne@69 197 * @param ec input-output error code
jpayne@69 198 * @stable ICU 3.8
jpayne@69 199 */
jpayne@69 200 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset,
jpayne@69 201 int32_t& dstOffset, UErrorCode& ec) const;
jpayne@69 202
jpayne@69 203 /**
jpayne@69 204 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
jpayne@69 205 * to GMT to get local time, before taking daylight savings time into account).
jpayne@69 206 *
jpayne@69 207 * @param offsetMillis The new raw GMT offset for this time zone.
jpayne@69 208 * @stable ICU 3.8
jpayne@69 209 */
jpayne@69 210 virtual void setRawOffset(int32_t offsetMillis);
jpayne@69 211
jpayne@69 212 /**
jpayne@69 213 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
jpayne@69 214 * to GMT to get local time, before taking daylight savings time into account).
jpayne@69 215 *
jpayne@69 216 * @return The TimeZone's raw GMT offset.
jpayne@69 217 * @stable ICU 3.8
jpayne@69 218 */
jpayne@69 219 virtual int32_t getRawOffset(void) const;
jpayne@69 220
jpayne@69 221 /**
jpayne@69 222 * Queries if this time zone uses daylight savings time.
jpayne@69 223 * @return true if this time zone uses daylight savings time,
jpayne@69 224 * false, otherwise.
jpayne@69 225 * @stable ICU 3.8
jpayne@69 226 */
jpayne@69 227 virtual UBool useDaylightTime(void) const;
jpayne@69 228
jpayne@69 229 #ifndef U_FORCE_HIDE_DEPRECATED_API
jpayne@69 230 /**
jpayne@69 231 * Queries if the given date is in daylight savings time in
jpayne@69 232 * this time zone.
jpayne@69 233 * This method is wasteful since it creates a new GregorianCalendar and
jpayne@69 234 * deletes it each time it is called. This is a deprecated method
jpayne@69 235 * and provided only for Java compatibility.
jpayne@69 236 *
jpayne@69 237 * @param date the given UDate.
jpayne@69 238 * @param status Output param filled in with success/error code.
jpayne@69 239 * @return true if the given date is in daylight savings time,
jpayne@69 240 * false, otherwise.
jpayne@69 241 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead.
jpayne@69 242 */
jpayne@69 243 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const;
jpayne@69 244 #endif // U_FORCE_HIDE_DEPRECATED_API
jpayne@69 245
jpayne@69 246 /**
jpayne@69 247 * Returns true if this zone has the same rule and offset as another zone.
jpayne@69 248 * That is, if this zone differs only in ID, if at all.
jpayne@69 249 * @param other the <code>TimeZone</code> object to be compared with
jpayne@69 250 * @return true if the given zone is the same as this one,
jpayne@69 251 * with the possible exception of the ID
jpayne@69 252 * @stable ICU 3.8
jpayne@69 253 */
jpayne@69 254 virtual UBool hasSameRules(const TimeZone& other) const;
jpayne@69 255
jpayne@69 256 /**
jpayne@69 257 * Gets the first time zone transition after the base time.
jpayne@69 258 * @param base The base time.
jpayne@69 259 * @param inclusive Whether the base time is inclusive or not.
jpayne@69 260 * @param result Receives the first transition after the base time.
jpayne@69 261 * @return TRUE if the transition is found.
jpayne@69 262 * @stable ICU 3.8
jpayne@69 263 */
jpayne@69 264 virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;
jpayne@69 265
jpayne@69 266 /**
jpayne@69 267 * Gets the most recent time zone transition before the base time.
jpayne@69 268 * @param base The base time.
jpayne@69 269 * @param inclusive Whether the base time is inclusive or not.
jpayne@69 270 * @param result Receives the most recent transition before the base time.
jpayne@69 271 * @return TRUE if the transition is found.
jpayne@69 272 * @stable ICU 3.8
jpayne@69 273 */
jpayne@69 274 virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const;
jpayne@69 275
jpayne@69 276 /**
jpayne@69 277 * Returns the number of <code>TimeZoneRule</code>s which represents time transitions,
jpayne@69 278 * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except
jpayne@69 279 * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value.
jpayne@69 280 * @param status Receives error status code.
jpayne@69 281 * @return The number of <code>TimeZoneRule</code>s representing time transitions.
jpayne@69 282 * @stable ICU 3.8
jpayne@69 283 */
jpayne@69 284 virtual int32_t countTransitionRules(UErrorCode& status) const;
jpayne@69 285
jpayne@69 286 /**
jpayne@69 287 * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code>
jpayne@69 288 * which represent time transitions for this time zone. On successful return,
jpayne@69 289 * the argument initial points to non-NULL <code>InitialTimeZoneRule</code> and
jpayne@69 290 * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code>
jpayne@69 291 * instances up to the size specified by trscount. The results are referencing the
jpayne@69 292 * rule instance held by this time zone instance. Therefore, after this time zone
jpayne@69 293 * is destructed, they are no longer available.
jpayne@69 294 * @param initial Receives the initial timezone rule
jpayne@69 295 * @param trsrules Receives the timezone transition rules
jpayne@69 296 * @param trscount On input, specify the size of the array 'transitions' receiving
jpayne@69 297 * the timezone transition rules. On output, actual number of
jpayne@69 298 * rules filled in the array will be set.
jpayne@69 299 * @param status Receives error status code.
jpayne@69 300 * @stable ICU 3.8
jpayne@69 301 */
jpayne@69 302 virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial,
jpayne@69 303 const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const;
jpayne@69 304
jpayne@69 305 /**
jpayne@69 306 * Get time zone offsets from local wall time.
jpayne@69 307 * @internal
jpayne@69 308 */
jpayne@69 309 virtual void getOffsetFromLocal(UDate date, int32_t nonExistingTimeOpt, int32_t duplicatedTimeOpt,
jpayne@69 310 int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) const;
jpayne@69 311
jpayne@69 312 private:
jpayne@69 313 void deleteRules(void);
jpayne@69 314 void deleteTransitions(void);
jpayne@69 315 UVector* copyRules(UVector* source);
jpayne@69 316 TimeZoneRule* findRuleInFinal(UDate date, UBool local,
jpayne@69 317 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt) const;
jpayne@69 318 UBool findNext(UDate base, UBool inclusive, UDate& time, TimeZoneRule*& from, TimeZoneRule*& to) const;
jpayne@69 319 UBool findPrev(UDate base, UBool inclusive, UDate& time, TimeZoneRule*& from, TimeZoneRule*& to) const;
jpayne@69 320 int32_t getLocalDelta(int32_t rawBefore, int32_t dstBefore, int32_t rawAfter, int32_t dstAfter,
jpayne@69 321 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt) const;
jpayne@69 322 UDate getTransitionTime(Transition* transition, UBool local,
jpayne@69 323 int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt) const;
jpayne@69 324 void getOffsetInternal(UDate date, UBool local, int32_t NonExistingTimeOpt, int32_t DuplicatedTimeOpt,
jpayne@69 325 int32_t& rawOffset, int32_t& dstOffset, UErrorCode& ec) const;
jpayne@69 326 void completeConst(UErrorCode &status) const;
jpayne@69 327
jpayne@69 328 InitialTimeZoneRule *fInitialRule;
jpayne@69 329 UVector *fHistoricRules;
jpayne@69 330 UVector *fFinalRules;
jpayne@69 331 UVector *fHistoricTransitions;
jpayne@69 332 UBool fUpToDate;
jpayne@69 333
jpayne@69 334 public:
jpayne@69 335 /**
jpayne@69 336 * Return the class ID for this class. This is useful only for comparing to
jpayne@69 337 * a return value from getDynamicClassID(). For example:
jpayne@69 338 * <pre>
jpayne@69 339 * . Base* polymorphic_pointer = createPolymorphicObject();
jpayne@69 340 * . if (polymorphic_pointer->getDynamicClassID() ==
jpayne@69 341 * . erived::getStaticClassID()) ...
jpayne@69 342 * </pre>
jpayne@69 343 * @return The class ID for all objects of this class.
jpayne@69 344 * @stable ICU 3.8
jpayne@69 345 */
jpayne@69 346 static UClassID U_EXPORT2 getStaticClassID(void);
jpayne@69 347
jpayne@69 348 /**
jpayne@69 349 * Returns a unique class ID POLYMORPHICALLY. Pure virtual override. This
jpayne@69 350 * method is to implement a simple version of RTTI, since not all C++
jpayne@69 351 * compilers support genuine RTTI. Polymorphic operator==() and clone()
jpayne@69 352 * methods call this method.
jpayne@69 353 *
jpayne@69 354 * @return The class ID for this object. All objects of a
jpayne@69 355 * given class have the same class ID. Objects of
jpayne@69 356 * other classes have different class IDs.
jpayne@69 357 * @stable ICU 3.8
jpayne@69 358 */
jpayne@69 359 virtual UClassID getDynamicClassID(void) const;
jpayne@69 360 };
jpayne@69 361
jpayne@69 362 U_NAMESPACE_END
jpayne@69 363
jpayne@69 364 #endif /* #if !UCONFIG_NO_FORMATTING */
jpayne@69 365
jpayne@69 366 #endif /* U_SHOW_CPLUSPLUS_API */
jpayne@69 367
jpayne@69 368 #endif // RBTZ_H
jpayne@69 369
jpayne@69 370 //eof