Bug #9521

[Doc] Fix error in Time.parse documentation (in lib/time)

Added by Marcus Stollsteimer over 1 year ago. Updated about 1 year ago.

[ruby-core:60778]
Status:Closed
Priority:Normal
Assignee:Zachary Scott
ruby -v:ruby 2.1.0p0 (2013-12-25 revision 44422) [i686-linux] Backport:2.0.0: WONTFIX, 2.1: DONE

Description

The docs state that the examples are for GMT as local time zone while in fact they are for JST.
The patch fixes this by using EST (and saying so), like the rest of the examples for lib/time.

doc_lib_time.patch Magnifier (1.13 KB) Marcus Stollsteimer, 02/15/2014 05:02 PM


Related issues

Copied to Ruby trunk - Bug #9682: [Doc] Improve Time.parse documentation (in lib/time) Closed 02/15/2014

Associated revisions

Revision 45349
Added by Zachary Scott over 1 year ago

  • lib/time.rb: [DOC] Fix timezone in example of Time.parse [Bug #9521] Based on patch by @stomar [ci skip]

Revision 45349
Added by Zachary Scott over 1 year ago

  • lib/time.rb: [DOC] Fix timezone in example of Time.parse [Bug #9521] Based on patch by @stomar [ci skip]

Revision 45837
Added by Akira Tanaka over 1 year ago

  • lib/time.rb (Time.parse): [DOC] Fix an example in the documentation. Reported by Marcus Stollsteimer. [Bug #9521] and [Bug #9682]

Revision 45837
Added by Akira Tanaka over 1 year ago

  • lib/time.rb (Time.parse): [DOC] Fix an example in the documentation. Reported by Marcus Stollsteimer. [Bug #9521] and [Bug #9682]

Revision 47228
Added by Tomoyuki Chikanaga about 1 year ago

merge revision(s) r45349,r45837,r45838: [Backport #9521] [Backport #9682]

* lib/time.rb: [DOC] Fix timezone in example of Time.parse [Bug #9521]
  Based on patch by @stomar

* lib/time.rb (Time.parse): [DOC] Fix an example in the documentation.
  Reported by Marcus Stollsteimer.
   [Bug #9521] and  [Bug #9682]

* lib/time.rb (Time.parse): [DOC] Fix an example in the documentation
  to use EST.

History

#1 Updated by Zachary Scott over 1 year ago

Thank you for the patch!

#2 Updated by Zachary Scott over 1 year ago

  • Status changed from Open to Assigned

#3 Updated by Zachary Scott over 1 year ago

  • Status changed from Assigned to Closed
  • % Done changed from 0 to 100

Applied in changeset r45349.


  • lib/time.rb: [DOC] Fix timezone in example of Time.parse [Bug #9521] Based on patch by @stomar [ci skip]

#4 Updated by Marcus Stollsteimer over 1 year ago

@zak Just to consider: I used EST because

  • the docs for Time state: All of these examples were done using the EST timezone which is GMT-5.
  • AFAIK it's not easily possible to set JST on the local machine (via environment variable) so that these examples can be reproduced, since it's not part of RFC 822. Setting to EST works fine (even in Germany):

2.1.1 :012 > ENV["TZ"] = "EST"
2.1.1 :013 > Time.parse("2014-01-01")
=> 2014-01-01 00:00:00 -0500
2.1.1 :014 > ENV["TZ"] = "JST"
2.1.1 :015 > Time.parse("2014-01-01")
=> 2014-01-01 00:00:00 +0000

#5 Updated by Zachary Scott over 1 year ago

  • Status changed from Closed to Feedback

You raise a good point, I was only trying to avoid extra work :)

To be honest, these examples are confusing.. I'm not sure what the point of passing tz is, for example:

now = Time.parse("Thu Nov 29 14:33:20 GMT 2001")

Is clearly set to GMT, right?

Time.parse("16:30", now) #=> 2001-11-29 16:30:00 +0900

Yet in this example 16:30 in GMT would be 1:30 the next day in JST..

#6 Updated by Yui NARUSE over 1 year ago

Marcus Stollsteimer wrote:

@zak Just to consider: I used EST because

  • the docs for Time state: All of these examples were done using the EST timezone which is GMT-5.
  • AFAIK it's not easily possible to set JST on the local machine (via environment variable) so that these examples can be reproduced, since it's not part of RFC 822. Setting to EST works fine (even in Germany):

2.1.1 :012 > ENV["TZ"] = "EST"
2.1.1 :013 > Time.parse("2014-01-01")
=> 2014-01-01 00:00:00 -0500
2.1.1 :014 > ENV["TZ"] = "JST"
2.1.1 :015 > Time.parse("2014-01-01")
=> 2014-01-01 00:00:00 +0000

TZ environment variable must be used like

irb(main):001:0> require"time"
=> true
irb(main):002:0> ENV["TZ"]="EST+5"
=> "EST+5"
irb(main):003:0> Time.parse("2014-01-01")
=> 2014-01-01 00:00:00 -0500
irb(main):004:0> ENV["TZ"]="JST-9"
=> "JST-9"
irb(main):005:0> Time.parse("2014-01-01")
=> 2014-01-01 00:00:00 +0900

see also http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html

#7 Updated by Marcus Stollsteimer over 1 year ago

I agree, the behaviour of Time.parse is confusing, at least when different time zones are involved.

It can be understood if you consider these points:

1. Time.parse assumes local time for all time specifications, unless explicitly stated otherwise:

require "time"
ENV["TZ"] = "EST"
now = Time.parse("Thu Nov 29 14:33:20 GMT 2001")
                             #=> 2001-11-29 09:33:20 -0500  (correct)
Time.parse("16:30", now)     #=> 2001-11-29 16:30:00 -0500  (EST is assumed,
Time.parse("16:30 CST", now) #=> 2001-11-29 17:30:00 -0500   unless explicitly set)

2. Also note that Time.parse returns the time in the local time zone (so the initially "set" TZ cannot be inferred from "now")

3. Time.parse uses the date component of "now" so to speak "as is", without regarding its TZ:

now = Time.parse("Thu Nov 29 3:20:55 GMT 2001")  #=> 2001-11-28 22:20:55 -0500 
Time.parse("16:30", now)                         #=> 2001-11-28 16:30:00 -0500 (!)

# the same point in time, but expressed in GMT
now = Time.new(2001, 11, 29, 3, 20, 55, "+00:00") #=> 2001-11-29 03:20:55 +0000 
Time.parse("16:30", now)                          #=> 2001-11-29 16:30:00 -0500 (!!!)

So... figuring this out felt pretty much like puzzle solving...
I rather wouldn't try using different time zones with Time.parse :)

#8 Updated by Marcus Stollsteimer over 1 year ago

@zzak I suggest adding the return value of Time.parse("Thu ...") to make the examples a little more clear:

now = Time.parse("Thu Nov 29 14:33:20 GMT 2001")  #=> 2001-11-29 09:33:20 -0500

(Or correspondingly for JST.)

@naruse Thanks for explaing, I didn't know that.

#9 Updated by Marcus Stollsteimer over 1 year ago

  • Copied to Bug #9682: [Doc] Improve Time.parse documentation (in lib/time) added

#10 Updated by Akira Tanaka over 1 year ago

  • Status changed from Feedback to Closed

Applied in changeset r45837.


  • lib/time.rb (Time.parse): [DOC] Fix an example in the documentation. Reported by Marcus Stollsteimer. [Bug #9521] and [Bug #9682]

#11 Updated by Akira Tanaka over 1 year ago

It seems the original document of that part written by gsinclair used GMT.
But I mistakenly modified to use JST.

I agree that most examples uses EST.
This convention is inherited from time.c.

time.c has a sentence:
"All of these examples were done using the EST timezone which is GMT-5."

Also, I didn't considered well the behavior of Time.parse when multiple time zones are involved.

So I modified the example to use EST,
not only the result but also for "now" at r45838.

#12 Updated by Usaku NAKAMURA about 1 year ago

  • Backport changed from 1.9.3: UNKNOWN, 2.0.0: UNKNOWN, 2.1: UNKNOWN to 2.0.0: WONTFIX, 2.1: UNKNOWN

#13 Updated by Tomoyuki Chikanaga about 1 year ago

  • Backport changed from 2.0.0: WONTFIX, 2.1: UNKNOWN to 2.0.0: WONTFIX, 2.1: REQUIRED

#14 Updated by Tomoyuki Chikanaga about 1 year ago

  • Backport changed from 2.0.0: WONTFIX, 2.1: REQUIRED to 2.0.0: WONTFIX, 2.1: DONE

Backported into ruby_2_1 branch at r47228.

Also available in: Atom PDF