On Tue, Jun 28, 2016 at 08:18:53PM -0400, David T. Lewis wrote:
On Tue, Jun 28, 2016 at 01:41:28PM -0500, Chris Muller wrote:
I was really just trying to ask for a good class comment.
I really do think this is the best way to do this clarification. Did you notice that Bert already updated the class comment of Timespan to mention the dual capability? So, I think simply removing that old stuff from Date's comment is simple and effective solution without breaking legacy apps.
This was my attempt at a class comment for Date:
Date provides methods for dealing with calendar dates in different formats.
Instances of Date are Timespans with duration of 1 day beginning at midnight. The start value of midnight, and possibly the duration of 1 day, depend on the time zone in which the Date is defined.
In the most common usage, a Date is defined relative to UTC (time zone offset zero), and thus may be treated as a location independent calendar value.
The current date, Date today, is assumed to be defined as a UTC date without consideration of local time zone.
Alternative attempts welcome :-)
Dave
Chris, thanks for updating the class comment for Date. Summarizing where we are now:
Brent's original class comment is:
Instances of Date are Timespans with duration of 1 day. Their default creation assumes a start of midnight in the local time zone.
And our class comment (Chronology-Core-cmm.6.mcz) is:
Instances of Date are Timespans with duration of 1 day. As with all Chronology Timespan sub-instances, Dates can be instantiated as position values which compare equally to any other instance of the same Date, irregardless of the timezone in which either is created.
However, like the other Timespan subInstances, there are rare cases where it may be desirable to use instances of Date to represent a particular 1-day span of time at a particular locality on the globe. All Timespans, including Dates, may specify a particular timezone offset for this purpose.
It seems that Brent's intent was to represent a date starting at midnight in the local time zone. For various reasons, we now treat it more like a magnitude, representing it as a one day duration beginning at midnight UTC. That works better for most actual usage of class Date, but it does leave me thinking that we are mashing up two different concepts.
To be clear, I am not planning to actually /do/ anything about this, I am just trying to clarify the documentation and my own understanding. It might well be a good idea to have two different classes to represent date as duration versus date as magnitude, but I certainly have no intention of taking that on until we decide to use or discard the UTCDateAndTime updates that I previously proposed.
My primary motiviation is to make sure that the changes in UTCDateAndTime pass the unit tests while also respecting the design intent. So I am not trying to be a pain in the ass, I am really trying to understand the intended meaning of the class, and I am trying to reconcile Brent's original intent with the various changes that we have made since its introduction.
Thanks :-)
Dave