Notes on xojo.core.date and .timezone

(1) The calendar used by xojo.core.date is the “proleptic Gregorian”–in other words, the current calendar with its rules extended back forever. (Thus, new Date(1100,2,29) will yield 1 March 1100, because 1100 would not be a leap year under the Gregorian rule–but back then, it would have actually been 23 February 1100 under the Julian calendar.) This is probably correct behavior (it complies with ISO 8601), but should be documented better.

(2) For dates prior to AD 1, the constructor takes values in the “astronomical” year-numbering system, which includes a year 0. Thus, new Date(-15,7,2) will yield 2 July 16BC. This is probably reasonable, but the problem is in getting the information back out. The .year property of that date will not be either -15 or -16: it will be (positive) 16, exactly as if the date were in AD 16. The text form from the Raw locale will also show the date as if it were in AD 16. (The information is in there, but you can only tell by using either SecondsFrom1970 or a locale/format that prints the information.) Either the .year property needs to return astronomical years, or there needs to be a property we can read to determine AD/BC (and in the latter case, a version of the constructor with that property included).

(3) Determining the GMT offset of a date could also be made easier. The .SecondsFromGMT property of the timezone object gives the modern/non-DST offset, but short of reading all the properties, constructing a time value from them, and comparing it to .SecondsFrom1970, or in the alternative parsing the text from a locale that lists the information, there’s not a way to determine the offset that the date actually had. (I have written a method to do that, actually…)

(4) The documentation never explains what the text is that should be passed to the TimeZone constructor, nor the form of the .Abbreviation property. In both cases, it’s the ID from the Olson tz database–again, a correct choice, but one that really needs to be documented.

I wouldn’t really rely on Xojo.Core.Date for handling of pre-Gregorian dates.

To be clear, you’d like something like “SecondsFromGMT(forDate As Date) As Integer” on a TimeZone? You should file a feature request.

You’re right, the documentation definitely should make this clear. Please file a bug report on this.