2
* Copyright (C) {1997-1999}, International Business Machines Corporation and others. All Rights Reserved.
4
********************************************************************************
8
* Modification History:
10
* Date Name Description
11
* 04/21/97 aliu Overhauled header.
12
* 08/10/98 stephen JDK 1.2 sync
13
* Added setStartRule() / setEndRule() overloads
14
* Added hasSameRules()
15
* 09/02/98 stephen Added getOffset(monthLen)
16
* Changed getOffset() to take UErrorCode
17
* 07/09/99 stephen Removed millisPerHour (unused, for HP compiler)
18
* 12/02/99 aliu Added TimeMode and constructor and setStart/EndRule
19
* methods that take TimeMode. Added to docs.
20
********************************************************************************
26
#include "unicode/timezone.h"
36
* <code>SimpleTimeZone</code> is a concrete subclass of <code>TimeZone</code>
37
* that represents a time zone for use with a Gregorian calendar. This
38
* class does not handle historical changes.
40
* When specifying daylight-savings-time begin and end dates, use a negative value for
41
* <code>dayOfWeekInMonth</code> to indicate that <code>SimpleTimeZone</code> should
42
* count from the end of the month backwards. For example, in the U.S., Daylight Savings
43
* Time ends at the last (dayOfWeekInMonth = -1) Sunday in October, at 2 AM in standard
47
* @see GregorianCalendar
49
* @author David Goldsmith, Mark Davis, Chen-Lieh Huang, Alan Liu
51
class U_I18N_API SimpleTimeZone: public TimeZone {
55
* TimeMode is used, together with a millisecond offset after
56
* midnight, to specify a rule transition time. Most rules
57
* transition at a local wall time, that is, according to the
58
* current time in effect, either standard, or DST. However, some
59
* rules transition at local standard time, and some at a specific
60
* UTC time. Although it might seem that all times could be
61
* converted to wall time, thus eliminating the need for this
62
* parameter, this is not the case.
74
SimpleTimeZone(const SimpleTimeZone& source);
77
* Default assignment operator
80
SimpleTimeZone& operator=(const SimpleTimeZone& right);
86
virtual ~SimpleTimeZone();
89
* Returns true if the two TimeZone objects are equal; that is, they have
90
* the same ID, raw GMT offset, and DST rules.
92
* @param that The SimpleTimeZone object to be compared with.
93
* @return True if the given time zone is equal to this time zone; false
97
virtual UBool operator==(const TimeZone& that) const;
100
* Constructs a SimpleTimeZone with the given raw GMT offset and time zone ID,
101
* and which doesn't observe daylight savings time. Normally you should use
102
* TimeZone::createInstance() to create a TimeZone instead of creating a
103
* SimpleTimeZone directly with this constructor.
105
* @param rawOffsetGMT The given base time zone offset to GMT.
106
* @param ID The timezone ID which is obtained from
107
* TimeZone.getAvailableIDs.
110
SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID);
113
* Construct a SimpleTimeZone with the given raw GMT offset, time zone ID,
114
* and times to start and end daylight savings time. To create a TimeZone that
115
* doesn't observe daylight savings time, don't use this constructor; use
116
* SimpleTimeZone(rawOffset, ID) instead. Normally, you should use
117
* TimeZone.createInstance() to create a TimeZone instead of creating a
118
* SimpleTimeZone directly with this constructor.
120
* Various types of daylight-savings time rules can be specfied by using different
121
* values for startDay and startDayOfWeek and endDay and endDayOfWeek. For a
122
* complete explanation of how these parameters work, see the documentation for
125
* @param rawOffsetGMT The new SimpleTimeZone's raw GMT offset
126
* @param ID The new SimpleTimeZone's time zone ID.
127
* @param savingsStartMonth The daylight savings starting month. Month is
128
* 0-based. eg, 0 for January.
129
* @param savingsStartDay The daylight savings starting
130
* day-of-week-in-month. See setStartRule() for a
131
* complete explanation.
132
* @param savingsStartDayOfWeek The daylight savings starting day-of-week.
133
* See setStartRule() for a complete explanation.
134
* @param savingsStartTime The daylight savings starting time, expressed as the
135
* number of milliseconds after midnight.
136
* @param savingsStartTimeMode Whether the start time is local wall time, local
137
* standard time, or UTC time. Default is local wall time.
138
* @param savingsEndMonth The daylight savings ending month. Month is
139
* 0-based. eg, 0 for January.
140
* @param savingsEndDay The daylight savings ending day-of-week-in-month.
141
* See setStartRule() for a complete explanation.
142
* @param savingsEndDayOfWeek The daylight savings ending day-of-week.
143
* See setStartRule() for a complete explanation.
144
* @param savingsEndTime The daylight savings ending time, expressed as the
145
* number of milliseconds after midnight.
146
* @param savingsEndTimeMode Whether the end time is local wall time, local
147
* standard time, or UTC time. Default is local wall time.
148
* @param savingsDST The number of milliseconds added to standard time
149
* to get DST time. Default is one hour.
150
* @param status An UErrorCode to receive the status.
153
SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID,
154
int8_t savingsStartMonth, int8_t savingsStartDayOfWeekInMonth,
155
int8_t savingsStartDayOfWeek, int32_t savingsStartTime,
156
int8_t savingsEndMonth, int8_t savingsEndDayOfWeekInMonth,
157
int8_t savingsEndDayOfWeek, int32_t savingsEndTime,
160
SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID,
161
int8_t savingsStartMonth, int8_t savingsStartDayOfWeekInMonth,
162
int8_t savingsStartDayOfWeek, int32_t savingsStartTime,
163
int8_t savingsEndMonth, int8_t savingsEndDayOfWeekInMonth,
164
int8_t savingsEndDayOfWeek, int32_t savingsEndTime,
165
int32_t savingsDST, UErrorCode& status);
167
SimpleTimeZone(int32_t rawOffsetGMT, const UnicodeString& ID,
168
int8_t savingsStartMonth, int8_t savingsStartDayOfWeekInMonth,
169
int8_t savingsStartDayOfWeek, int32_t savingsStartTime,
170
TimeMode savingsStartTimeMode,
171
int8_t savingsEndMonth, int8_t savingsEndDayOfWeekInMonth,
172
int8_t savingsEndDayOfWeek, int32_t savingsEndTime, TimeMode savingsEndTimeMode,
173
int32_t savingsDST, UErrorCode& status);
176
* Sets the daylight savings starting year, that is, the year this time zone began
177
* observing its specified daylight savings time rules. The time zone is considered
178
* not to observe daylight savings time prior to that year; SimpleTimeZone doesn't
179
* support historical daylight-savings-time rules.
180
* @param year the daylight savings starting year.
183
void setStartYear(int32_t year);
186
* Sets the daylight savings starting rule. For example, in the U.S., Daylight Savings
187
* Time starts at the first Sunday in April, at 2 AM in standard time.
188
* Therefore, you can set the start rule by calling:
189
* setStartRule(TimeFields.APRIL, 1, TimeFields.SUNDAY, 2*60*60*1000);
190
* The dayOfWeekInMonth and dayOfWeek parameters together specify how to calculate
191
* the exact starting date. Their exact meaning depend on their respective signs,
192
* allowing various types of rules to be constructed, as follows:<ul>
193
* <li>If both dayOfWeekInMonth and dayOfWeek are positive, they specify the
194
* day of week in the month (e.g., (2, WEDNESDAY) is the second Wednesday
196
* <li>If dayOfWeek is positive and dayOfWeekInMonth is negative, they specify
197
* the day of week in the month counting backward from the end of the month.
198
* (e.g., (-1, MONDAY) is the last Monday in the month)
199
* <li>If dayOfWeek is zero and dayOfWeekInMonth is positive, dayOfWeekInMonth
200
* specifies the day of the month, regardless of what day of the week it is.
201
* (e.g., (10, 0) is the tenth day of the month)
202
* <li>If dayOfWeek is zero and dayOfWeekInMonth is negative, dayOfWeekInMonth
203
* specifies the day of the month counting backward from the end of the
204
* month, regardless of what day of the week it is (e.g., (-2, 0) is the
205
* next-to-last day of the month).
206
* <li>If dayOfWeek is negative and dayOfWeekInMonth is positive, they specify the
207
* first specified day of the week on or after the specfied day of the month.
208
* (e.g., (15, -SUNDAY) is the first Sunday after the 15th of the month
209
* [or the 15th itself if the 15th is a Sunday].)
210
* <li>If dayOfWeek and DayOfWeekInMonth are both negative, they specify the
211
* last specified day of the week on or before the specified day of the month.
212
* (e.g., (-20, -TUESDAY) is the last Tuesday before the 20th of the month
213
* [or the 20th itself if the 20th is a Tuesday].)</ul>
214
* @param month the daylight savings starting month. Month is 0-based.
216
* @param dayOfWeekInMonth the daylight savings starting
217
* day-of-week-in-month. Please see the member description for an example.
218
* @param dayOfWeek the daylight savings starting day-of-week. Please see
219
* the member description for an example.
220
* @param time the daylight savings starting time. Please see the member
221
* description for an example.
222
* @param mode whether the time is local wall time, local standard time,
223
* or UTC time. Default is local wall time.
224
* @param status An UErrorCode
227
void setStartRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek,
228
int32_t time, UErrorCode& status);
230
void setStartRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek,
231
int32_t time, TimeMode mode, UErrorCode& status);
234
* Sets the DST start rule to a fixed date within a month.
236
* @param month The month in which this rule occurs (0-based).
237
* @param dayOfMonth The date in that month (1-based).
238
* @param time The time of that day (number of millis after midnight)
239
* when DST takes effect in local wall time, which is
240
* standard time in this case.
241
* @param mode whether the time is local wall time, local standard time,
242
* or UTC time. Default is local wall time.
243
* @param status An UErrorCode
246
void setStartRule(int32_t month, int32_t dayOfMonth, int32_t time,
249
void setStartRule(int32_t month, int32_t dayOfMonth, int32_t time,
250
TimeMode mode, UErrorCode& status);
253
* Sets the DST start rule to a weekday before or after a give date within
254
* a month, e.g., the first Monday on or after the 8th.
256
* @param month The month in which this rule occurs (0-based).
257
* @param dayOfMonth A date within that month (1-based).
258
* @param dayOfWeek The day of the week on which this rule occurs.
259
* @param time The time of that day (number of millis after midnight)
260
* when DST takes effect in local wall time, which is
261
* standard time in this case.
262
* @param mode whether the time is local wall time, local standard time,
263
* or UTC time. Default is local wall time.
264
* @param after If true, this rule selects the first dayOfWeek on
265
* or after dayOfMonth. If false, this rule selects
266
* the last dayOfWeek on or before dayOfMonth.
267
* @param status An UErrorCode
270
void setStartRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
271
int32_t time, UBool after, UErrorCode& status);
273
void setStartRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
274
int32_t time, TimeMode mode, UBool after, UErrorCode& status);
277
* Sets the daylight savings ending rule. For example, in the U.S., Daylight
278
* Savings Time ends at the last (-1) Sunday in October, at 2 AM in standard time.
279
* Therefore, you can set the end rule by calling:
281
* . setEndRule(TimeFields.OCTOBER, -1, TimeFields.SUNDAY, 2*60*60*1000);
283
* Various other types of rules can be specified by manipulating the dayOfWeek
284
* and dayOfWeekInMonth parameters. For complete details, see the documentation
285
* for setStartRule().
287
* @param month the daylight savings ending month. Month is 0-based.
289
* @param dayOfWeekInMonth the daylight savings ending
290
* day-of-week-in-month. See setStartRule() for a complete explanation.
291
* @param dayOfWeek the daylight savings ending day-of-week. See setStartRule()
292
* for a complete explanation.
293
* @param time the daylight savings ending time. Please see the member
294
* description for an example.
295
* @param mode whether the time is local wall time, local standard time,
296
* or UTC time. Default is local wall time.
297
* @param status An UErrorCode
300
void setEndRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek,
301
int32_t time, UErrorCode& status);
303
void setEndRule(int32_t month, int32_t dayOfWeekInMonth, int32_t dayOfWeek,
304
int32_t time, TimeMode mode, UErrorCode& status);
307
* Sets the DST end rule to a fixed date within a month.
309
* @param month The month in which this rule occurs (0-based).
310
* @param dayOfMonth The date in that month (1-based).
311
* @param time The time of that day (number of millis after midnight)
312
* when DST ends in local wall time, which is daylight
314
* @param mode whether the time is local wall time, local standard time,
315
* or UTC time. Default is local wall time.
316
* @param status An UErrorCode
319
void setEndRule(int32_t month, int32_t dayOfMonth, int32_t time, UErrorCode& status);
321
void setEndRule(int32_t month, int32_t dayOfMonth, int32_t time,
322
TimeMode mode, UErrorCode& status);
325
* Sets the DST end rule to a weekday before or after a give date within
326
* a month, e.g., the first Monday on or after the 8th.
328
* @param month The month in which this rule occurs (0-based).
329
* @param dayOfMonth A date within that month (1-based).
330
* @param dayOfWeek The day of the week on which this rule occurs.
331
* @param time The time of that day (number of millis after midnight)
332
* when DST ends in local wall time, which is daylight
334
* @param mode whether the time is local wall time, local standard time,
335
* or UTC time. Default is local wall time.
336
* @param after If true, this rule selects the first dayOfWeek on
337
* or after dayOfMonth. If false, this rule selects
338
* the last dayOfWeek on or before dayOfMonth.
339
* @param status An UErrorCode
342
void setEndRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
343
int32_t time, UBool after, UErrorCode& status);
345
void setEndRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
346
int32_t time, TimeMode mode, UBool after, UErrorCode& status);
349
* Returns the TimeZone's adjusted GMT offset (i.e., the number of milliseconds to add
350
* to GMT to get local time in this time zone, taking daylight savings time into
351
* account) as of a particular reference date. The reference date is used to determine
352
* whether daylight savings time is in effect and needs to be figured into the offset
353
* that is returned (in other words, what is the adjusted GMT offset in this time zone
354
* at this particular date and time?). For the time zones produced by createTimeZone(),
355
* the reference data is specified according to the Gregorian calendar, and the date
356
* and time fields are in GMT, NOT local time.
358
* @param era The reference date's era
359
* @param year The reference date's year
360
* @param month The reference date's month (0-based; 0 is January)
361
* @param day The reference date's day-in-month (1-based)
362
* @param dayOfWeek The reference date's day-of-week (1-based; 1 is Sunday)
363
* @param millis The reference date's milliseconds in day, UTT (NOT local time).
364
* @return The offset in milliseconds to add to GMT to get local time.
367
virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
368
uint8_t dayOfWeek, int32_t millis, UErrorCode& status) const;
370
virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
371
uint8_t dayOfWeek, int32_t millis) const;
374
* Gets the time zone offset, for current date, modified in case of
375
* daylight savings. This is the offset to add *to* UTC to get local time.
376
* @param era the era of the given date.
377
* @param year the year in the given date.
378
* @param month the month in the given date.
379
* Month is 0-based. e.g., 0 for January.
380
* @param day the day-in-month of the given date.
381
* @param dayOfWeek the day-of-week of the given date.
382
* @param milliseconds the millis in day in <em>standard</em> local time.
383
* @param monthLength the length of the given month in days.
384
* @param prevMonthLength length of the previous month in days.
385
* @return the offset to add *to* GMT to get local time.
388
virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
389
uint8_t dayOfWeek, int32_t milliseconds,
390
int32_t monthLength, UErrorCode& status) const;
392
virtual int32_t getOffset(uint8_t era, int32_t year, int32_t month, int32_t day,
393
uint8_t dayOfWeek, int32_t milliseconds,
394
int32_t monthLength, int32_t prevMonthLength,
395
UErrorCode& status) const;
398
* Returns the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
399
* to GMT to get local time, before taking daylight savings time into account).
401
* @return The TimeZone's raw GMT offset.
404
virtual int32_t getRawOffset(void) const;
407
* Sets the TimeZone's raw GMT offset (i.e., the number of milliseconds to add
408
* to GMT to get local time, before taking daylight savings time into account).
410
* @param offsetMillis The new raw GMT offset for this time zone.
413
virtual void setRawOffset(int32_t offsetMillis);
416
* Sets the amount of time in ms that the clock is advanced during DST.
417
* @param millisSavedDuringDST the number of milliseconds the time is
418
* advanced with respect to standard time when the daylight savings rules
419
* are in effect. A positive number, typically one hour (3600000).
422
void setDSTSavings(int32_t millisSavedDuringDST, UErrorCode& status);
424
#ifdef ICU_SIMPLETIMEZONE_USE_DEPRECATES
426
* @deprecated This will be removed after 2000-Dec-31. Use the other setDSTSavings().
428
void setDSTSavings(int32_t millisSavedDuringDST);
432
* Returns the amount of time in ms that the clock is advanced during DST.
433
* @return the number of milliseconds the time is
434
* advanced with respect to standard time when the daylight savings rules
435
* are in effect. A positive number, typically one hour (3600000).
437
int32_t getDSTSavings(void) const;
440
* Queries if this TimeZone uses Daylight Savings Time.
442
* @return True if this TimeZone uses Daylight Savings Time; false otherwise.
445
virtual UBool useDaylightTime(void) const;
448
* Returns true if the given date is within the period when daylight savings time
449
* is in effect; false otherwise. If the TimeZone doesn't observe daylight savings
450
* time, this functions always returns false.
451
* @param date The date to test.
452
* @return true if the given date is in Daylight Savings Time;
456
virtual UBool inDaylightTime(UDate date, UErrorCode& status) const;
459
* Return true if this zone has the same rules and offset as another zone.
460
* @param other the TimeZone object to be compared with
461
* @return true if the given zone has the same rules and offset as this one
464
UBool hasSameRules(const TimeZone& other) const;
467
* Clones TimeZone objects polymorphically. Clients are responsible for deleting
468
* the TimeZone object cloned.
470
* @return A new copy of this TimeZone object.
473
virtual TimeZone* clone(void) const;
478
* Override TimeZone Returns a unique class ID POLYMORPHICALLY. Pure virtual
479
* override. This method is to implement a simple version of RTTI, since not all C++
480
* compilers support genuine RTTI. Polymorphic operator==() and clone() methods call
483
* @return The class ID for this object. All objects of a given class have the
484
* same class ID. Objects of other classes have different class IDs.
487
virtual UClassID getDynamicClassID(void) const { return (UClassID)&fgClassID; }
490
* Return the class ID for this class. This is useful only for comparing to a return
491
* value from getDynamicClassID(). For example:
493
* . Base* polymorphic_pointer = createPolymorphicObject();
494
* . if (polymorphic_pointer->getDynamicClassID() ==
495
* . Derived::getStaticClassID()) ...
497
* @return The class ID for all objects of this class.
500
static UClassID getStaticClassID(void) { return (UClassID)&fgClassID; }
504
* Constants specifying values of startMode and endMode.
514
friend class TimeZone; // for access to these 2 constructors:
517
* Construct from memory-mapped data.
519
SimpleTimeZone(const StandardZone& stdZone, const UnicodeString& id);
520
SimpleTimeZone(const DSTZone& dstZone, const UnicodeString& id);
523
* Internal construction method.
525
void construct(int32_t rawOffsetGMT,
526
int8_t startMonth, int8_t startDay, int8_t startDayOfWeek,
527
int32_t startTime, TimeMode startTimeMode,
528
int8_t endMonth, int8_t endDay, int8_t endDayOfWeek,
529
int32_t endTime, TimeMode endTimeMode,
530
int32_t dstSavings, UErrorCode& status);
533
* Compare a given date in the year to a rule. Return 1, 0, or -1, depending
534
* on whether the date is after, equal to, or before the rule date. The
535
* millis are compared directly against the ruleMillis, so any
536
* standard-daylight adjustments must be handled by the caller.
538
* @return 1 if the date is after the rule date, -1 if the date is before
539
* the rule date, or 0 if the date is equal to the rule date.
541
static int32_t compareToRule(int8_t month, int8_t monthLen, int8_t prevMonthLen,
543
int8_t dayOfWeek, int32_t millis, int32_t millisDelta,
544
EMode ruleMode, int8_t ruleMonth, int8_t ruleDayOfWeek,
545
int8_t ruleDay, int32_t ruleMillis);
548
* Given a set of encoded rules in startDay and startDayOfMonth, decode
549
* them and set the startMode appropriately. Do the same for endDay and
552
* Upon entry, the day of week variables may be zero or
553
* negative, in order to indicate special modes. The day of month
554
* variables may also be negative.
556
* Upon exit, the mode variables will be
557
* set, and the day of week and day of month variables will be positive.
559
* This method also recognizes a startDay or endDay of zero as indicating
562
void decodeRules(UErrorCode& status);
563
void decodeStartRule(UErrorCode& status);
564
void decodeEndRule(UErrorCode& status);
566
static const char fgClassID;
568
int8_t startMonth, startDay, startDayOfWeek; // the month, day, DOW, and time DST starts
570
TimeMode startTimeMode, endTimeMode; // Mode for startTime, endTime; see TimeMode
571
int8_t endMonth, endDay, endDayOfWeek; // the month, day, DOW, and time DST ends
573
int32_t startYear; // the year these DST rules took effect
574
int32_t rawOffset; // the TimeZone's raw GMT offset
575
UBool useDaylight; // flag indicating whether this TimeZone uses DST
576
static const int8_t staticMonthLength[12]; // lengths of the months
577
EMode startMode, endMode; // flags indicating what kind of rules the DST rules are
580
* A positive value indicating the amount of time saved during DST in ms.
581
* Typically one hour; sometimes 30 minutes.
586
inline void SimpleTimeZone::setStartRule(int32_t month, int32_t dayOfWeekInMonth,
588
int32_t time, UErrorCode& status) {
589
setStartRule(month, dayOfWeekInMonth, dayOfWeek, time, WALL_TIME, status);
592
inline void SimpleTimeZone::setStartRule(int32_t month, int32_t dayOfMonth,
594
UErrorCode& status) {
595
setStartRule(month, dayOfMonth, time, WALL_TIME, status);
598
inline void SimpleTimeZone::setStartRule(int32_t month, int32_t dayOfMonth,
600
int32_t time, UBool after, UErrorCode& status) {
601
setStartRule(month, dayOfMonth, dayOfWeek, time, WALL_TIME, after, status);
604
inline void SimpleTimeZone::setEndRule(int32_t month, int32_t dayOfWeekInMonth,
606
int32_t time, UErrorCode& status) {
607
setEndRule(month, dayOfWeekInMonth, dayOfWeek, time, WALL_TIME, status);
610
inline void SimpleTimeZone::setEndRule(int32_t month, int32_t dayOfMonth,
611
int32_t time, UErrorCode& status) {
612
setEndRule(month, dayOfMonth, time, WALL_TIME, status);
615
inline void SimpleTimeZone::setEndRule(int32_t month, int32_t dayOfMonth, int32_t dayOfWeek,
616
int32_t time, UBool after, UErrorCode& status) {
617
setEndRule(month, dayOfMonth, dayOfWeek, time, WALL_TIME, after, status);