Deprecated use of DateAndTime

Implementation of time zone support rendered the offset instance variable in DateAndTime obsolete. The offset instance variable had been a Duration representing the seconds the DateAndTime object was offset from UTC (GMT). It has been replaced by an instance variable named timeZone. The timeZone instance variable is an instance of EsTimeZone which holds the timeZoneRuleSet of the DateAndTime object and the current timeZone Rule in effect for the DateAndTime object.

The removal of the offset instance variable does not cause any code that uses DateAndTime objects to stop working. However, some of the DateAndTime instance creation methods will result in DateAndTime objects without any information about DST transitions. This means that calculations using these DateAndTime objects will not have any accuracy with respect to DST because they have no time zone information.

For instance, for a DateAndTime object created August 28, 2012 in Raleigh, NC, the timeZoneRuleSet in the timeZone instance variable will be 'America/New_York', because that is the timeZoneRuleSet specified in the LocalTimeZone class variable of class DateAndTime; the timeZoneRule will be the one that is in effect at that time.

However, the following expression creates a DateAndTime object whose date is also August 28, 2012, but the DateAndTime object has no DST information available in it.

DateAndTime

year: 2012

day: 241

hour: 11

minute: 0

second: 0

millisecond: 0

offset: (Duration hours: 4)

All of the existing DateAndTime APIs still work, though some have been deprecated because they use the old offset and will not provide any DST transitions:

•	DateAndTime class>> year: year day: dayOfYear hour: hour minute: minute second: second millisecond: millisecond offset: aDuration

•	DateAndTime class>> year: year month: month day: dayOfYear hour: hour minute: minute second: second millisecond: millisecond offset: aDuration

These methods which use the timezone should be used in their place:

•	DateAndTime class>> year: year day: dayOfYear hour: hour minute: minute second: second millisecond: millisecond timeZone: timeZoneName

•	DateAndTime class>> year: year month: month day: dayOfYear hour: hour minute: minute second: second millisecond: millisecond timeZone: timeZoneName

All of the DateAndTime instance creation methods that specify some value for offset have a similar problem; there is no way to reliably determine a time zone from an offset because different time zones can have the same offset. For instance, Chicago ('America/Chicago') during DST has an offset of -5:00:00 hours from UTC which is the same offset Raleigh, NC ('America/New_York') has in the winter when DST is not in effect. You can determine offset from time zone but not vice versa.

DateAndTime instance creation methods that specify some value for offset will set the timeZone instance variable of the created DateAndTime objects to a dummy instance of EsTimeZone that is created on the fly. This dummy EsTimeZone instance will have a name of the form 'TZ plus or minus some system offset', and it will have a single timeZoneRule specifying that DST=false. For example, the DateAndTime object created by this code:

DateAndTime

year: 2011

month: 12

day: 17

hour: 1

minute: 2

second: 3

offset: (Duration seconds: -18000)

will have its timeZone instance variable set to an instance of EsTimeZone named 'Tz-5:00:00'. The EsTimeZone instance in the timeZone instance variable of this DateAndTime object will have just one timeZoneRule saying that DST=false as of 1901-01-01T00:00:00.