simpletz.h (46716B)
1 // © 2016 and later: Unicode, Inc. and others. 2 // License & terms of use: http://www.unicode.org/copyright.html 3 /* 4 ******************************************************************************** 5 * Copyright (C) 1997-2013, International Business Machines * 6 * Corporation and others. All Rights Reserved. * 7 ******************************************************************************** 8 * 9 * File SIMPLETZ.H 10 * 11 * Modification History: 12 * 13 * Date Name Description 14 * 04/21/97 aliu Overhauled header. 15 * 08/10/98 stephen JDK 1.2 sync 16 * Added setStartRule() / setEndRule() overloads 17 * Added hasSameRules() 18 * 09/02/98 stephen Added getOffset(monthLen) 19 * Changed getOffset() to take UErrorCode 20 * 07/09/99 stephen Removed millisPerHour (unused, for HP compiler) 21 * 12/02/99 aliu Added TimeMode and constructor and setStart/EndRule 22 * methods that take TimeMode. Added to docs. 23 ******************************************************************************** 24 */ 25 26 #ifndef SIMPLETZ_H 27 #define SIMPLETZ_H 28 29 #include "unicode/utypes.h" 30 31 #if U_SHOW_CPLUSPLUS_API 32 33 /** 34 * \file 35 * \brief C++ API: SimpleTimeZone is a concrete subclass of TimeZone. 36 */ 37 38 #if !UCONFIG_NO_FORMATTING 39 40 #include "unicode/basictz.h" 41 42 U_NAMESPACE_BEGIN 43 44 // forward declaration 45 class InitialTimeZoneRule; 46 class TimeZoneTransition; 47 class AnnualTimeZoneRule; 48 49 /** 50 * <code>SimpleTimeZone</code> is a concrete subclass of <code>TimeZone</code> 51 * that represents a time zone for use with a Gregorian calendar. This 52 * class does not handle historical changes. 53 * <P> 54 * When specifying daylight-savings-time begin and end dates, use a negative value for 55 * <code>dayOfWeekInMonth</code> to indicate that <code>SimpleTimeZone</code> should 56 * count from the end of the month backwards. For example, if Daylight Savings 57 * Time starts or ends at the last Sunday a month, use <code>dayOfWeekInMonth = -1</code> 58 * along with <code>dayOfWeek = UCAL_SUNDAY</code> to specify the rule. 59 * 60 * @see Calendar 61 * @see GregorianCalendar 62 * @see TimeZone 63 * @author D. Goldsmith, Mark Davis, Chen-Lieh Huang, Alan Liu 64 */ 65 class U_I18N_API SimpleTimeZone: public BasicTimeZone { 66 public: 67 68 /** 69 * TimeMode is used, together with a millisecond offset after 70 * midnight, to specify a rule transition time. Most rules 71 * transition at a local wall time, that is, according to the 72 * current time in effect, either standard, or DST. However, some 73 * rules transition at local standard time, and some at a specific 74 * UTC time. Although it might seem that all times could be 75 * converted to wall time, thus eliminating the need for this 76 * parameter, this is not the case. 77 * @stable ICU 2.0 78 */ 79 enum TimeMode { 80 WALL_TIME = 0, 81 STANDARD_TIME, 82 UTC_TIME 83 }; 84 85 /** 86 * Copy constructor 87 * @param source the object to be copied. 88 * @stable ICU 2.0 89 */ 90 SimpleTimeZone(const SimpleTimeZone& source); 91 92 /** 93 * Default assignment operator 94 * @param right the object to be copied. 95 * @stable ICU 2.0 96 */ 97 SimpleTimeZone& operator=(const SimpleTimeZone& right); 98 99 /** 100 * Destructor 101 * @stable ICU 2.0 102 */ 103 virtual ~SimpleTimeZone(); 104 105 /** 106 * Returns true if the two TimeZone objects are equal; that is, they have 107 * the same ID, raw GMT offset, and DST rules. 108 * 109 * @param that The SimpleTimeZone object to be compared with. 110 * @return true if the given time zone is equal to this time zone; false 111 * otherwise. 112 * @stable ICU 2.0 113 */ 114 virtual bool operator==(const TimeZone& that) const override; 115 116 /** 117 * Constructs a SimpleTimeZone with the given raw GMT offset and time zone ID, 118 * and which doesn't observe daylight savings time. Normally you should use 119 * TimeZone::createInstance() to create a TimeZone instead of creating a 120 * SimpleTimeZone directly with this constructor. 121 * 122 * @param rawOffsetGMT The given base time zone offset to GMT. 123 * @param ID The timezone ID which is obtained from 124 * TimeZone.getAvailableIDs. 125 * @stable ICU 2.0 126 */ 127 SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID); 128 129 /** 130 * Construct a SimpleTimeZone with the given raw GMT offset, time zone ID, 131 * and times to start and end daylight savings time. To create a TimeZone that 132 * doesn't observe daylight savings time, don't use this constructor; use 133 * SimpleTimeZone(rawOffset, ID) instead. Normally, you should use 134 * TimeZone.createInstance() to create a TimeZone instead of creating a 135 * SimpleTimeZone directly with this constructor. 136 * <P> 137 * Various types of daylight-savings time rules can be specified by using different 138 * values for startDay and startDayOfWeek and endDay and endDayOfWeek. For a 139 * complete explanation of how these parameters work, see the documentation for 140 * setStartRule(). 141 * 142 * @param rawOffsetGMT The new SimpleTimeZone's raw GMT offset 143 * @param ID The new SimpleTimeZone's time zone ID. 144 * @param savingsStartMonth The daylight savings starting month. Month is 145 * 0-based. eg, 0 for January. 146 * @param savingsStartDayOfWeekInMonth The daylight savings starting 147 * day-of-week-in-month. See setStartRule() for a 148 * complete explanation. 149 * @param savingsStartDayOfWeek The daylight savings starting day-of-week. 150 * See setStartRule() for a complete explanation. 151 * @param savingsStartTime The daylight savings starting time, expressed as the 152 * number of milliseconds after midnight. 153 * @param savingsEndMonth The daylight savings ending month. Month is 154 * 0-based. eg, 0 for January. 155 * @param savingsEndDayOfWeekInMonth The daylight savings ending day-of-week-in-month. 156 * See setStartRule() for a complete explanation. 157 * @param savingsEndDayOfWeek The daylight savings ending day-of-week. 158 * See setStartRule() for a complete explanation. 159 * @param savingsEndTime The daylight savings ending time, expressed as the 160 * number of milliseconds after midnight. 161 * @param status An UErrorCode to receive the status. 162 * @stable ICU 2.0 163 */ 164 SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID, 165 int8_t savingsStartMonth, int8_t savingsStartDayOfWeekInMonth, 166 int8_t savingsStartDayOfWeek, int32_t savingsStartTime, 167 int8_t savingsEndMonth, int8_t savingsEndDayOfWeekInMonth, 168 int8_t savingsEndDayOfWeek, int32_t savingsEndTime, 169 UErrorCode& status); 170 /** 171 * Construct a SimpleTimeZone with the given raw GMT offset, time zone ID, 172 * and times to start and end daylight savings time. To create a TimeZone that 173 * doesn't observe daylight savings time, don't use this constructor; use 174 * SimpleTimeZone(rawOffset, ID) instead. Normally, you should use 175 * TimeZone.createInstance() to create a TimeZone instead of creating a 176 * SimpleTimeZone directly with this constructor. 177 * <P> 178 * Various types of daylight-savings time rules can be specified by using different 179 * values for startDay and startDayOfWeek and endDay and endDayOfWeek. For a 180 * complete explanation of how these parameters work, see the documentation for 181 * setStartRule(). 182 * 183 * @param rawOffsetGMT The new SimpleTimeZone's raw GMT offset 184 * @param ID The new SimpleTimeZone's time zone ID. 185 * @param savingsStartMonth The daylight savings starting month. Month is 186 * 0-based. eg, 0 for January. 187 * @param savingsStartDayOfWeekInMonth The daylight savings starting 188 * day-of-week-in-month. See setStartRule() for a 189 * complete explanation. 190 * @param savingsStartDayOfWeek The daylight savings starting day-of-week. 191 * See setStartRule() for a complete explanation. 192 * @param savingsStartTime The daylight savings starting time, expressed as the 193 * number of milliseconds after midnight. 194 * @param savingsEndMonth The daylight savings ending month. Month is 195 * 0-based. eg, 0 for January. 196 * @param savingsEndDayOfWeekInMonth The daylight savings ending day-of-week-in-month. 197 * See setStartRule() for a complete explanation. 198 * @param savingsEndDayOfWeek The daylight savings ending day-of-week. 199 * See setStartRule() for a complete explanation. 200 * @param savingsEndTime The daylight savings ending time, expressed as the 201 * number of milliseconds after midnight. 202 * @param savingsDST The number of milliseconds added to standard time 203 * to get DST time. Default is one hour. 204 * @param status An UErrorCode to receive the status. 205 * @stable ICU 2.0 206 */ 207 SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID, 208 int8_t savingsStartMonth, int8_t savingsStartDayOfWeekInMonth, 209 int8_t savingsStartDayOfWeek, int32_t savingsStartTime, 210 int8_t savingsEndMonth, int8_t savingsEndDayOfWeekInMonth, 211 int8_t savingsEndDayOfWeek, int32_t savingsEndTime, 212 int32_t savingsDST, UErrorCode& status); 213 214 /** 215 * Construct a SimpleTimeZone with the given raw GMT offset, time zone ID, 216 * and times to start and end daylight savings time. To create a TimeZone that 217 * doesn't observe daylight savings time, don't use this constructor; use 218 * SimpleTimeZone(rawOffset, ID) instead. Normally, you should use 219 * TimeZone.createInstance() to create a TimeZone instead of creating a 220 * SimpleTimeZone directly with this constructor. 221 * <P> 222 * Various types of daylight-savings time rules can be specified by using different 223 * values for startDay and startDayOfWeek and endDay and endDayOfWeek. For a 224 * complete explanation of how these parameters work, see the documentation for 225 * setStartRule(). 226 * 227 * @param rawOffsetGMT The new SimpleTimeZone's raw GMT offset 228 * @param ID The new SimpleTimeZone's time zone ID. 229 * @param savingsStartMonth The daylight savings starting month. Month is 230 * 0-based. eg, 0 for January. 231 * @param savingsStartDayOfWeekInMonth The daylight savings starting 232 * day-of-week-in-month. See setStartRule() for a 233 * complete explanation. 234 * @param savingsStartDayOfWeek The daylight savings starting day-of-week. 235 * See setStartRule() for a complete explanation. 236 * @param savingsStartTime The daylight savings starting time, expressed as the 237 * number of milliseconds after midnight. 238 * @param savingsStartTimeMode Whether the start time is local wall time, local 239 * standard time, or UTC time. Default is local wall time. 240 * @param savingsEndMonth The daylight savings ending month. Month is 241 * 0-based. eg, 0 for January. 242 * @param savingsEndDayOfWeekInMonth The daylight savings ending day-of-week-in-month. 243 * See setStartRule() for a complete explanation. 244 * @param savingsEndDayOfWeek The daylight savings ending day-of-week. 245 * See setStartRule() for a complete explanation. 246 * @param savingsEndTime The daylight savings ending time, expressed as the 247 * number of milliseconds after midnight. 248 * @param savingsEndTimeMode Whether the end time is local wall time, local 249 * standard time, or UTC time. Default is local wall time. 250 * @param savingsDST The number of milliseconds added to standard time 251 * to get DST time. Default is one hour. 252 * @param status An UErrorCode to receive the status. 253 * @stable ICU 2.0 254 */ 255 SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID, 256 int8_t savingsStartMonth, int8_t savingsStartDayOfWeekInMonth, 257 int8_t savingsStartDayOfWeek, int32_t savingsStartTime, 258 TimeMode savingsStartTimeMode, 259 int8_t savingsEndMonth, int8_t savingsEndDayOfWeekInMonth, 260 int8_t savingsEndDayOfWeek, int32_t savingsEndTime, TimeMode savingsEndTimeMode, 261 int32_t savingsDST, UErrorCode& status); 262 263 /** 264 * Sets the daylight savings starting year, that is, the year this time zone began 265 * observing its specified daylight savings time rules. The time zone is considered 266 * not to observe daylight savings time prior to that year; SimpleTimeZone doesn't 267 * support historical daylight-savings-time rules. 268 * @param year the daylight savings starting year. 269 * @stable ICU 2.0 270 */ 271 void setStartYear(int32_t year); 272 273 /** 274 * Sets the daylight savings starting rule. For example, in the U.S., Daylight Savings 275 * Time starts at the second Sunday in March, at 2 AM in standard time. 276 * Therefore, you can set the start rule by calling: 277 * setStartRule(UCAL_MARCH, 2, UCAL_SUNDAY, 2*60*60*1000); 278 * The dayOfWeekInMonth and dayOfWeek parameters together specify how to calculate 279 * the exact starting date. Their exact meaning depend on their respective signs, 280 * allowing various types of rules to be constructed, as follows: 281 * <ul> 282 * <li>If both dayOfWeekInMonth and dayOfWeek are positive, they specify the 283 * day of week in the month (e.g., (2, WEDNESDAY) is the second Wednesday 284 * of the month).</li> 285 * <li>If dayOfWeek is positive and dayOfWeekInMonth is negative, they specify 286 * the day of week in the month counting backward from the end of the month. 287 * (e.g., (-1, MONDAY) is the last Monday in the month)</li> 288 * <li>If dayOfWeek is zero and dayOfWeekInMonth is positive, dayOfWeekInMonth 289 * specifies the day of the month, regardless of what day of the week it is. 290 * (e.g., (10, 0) is the tenth day of the month)</li> 291 * <li>If dayOfWeek is zero and dayOfWeekInMonth is negative, dayOfWeekInMonth 292 * specifies the day of the month counting backward from the end of the 293 * month, regardless of what day of the week it is (e.g., (-2, 0) is the 294 * next-to-last day of the month).</li> 295 * <li>If dayOfWeek is negative and dayOfWeekInMonth is positive, they specify the 296 * first specified day of the week on or after the specified day of the month. 297 * (e.g., (15, -SUNDAY) is the first Sunday after the 15th of the month 298 * [or the 15th itself if the 15th is a Sunday].)</li> 299 * <li>If dayOfWeek and DayOfWeekInMonth are both negative, they specify the 300 * last specified day of the week on or before the specified day of the month. 301 * (e.g., (-20, -TUESDAY) is the last Tuesday before the 20th of the month 302 * [or the 20th itself if the 20th is a Tuesday].)</li> 303 * </ul> 304 * @param month the daylight savings starting month. Month is 0-based. 305 * eg, 0 for January. 306 * @param dayOfWeekInMonth the daylight savings starting 307 * day-of-week-in-month. Please see the member description for an example. 308 * @param dayOfWeek the daylight savings starting day-of-week. Please see 309 * the member description for an example. 310 * @param time the daylight savings starting time. Please see the member 311 * description for an example. 312 * @param status An UErrorCode 313 * @stable ICU 2.0 314 */ 315 void setStartRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek, 316 int32_t time, UErrorCode& status); 317 /** 318 * Sets the daylight savings starting rule. For example, in the U.S., Daylight Savings 319 * Time starts at the second Sunday in March, at 2 AM in standard time. 320 * Therefore, you can set the start rule by calling: 321 * setStartRule(UCAL_MARCH, 2, UCAL_SUNDAY, 2*60*60*1000); 322 * The dayOfWeekInMonth and dayOfWeek parameters together specify how to calculate 323 * the exact starting date. Their exact meaning depend on their respective signs, 324 * allowing various types of rules to be constructed, as follows: 325 * <ul> 326 * <li>If both dayOfWeekInMonth and dayOfWeek are positive, they specify the 327 * day of week in the month (e.g., (2, WEDNESDAY) is the second Wednesday 328 * of the month).</li> 329 * <li>If dayOfWeek is positive and dayOfWeekInMonth is negative, they specify 330 * the day of week in the month counting backward from the end of the month. 331 * (e.g., (-1, MONDAY) is the last Monday in the month)</li> 332 * <li>If dayOfWeek is zero and dayOfWeekInMonth is positive, dayOfWeekInMonth 333 * specifies the day of the month, regardless of what day of the week it is. 334 * (e.g., (10, 0) is the tenth day of the month)</li> 335 * <li>If dayOfWeek is zero and dayOfWeekInMonth is negative, dayOfWeekInMonth 336 * specifies the day of the month counting backward from the end of the 337 * month, regardless of what day of the week it is (e.g., (-2, 0) is the 338 * next-to-last day of the month).</li> 339 * <li>If dayOfWeek is negative and dayOfWeekInMonth is positive, they specify the 340 * first specified day of the week on or after the specified day of the month. 341 * (e.g., (15, -SUNDAY) is the first Sunday after the 15th of the month 342 * [or the 15th itself if the 15th is a Sunday].)</li> 343 * <li>If dayOfWeek and DayOfWeekInMonth are both negative, they specify the 344 * last specified day of the week on or before the specified day of the month. 345 * (e.g., (-20, -TUESDAY) is the last Tuesday before the 20th of the month 346 * [or the 20th itself if the 20th is a Tuesday].)</li> 347 * </ul> 348 * @param month the daylight savings starting month. Month is 0-based. 349 * eg, 0 for January. 350 * @param dayOfWeekInMonth the daylight savings starting 351 * day-of-week-in-month. Please see the member description for an example. 352 * @param dayOfWeek the daylight savings starting day-of-week. Please see 353 * the member description for an example. 354 * @param time the daylight savings starting time. Please see the member 355 * description for an example. 356 * @param mode whether the time is local wall time, local standard time, 357 * or UTC time. Default is local wall time. 358 * @param status An UErrorCode 359 * @stable ICU 2.0 360 */ 361 void setStartRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek, 362 int32_t time, TimeMode mode, UErrorCode& status); 363 364 /** 365 * Sets the DST start rule to a fixed date within a month. 366 * 367 * @param month The month in which this rule occurs (0-based). 368 * @param dayOfMonth The date in that month (1-based). 369 * @param time The time of that day (number of millis after midnight) 370 * when DST takes effect in local wall time, which is 371 * standard time in this case. 372 * @param status An UErrorCode 373 * @stable ICU 2.0 374 */ 375 void setStartRule(int32_t month, int32_t dayOfMonth, int32_t time, 376 UErrorCode& status); 377 /** 378 * Sets the DST start rule to a fixed date within a month. 379 * 380 * @param month The month in which this rule occurs (0-based). 381 * @param dayOfMonth The date in that month (1-based). 382 * @param time The time of that day (number of millis after midnight) 383 * when DST takes effect in local wall time, which is 384 * standard time in this case. 385 * @param mode whether the time is local wall time, local standard time, 386 * or UTC time. Default is local wall time. 387 * @param status An UErrorCode 388 * @stable ICU 2.0 389 */ 390 void setStartRule(int32_t month, int32_t dayOfMonth, int32_t time, 391 TimeMode mode, UErrorCode& status); 392 393 /** 394 * Sets the DST start rule to a weekday before or after a give date within 395 * a month, e.g., the first Monday on or after the 8th. 396 * 397 * @param month The month in which this rule occurs (0-based). 398 * @param dayOfMonth A date within that month (1-based). 399 * @param dayOfWeek The day of the week on which this rule occurs. 400 * @param time The time of that day (number of millis after midnight) 401 * when DST takes effect in local wall time, which is 402 * standard time in this case. 403 * @param after If true, this rule selects the first dayOfWeek on 404 * or after dayOfMonth. If false, this rule selects 405 * the last dayOfWeek on or before dayOfMonth. 406 * @param status An UErrorCode 407 * @stable ICU 2.0 408 */ 409 void setStartRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, 410 int32_t time, UBool after, UErrorCode& status); 411 /** 412 * Sets the DST start rule to a weekday before or after a give date within 413 * a month, e.g., the first Monday on or after the 8th. 414 * 415 * @param month The month in which this rule occurs (0-based). 416 * @param dayOfMonth A date within that month (1-based). 417 * @param dayOfWeek The day of the week on which this rule occurs. 418 * @param time The time of that day (number of millis after midnight) 419 * when DST takes effect in local wall time, which is 420 * standard time in this case. 421 * @param mode whether the time is local wall time, local standard time, 422 * or UTC time. Default is local wall time. 423 * @param after If true, this rule selects the first dayOfWeek on 424 * or after dayOfMonth. If false, this rule selects 425 * the last dayOfWeek on or before dayOfMonth. 426 * @param status An UErrorCode 427 * @stable ICU 2.0 428 */ 429 void setStartRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, 430 int32_t time, TimeMode mode, UBool after, UErrorCode& status); 431 432 /** 433 * Sets the daylight savings ending rule. For example, if Daylight 434 * Savings Time ends at the last (-1) Sunday in October, at 2 AM in standard time. 435 * Therefore, you can set the end rule by calling: 436 * <pre> 437 * setEndRule(UCAL_OCTOBER, -1, UCAL_SUNDAY, 2*60*60*1000); 438 * </pre> 439 * Various other types of rules can be specified by manipulating the dayOfWeek 440 * and dayOfWeekInMonth parameters. For complete details, see the documentation 441 * for setStartRule(). 442 * 443 * @param month the daylight savings ending month. Month is 0-based. 444 * eg, 0 for January. 445 * @param dayOfWeekInMonth the daylight savings ending 446 * day-of-week-in-month. See setStartRule() for a complete explanation. 447 * @param dayOfWeek the daylight savings ending day-of-week. See setStartRule() 448 * for a complete explanation. 449 * @param time the daylight savings ending time. Please see the member 450 * description for an example. 451 * @param status An UErrorCode 452 * @stable ICU 2.0 453 */ 454 void setEndRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek, 455 int32_t time, UErrorCode& status); 456 457 /** 458 * Sets the daylight savings ending rule. For example, if Daylight 459 * Savings Time ends at the last (-1) Sunday in October, at 2 AM in standard time. 460 * Therefore, you can set the end rule by calling: 461 * <pre> 462 * setEndRule(UCAL_OCTOBER, -1, UCAL_SUNDAY, 2*60*60*1000); 463 * </pre> 464 * Various other types of rules can be specified by manipulating the dayOfWeek 465 * and dayOfWeekInMonth parameters. For complete details, see the documentation 466 * for setStartRule(). 467 * 468 * @param month the daylight savings ending month. Month is 0-based. 469 * eg, 0 for January. 470 * @param dayOfWeekInMonth the daylight savings ending 471 * day-of-week-in-month. See setStartRule() for a complete explanation. 472 * @param dayOfWeek the daylight savings ending day-of-week. See setStartRule() 473 * for a complete explanation. 474 * @param time the daylight savings ending time. Please see the member 475 * description for an example. 476 * @param mode whether the time is local wall time, local standard time, 477 * or UTC time. Default is local wall time. 478 * @param status An UErrorCode 479 * @stable ICU 2.0 480 */ 481 void setEndRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek, 482 int32_t time, TimeMode mode, UErrorCode& status); 483 484 /** 485 * Sets the DST end rule to a fixed date within a month. 486 * 487 * @param month The month in which this rule occurs (0-based). 488 * @param dayOfMonth The date in that month (1-based). 489 * @param time The time of that day (number of millis after midnight) 490 * when DST ends in local wall time, which is daylight 491 * time in this case. 492 * @param status An UErrorCode 493 * @stable ICU 2.0 494 */ 495 void setEndRule(int32_t month, int32_t dayOfMonth, int32_t time, UErrorCode& status); 496 497 /** 498 * Sets the DST end rule to a fixed date within a month. 499 * 500 * @param month The month in which this rule occurs (0-based). 501 * @param dayOfMonth The date in that month (1-based). 502 * @param time The time of that day (number of millis after midnight) 503 * when DST ends in local wall time, which is daylight 504 * time in this case. 505 * @param mode whether the time is local wall time, local standard time, 506 * or UTC time. Default is local wall time. 507 * @param status An UErrorCode 508 * @stable ICU 2.0 509 */ 510 void setEndRule(int32_t month, int32_t dayOfMonth, int32_t time, 511 TimeMode mode, UErrorCode& status); 512 513 /** 514 * Sets the DST end rule to a weekday before or after a give date within 515 * a month, e.g., the first Monday on or after the 8th. 516 * 517 * @param month The month in which this rule occurs (0-based). 518 * @param dayOfMonth A date within that month (1-based). 519 * @param dayOfWeek The day of the week on which this rule occurs. 520 * @param time The time of that day (number of millis after midnight) 521 * when DST ends in local wall time, which is daylight 522 * time in this case. 523 * @param after If true, this rule selects the first dayOfWeek on 524 * or after dayOfMonth. If false, this rule selects 525 * the last dayOfWeek on or before dayOfMonth. 526 * @param status An UErrorCode 527 * @stable ICU 2.0 528 */ 529 void setEndRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, 530 int32_t time, UBool after, UErrorCode& status); 531 532 /** 533 * Sets the DST end rule to a weekday before or after a give date within 534 * a month, e.g., the first Monday on or after the 8th. 535 * 536 * @param month The month in which this rule occurs (0-based). 537 * @param dayOfMonth A date within that month (1-based). 538 * @param dayOfWeek The day of the week on which this rule occurs. 539 * @param time The time of that day (number of millis after midnight) 540 * when DST ends in local wall time, which is daylight 541 * time in this case. 542 * @param mode whether the time is local wall time, local standard time, 543 * or UTC time. Default is local wall time. 544 * @param after If true, this rule selects the first dayOfWeek on 545 * or after dayOfMonth. If false, this rule selects 546 * the last dayOfWeek on or before dayOfMonth. 547 * @param status An UErrorCode 548 * @stable ICU 2.0 549 */ 550 void setEndRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, 551 int32_t time, TimeMode mode, UBool after, UErrorCode& status); 552 553 /** 554 * Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add 555 * to GMT to get local time in this time zone, taking daylight savings time into 556 * account) as of a particular reference date. The reference date is used to determine 557 * whether daylight savings time is in effect and needs to be figured into the offset 558 * that is returned (in other words, what is the adjusted GMT offset in this time zone 559 * at this particular date and time?). For the time zones produced by createTimeZone(), 560 * the reference data is specified according to the Gregorian calendar, and the date 561 * and time fields are in GMT, NOT local time. 562 * 563 * @param era The reference date's era 564 * @param year The reference date's year 565 * @param month The reference date's month (0-based; 0 is January) 566 * @param day The reference date's day-in-month (1-based) 567 * @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday) 568 * @param millis The reference date's milliseconds in day, UTT (NOT local time). 569 * @param status An UErrorCode to receive the status. 570 * @return The offset in milliseconds to add to GMT to get local time. 571 * @stable ICU 2.0 572 */ 573 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, 574 uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const override; 575 576 /** 577 * Gets the time zone offset, for current date, modified in case of 578 * daylight savings. This is the offset to add *to* UTC to get local time. 579 * @param era the era of the given date. 580 * @param year the year in the given date. 581 * @param month the month in the given date. 582 * Month is 0-based. e.g., 0 for January. 583 * @param day the day-in-month of the given date. 584 * @param dayOfWeek the day-of-week of the given date. 585 * @param milliseconds the millis in day in <em>standard</em> local time. 586 * @param monthLength the length of the given month in days. 587 * @param status An UErrorCode to receive the status. 588 * @return the offset to add *to* GMT to get local time. 589 * @stable ICU 2.0 590 */ 591 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, 592 uint8_t dayOfWeek, int32_t milliseconds, 593 int32_t monthLength, UErrorCode& status) const override; 594 /** 595 * Gets the time zone offset, for current date, modified in case of 596 * daylight savings. This is the offset to add *to* UTC to get local time. 597 * @param era the era of the given date. 598 * @param year the year in the given date. 599 * @param month the month in the given date. 600 * Month is 0-based. e.g., 0 for January. 601 * @param day the day-in-month of the given date. 602 * @param dayOfWeek the day-of-week of the given date. 603 * @param milliseconds the millis in day in <em>standard</em> local time. 604 * @param monthLength the length of the given month in days. 605 * @param prevMonthLength length of the previous month in days. 606 * @param status An UErrorCode to receive the status. 607 * @return the offset to add *to* GMT to get local time. 608 * @stable ICU 2.0 609 */ 610 virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day, 611 uint8_t dayOfWeek, int32_t milliseconds, 612 int32_t monthLength, int32_t prevMonthLength, 613 UErrorCode& status) const; 614 615 /** 616 * Redeclared TimeZone method. This implementation simply calls 617 * the base class method, which otherwise would be hidden. 618 * @stable ICU 2.8 619 */ 620 virtual void getOffset(UDate date, UBool local, int32_t& rawOffset, 621 int32_t& dstOffset, UErrorCode& ec) const override; 622 623 /** 624 * Get time zone offsets from local wall time. 625 * @stable ICU 69 626 */ 627 virtual void getOffsetFromLocal( 628 UDate date, UTimeZoneLocalOption nonExistingTimeOpt, 629 UTimeZoneLocalOption duplicatedTimeOpt, 630 int32_t& rawOffset, int32_t& dstOffset, UErrorCode& status) const override; 631 632 /** 633 * Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 634 * to GMT to get local time, before taking daylight savings time into account). 635 * 636 * @return The TimeZone's raw GMT offset. 637 * @stable ICU 2.0 638 */ 639 virtual int32_t getRawOffset() const override; 640 641 /** 642 * Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add 643 * to GMT to get local time, before taking daylight savings time into account). 644 * 645 * @param offsetMillis The new raw GMT offset for this time zone. 646 * @stable ICU 2.0 647 */ 648 virtual void setRawOffset(int32_t offsetMillis) override; 649 650 /** 651 * Sets the amount of time in ms that the clock is advanced during DST. 652 * @param millisSavedDuringDST the number of milliseconds the time is 653 * advanced with respect to standard time when the daylight savings rules 654 * are in effect. Typically one hour (+3600000). The amount could be negative, 655 * but not 0. 656 * @param status An UErrorCode to receive the status. 657 * @stable ICU 2.0 658 */ 659 void setDSTSavings(int32_t millisSavedDuringDST, UErrorCode& status); 660 661 /** 662 * Returns the amount of time in ms that the clock is advanced during DST. 663 * @return the number of milliseconds the time is 664 * advanced with respect to standard time when the daylight savings rules 665 * are in effect. Typically one hour (+3600000). The amount could be negative, 666 * but not 0. 667 * @stable ICU 2.0 668 */ 669 virtual int32_t getDSTSavings() const override; 670 671 /** 672 * Queries if this TimeZone uses Daylight Savings Time. 673 * 674 * @return True if this TimeZone uses Daylight Savings Time; false otherwise. 675 * @stable ICU 2.0 676 */ 677 virtual UBool useDaylightTime() const override; 678 679 #ifndef U_FORCE_HIDE_DEPRECATED_API 680 /** 681 * Returns true if the given date is within the period when daylight savings time 682 * is in effect; false otherwise. If the TimeZone doesn't observe daylight savings 683 * time, this functions always returns false. 684 * This method is wasteful since it creates a new GregorianCalendar and 685 * deletes it each time it is called. This is a deprecated method 686 * and provided only for Java compatibility. 687 * 688 * @param date The date to test. 689 * @param status An UErrorCode to receive the status. 690 * @return true if the given date is in Daylight Savings Time; 691 * false otherwise. 692 * @deprecated ICU 2.4. Use Calendar::inDaylightTime() instead. 693 */ 694 virtual UBool inDaylightTime(UDate date, UErrorCode& status) const override; 695 #endif // U_FORCE_HIDE_DEPRECATED_API 696 697 /** 698 * Return true if this zone has the same rules and offset as another zone. 699 * @param other the TimeZone object to be compared with 700 * @return true if the given zone has the same rules and offset as this one 701 * @stable ICU 2.0 702 */ 703 UBool hasSameRules(const TimeZone& other) const override; 704 705 /** 706 * Clones TimeZone objects polymorphically. Clients are responsible for deleting 707 * the TimeZone object cloned. 708 * 709 * @return A new copy of this TimeZone object. 710 * @stable ICU 2.0 711 */ 712 virtual SimpleTimeZone* clone() const override; 713 714 /** 715 * Gets the first time zone transition after the base time. 716 * @param base The base time. 717 * @param inclusive Whether the base time is inclusive or not. 718 * @param result Receives the first transition after the base time. 719 * @return true if the transition is found. 720 * @stable ICU 3.8 721 */ 722 virtual UBool getNextTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const override; 723 724 /** 725 * Gets the most recent time zone transition before the base time. 726 * @param base The base time. 727 * @param inclusive Whether the base time is inclusive or not. 728 * @param result Receives the most recent transition before the base time. 729 * @return true if the transition is found. 730 * @stable ICU 3.8 731 */ 732 virtual UBool getPreviousTransition(UDate base, UBool inclusive, TimeZoneTransition& result) const override; 733 734 /** 735 * Returns the number of <code>TimeZoneRule</code>s which represents time transitions, 736 * for this time zone, that is, all <code>TimeZoneRule</code>s for this time zone except 737 * <code>InitialTimeZoneRule</code>. The return value range is 0 or any positive value. 738 * @param status Receives error status code. 739 * @return The number of <code>TimeZoneRule</code>s representing time transitions. 740 * @stable ICU 3.8 741 */ 742 virtual int32_t countTransitionRules(UErrorCode& status) const override; 743 744 /** 745 * Gets the <code>InitialTimeZoneRule</code> and the set of <code>TimeZoneRule</code> 746 * which represent time transitions for this time zone. On successful return, 747 * the argument initial points to non-nullptr <code>InitialTimeZoneRule</code> and 748 * the array trsrules is filled with 0 or multiple <code>TimeZoneRule</code> 749 * instances up to the size specified by trscount. The results are referencing the 750 * rule instance held by this time zone instance. Therefore, after this time zone 751 * is destructed, they are no longer available. 752 * @param initial Receives the initial timezone rule 753 * @param trsrules Receives the timezone transition rules 754 * @param trscount On input, specify the size of the array 'transitions' receiving 755 * the timezone transition rules. On output, actual number of 756 * rules filled in the array will be set. 757 * @param status Receives error status code. 758 * @stable ICU 3.8 759 */ 760 virtual void getTimeZoneRules(const InitialTimeZoneRule*& initial, 761 const TimeZoneRule* trsrules[], int32_t& trscount, UErrorCode& status) const override; 762 763 764 public: 765 766 /** 767 * Override TimeZone Returns a unique class ID POLYMORPHICALLY. Pure virtual 768 * override. This method is to implement a simple version of RTTI, since not all C++ 769 * compilers support genuine RTTI. Polymorphic operator==() and clone() methods call 770 * this method. 771 * 772 * @return The class ID for this object. All objects of a given class have the 773 * same class ID. Objects of other classes have different class IDs. 774 * @stable ICU 2.0 775 */ 776 virtual UClassID getDynamicClassID() const override; 777 778 /** 779 * Return the class ID for this class. This is useful only for comparing to a return 780 * value from getDynamicClassID(). For example: 781 * <pre> 782 * . Base* polymorphic_pointer = createPolymorphicObject(); 783 * . if (polymorphic_pointer->getDynamicClassID() == 784 * . Derived::getStaticClassID()) ... 785 * </pre> 786 * @return The class ID for all objects of this class. 787 * @stable ICU 2.0 788 */ 789 static UClassID U_EXPORT2 getStaticClassID(); 790 791 private: 792 /** 793 * Constants specifying values of startMode and endMode. 794 */ 795 enum EMode 796 { 797 DOM_MODE = 1, 798 DOW_IN_MONTH_MODE, 799 DOW_GE_DOM_MODE, 800 DOW_LE_DOM_MODE 801 }; 802 803 SimpleTimeZone() = delete; // default constructor not implemented 804 805 /** 806 * Internal construction method. 807 * @param rawOffsetGMT The new SimpleTimeZone's raw GMT offset 808 * @param startMonth the month DST starts 809 * @param startDay the day DST starts 810 * @param startDayOfWeek the DOW DST starts 811 * @param startTime the time DST starts 812 * @param startTimeMode Whether the start time is local wall time, local 813 * standard time, or UTC time. Default is local wall time. 814 * @param endMonth the month DST ends 815 * @param endDay the day DST ends 816 * @param endDayOfWeek the DOW DST ends 817 * @param endTime the time DST ends 818 * @param endTimeMode Whether the end time is local wall time, local 819 * standard time, or UTC time. Default is local wall time. 820 * @param dstSavings The number of milliseconds added to standard time 821 * to get DST time. Default is one hour. 822 * @param status An UErrorCode to receive the status. 823 */ 824 void construct(int32_t rawOffsetGMT, 825 int8_t startMonth, int8_t startDay, int8_t startDayOfWeek, 826 int32_t startTime, TimeMode startTimeMode, 827 int8_t endMonth, int8_t endDay, int8_t endDayOfWeek, 828 int32_t endTime, TimeMode endTimeMode, 829 int32_t dstSavings, UErrorCode& status); 830 831 /** 832 * Compare a given date in the year to a rule. Return 1, 0, or -1, depending 833 * on whether the date is after, equal to, or before the rule date. The 834 * millis are compared directly against the ruleMillis, so any 835 * standard-daylight adjustments must be handled by the caller. 836 * 837 * @return 1 if the date is after the rule date, -1 if the date is before 838 * the rule date, or 0 if the date is equal to the rule date. 839 */ 840 static int32_t compareToRule(int8_t month, int8_t monthLen, int8_t prevMonthLen, 841 int8_t dayOfMonth, 842 int8_t dayOfWeek, int32_t millis, int32_t millisDelta, 843 EMode ruleMode, int8_t ruleMonth, int8_t ruleDayOfWeek, 844 int8_t ruleDay, int32_t ruleMillis); 845 846 /** 847 * Given a set of encoded rules in startDay and startDayOfMonth, decode 848 * them and set the startMode appropriately. Do the same for endDay and 849 * endDayOfMonth. 850 * <P> 851 * Upon entry, the day of week variables may be zero or 852 * negative, in order to indicate special modes. The day of month 853 * variables may also be negative. 854 * <P> 855 * Upon exit, the mode variables will be 856 * set, and the day of week and day of month variables will be positive. 857 * <P> 858 * This method also recognizes a startDay or endDay of zero as indicating 859 * no DST. 860 */ 861 void decodeRules(UErrorCode& status); 862 void decodeStartRule(UErrorCode& status); 863 void decodeEndRule(UErrorCode& status); 864 865 int8_t startMonth, startDay, startDayOfWeek; // the month, day, DOW, and time DST starts 866 int32_t startTime; 867 TimeMode startTimeMode, endTimeMode; // Mode for startTime, endTime; see TimeMode 868 int8_t endMonth, endDay, endDayOfWeek; // the month, day, DOW, and time DST ends 869 int32_t endTime; 870 int32_t startYear; // the year these DST rules took effect 871 int32_t rawOffset; // the TimeZone's raw GMT offset 872 UBool useDaylight; // flag indicating whether this TimeZone uses DST 873 static const int8_t STATICMONTHLENGTH[12]; // lengths of the months 874 EMode startMode, endMode; // flags indicating what kind of rules the DST rules are 875 876 /** 877 * A positive value indicating the amount of time saved during DST in ms. 878 * Typically one hour; sometimes 30 minutes. 879 */ 880 int32_t dstSavings; 881 882 /* Private for BasicTimeZone implementation */ 883 void checkTransitionRules(UErrorCode& status) const; 884 void initTransitionRules(UErrorCode& status); 885 void clearTransitionRules(); 886 void deleteTransitionRules(); 887 UBool transitionRulesInitialized; 888 InitialTimeZoneRule* initialRule; 889 TimeZoneTransition* firstTransition; 890 AnnualTimeZoneRule* stdRule; 891 AnnualTimeZoneRule* dstRule; 892 }; 893 894 inline void SimpleTimeZone::setStartRule(int32_t month, int32_t dayOfWeekInMonth, 895 int32_t dayOfWeek, 896 int32_t time, UErrorCode& status) { 897 setStartRule(month, dayOfWeekInMonth, dayOfWeek, time, WALL_TIME, status); 898 } 899 900 inline void SimpleTimeZone::setStartRule(int32_t month, int32_t dayOfMonth, 901 int32_t time, 902 UErrorCode& status) { 903 setStartRule(month, dayOfMonth, time, WALL_TIME, status); 904 } 905 906 inline void SimpleTimeZone::setStartRule(int32_t month, int32_t dayOfMonth, 907 int32_t dayOfWeek, 908 int32_t time, UBool after, UErrorCode& status) { 909 setStartRule(month, dayOfMonth, dayOfWeek, time, WALL_TIME, after, status); 910 } 911 912 inline void SimpleTimeZone::setEndRule(int32_t month, int32_t dayOfWeekInMonth, 913 int32_t dayOfWeek, 914 int32_t time, UErrorCode& status) { 915 setEndRule(month, dayOfWeekInMonth, dayOfWeek, time, WALL_TIME, status); 916 } 917 918 inline void SimpleTimeZone::setEndRule(int32_t month, int32_t dayOfMonth, 919 int32_t time, UErrorCode& status) { 920 setEndRule(month, dayOfMonth, time, WALL_TIME, status); 921 } 922 923 inline void SimpleTimeZone::setEndRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek, 924 int32_t time, UBool after, UErrorCode& status) { 925 setEndRule(month, dayOfMonth, dayOfWeek, time, WALL_TIME, after, status); 926 } 927 928 inline void 929 SimpleTimeZone::getOffset(UDate date, UBool local, int32_t& rawOffsetRef, 930 int32_t& dstOffsetRef, UErrorCode& ec) const { 931 TimeZone::getOffset(date, local, rawOffsetRef, dstOffsetRef, ec); 932 } 933 934 U_NAMESPACE_END 935 936 #endif /* #if !UCONFIG_NO_FORMATTING */ 937 938 #endif /* U_SHOW_CPLUSPLUS_API */ 939 940 #endif // _SIMPLETZ