http://dev.clojure.org/jira This file is an XML representation of an issue en-us 4.4 649 25-07-2011 http://dev.clojure.org/jira/browse/CLJ-928 Clojure <p>The default #inst returns a java.util.Date. Date is always in UTC, and doesn't know about time zones, but the implementation of the print method always renders it in the default time zone. For example,</p> <p>user=&gt; #inst "2012Z"<br/> #inst "2011-12-31T19:00:00.000-05:00"</p> <p>RFC3339 says:</p> <p>4.3. Unknown Local Offset Convention</p> <p> If the time in UTC is known, but the offset to local time is unknown,<br/> this can be represented with an offset of "-00:00". This differs<br/> semantically from an offset of "Z" or "+00:00", which imply that UTC<br/> is the preferred reference point for the specified time.</p> <p>java.sql.Timestamp should also print in UTC since that class doesn't keep timezone information. The print-method for Timestamp seems broken.</p> <p>user=&gt; (binding <span class="error">&#91;*data-readers* {'inst #'clojure.instant/read-instant-timestamp}] (read-string "#inst \"2012Z\""))<br/> #inst "2011-12-31T19:000000000000000-05:00"<br/> <br/> user=&gt; (binding [<b>data-readers</b> {'inst #'clojure.instant/read-instant-timestamp}&#93;</span> (read-string "#inst \"2012-01-01T01:23:45.678+00:00\""))<br/> #inst "2011-12-31T20:267800000000000-05:00"</p> <p>user=&gt; (java.sql.Timestamp. 0)<br/> #inst "1969-12-31T19:000000000000000-05:00"</p> <p>The implementations of the print-methods for Data, GregorianCalendar and Timestamp do too much string manipulation. I suggest doing some refactoring. (Patch coming soon.)</p> <p>Also, the documentation needs some updating. clojure.instant/read-instant-date, etc. mention <b>instant-reader</b> but I think that mechanism was generalized as <b>data-readers</b>.</p> 1.4-beta1, Mac OS X 10.7.3, java version &quot;1.6.0_30&quot; CLJ-928

instant literal for Date and Timestamp should print in UTC

Defect Major Closed Completed Unassigned Steve Miner reader Tue, 7 Feb 2012 13:19:34 -0600 Fri, 1 Mar 2013 12:46:58 -0600 Fri, 24 Feb 2012 15:29:11 -0600 Release 1.4 0 2 <p>#inst literals for Date and Timestamp should print in UTC. Fixed round-tripping problem with Timestamp nanos (and re-enabled test). Refactored print-methods to avoid some string manipulations, particularly regarding Calendar timezone offsets. Added tests including those from <a href="http://dev.clojure.org/jira/browse/CLJ-926" title="Instant literals do not round trip correctly"><del>CLJ-926</del></a>, which this patch also fixes. Fixed doc on read-instant-date, etc.</p> <p>Thank you. I will run this patch through the paces ASAP.</p> <p>"Date is always in UTC, and doesn't know about time zones"</p> <p>Given that pretty much all of the methods on Date return results in the local timezone, I wouldn't quite say that Date is always in UTC. Granted, most of those methods are deprecated; toString() however isn't and it also displays the date in the local timezone.</p> <p>We can certainly force printing of dates in UTC, by overriding the timezone setting on SimpleDateFormat, and there might be other valid reasons for always forcing UTC representation. Dates not being timezone aware however doesn't seem like one to me.</p> <p>It's only a slight exaggeration to say that a java.util.Date is intrinsically a long (milliseconds since "the epoch"). For Clojure's purposes, an "instant" is a point in time in a universal sense (not situated in a timezone) so UTC makes sense as the canonical form. RFC 3339 section 4.3 says to use "-00:00" for the offset when timezone information is unknown. java.sql.Timestamp is like a Date with an extra field for nanos so it also should use UTC for the canonical form.</p> <p>My argument for UTC as the canonical form is that it best matches the desired semantics of a Clojure instant. I think it's the most conservative way to go and offers the best approach to interoperability by following RFC 3339.</p> <p>java.util.Calendar is by design cognizant of timezones so it arguably makes sense to preserve the timezone information. Note that comparisons of Calendars take into account the timezone so two Calendar objects might be the same instant in a sense but not be equal because of the timezones. That might be a bit tricky for Clojure users who want a clean abstraction of "instant" with multiple implementations. Presumably they know what they are doing if they decide to use read-instant-calendar. It might be a good idea to be more explicit about this in the documentation.</p> <p>Modified priting to conform to the following:</p> <ul> <li>Instant instances are stored in UTC format without offset information.</li> <li>Instant literals with offset information will be parsed and stored with offset applied.</li> <li>Instant literals without offset information will be parsed as UTC format without offset information.</li> <li>Instants will print as time having local offset applied and without offset printed.</li> <li>Instants without offset info will be print-dup'd as UTC format with RFC-3339 default offset information (-00:00)</li> </ul> <p> This provides a canonical storage and read format of UTC and a print format relative to the local offset.</p> <p>With Fogus' patch on Feb. 20, instant literals do not round-trip unless <tt>&#42;print-dup&#42;</tt> is bound true:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> <pre class="code-java">user=&gt; (let [i (read-string <span class="code-quote">"#inst \"</span>2012-02-24T14:41-02:00\"") j (read-string (pr-str i))] (prn i) (prn j) (prn (= i j))) #inst <span class="code-quote">"2012-02-24T11:41:00.000"</span> #inst <span class="code-quote">"2012-02-24T06:41:00.000"</span> <span class="code-keyword">false</span> nil user=&gt;(binding [*print-dup* <span class="code-keyword">true</span>] (let [i (read-string <span class="code-quote">"#inst \"</span>2012-02-24T14:41-02:00\"") j (read-string (pr-str i))] (prn i) (prn j) (prn (= i j)))) #inst <span class="code-quote">"2012-02-24T16:41:00.000-00:00"</span> #inst <span class="code-quote">"2012-02-24T16:41:00.000-00:00"</span> <span class="code-keyword">true</span> nil</pre> </div></div> <p>The docstring of <tt>&#42;print-dup&#42;</tt> says nothing about print/read values being equal (by Clojure's definition of =) only that print/read values will be of the same type. "Type" is not a particularly meaningful concept when applied to data literals.</p> <p>We (Stuart &amp; Luke) believe that print/read values should <b>always</b> print in such a way that they can be read back as the same instant. Printing an instant should either:</p> <ul> <li>print in local time, with local offset</li> <li>always print in UTC, with zero offset</li> </ul> <p>Instants should <b>never</b> print without any time zone offset, as this admits too much confusion.</p> <p>Just spoke with Rich Hickey, who made the following assertions:</p> <ul> <li>Instants should always represent an exact point in time, unambiguously. This representation may include time zone information.</li> </ul> <ul> <li>Our specification for instant literals allows any part on the right to be omitted. Omitting the time zone offset means UTC is assumed. It is not important whether or not the default printer includes the UTC "00:00" offset or omits it.</li> </ul> <ul> <li>If we are printing an instant literal based on a type that does <b>not</b> contain time zone information (e.g., java.util.Date) then we should <b>not</b> add time zone information but simply print in UTC.</li> </ul> <ul> <li>If we are printing an instant literal based on a type that <b>can</b> contain time zone information (e.g., java.util.Calendar) then we <b>may</b> print with the time zone offset included. This is a nice-to-have feature, not a requirement. It is always permissible to print instants in UTC.</li> </ul> <ul> <li>It is possible that round-trip print/read of an instant <b>may</b> lose time zone information, depending on the types used, but it this should not change the meaning of the instant in UTC.</li> </ul> <p>I believe my original patch satisfies the requirements stated above. I'm happy to work on this if you want something changed.</p> <p>Rejected Fogus' patch of Feb. 20.</p> <p>Screened Steve Miner's patch of Feb. 7. Ready for Rich.</p> <p>Patch applied.</p> Approval Ok Global Rank Patch Code and Test