The New DateTime class introduced in Xojo 2019r2 is meant as a replacement for the now deprecated Date class. Let’s take a look at how these two classes compare:
Date
- Mutable (you can change any of its properties without having to create a new Date)
On the surface this sounds great, but you can get into some ambiguous Dates depending on the order of operation, for example:
Dim d As New Date(2019, 2, 28) // February 28, 2019
d.Day = 31 // February 31, 2019?
d.Month = 3
In reality since February 31 is not a valid date we have to coerce it into one, in this case we roll over as 3 days into March, so after the Day has been set to 31 the actual date is now March 3, 2019, probably not what the user intended.
- Uses local TimeZone (no way to use a different TimeZone)
Consider living in California and trying to determine the time in New York. With the Date class you’d have to calculate the time offset yourself.
- Uses current locale for date string formatting (no way to use a different locale)
If you’re trying to display something for your French or Spanish speaking compadre and you’re on a English speaking region, you’d have to format the date yourself.
- Fixed GMTOffset (no understanding of daylight savings rollover)
The GMTOffset is always the current TimeZone offset, unless its has been specifically set in one of the Date constructors.
DateTime
- Immutable (none of its properties can be modified, you’d have to create a new DateTime)
While this may seem more restrictive, this provides protection against setting ambiguous dates. You can use DateInterval and/or DateTime.AddInterval to manipulate the date which is returned as a new DateTime object.
- TimeZone savvy
Each DateTime object can be associated with a different TimeZone. For a list of all the supported TimeZone names, see:
https://docs.oracle.com/cd/E41183_01/DR/ICU_Time_Zones.html
- Date formats are locale savvy
Instead of being tied to presenting a date string in the current locale, you can specify a different locale in which to display your formatted date string.
- Daylight savings aware
A TimeZone is always associated with a DateTime object (if none is specified then the current TimeZone is used), you can use the TimeZone.SecondsFromGMTOffset to determine if the Date is in daylight savings.
Daylight savings boundary behavior
When daylight savings end on November 3, 2019 at 2:00am the date will fall back one hour so we really are on November 3, 2019 at 1:00am. So how does Xojo handle the case where a user sets the date to be November 3, 2019 at 1:00am? Is it just before daylight savings or after? The answer is, after, with the TimeZone GMTOffset adjusted accordingly.
For more information about the new DateTime class, make sure to check out the documentation page on it: http://documentation.xojo.com/api/deprecated/date.htmlTime