Bug #9521: [Doc] Fix error in Time.parse documentation (in lib/time)

• Status: Closed
• Assignee: zzak (zzak _)
• Target version: -
• ruby -v: ruby 2.1.0p0 (2013-12-25 revision 44422) [i686-linux]
• Backport: 2.0.0: WONTFIX, 2.1: DONE

[stomar (Marcus Stollsteimer)]

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.

[zzak (zzak _)]

Thank you for the patch!

[zzak (zzak _)]

• Status changed from Open to Assigned

[zzak (zzak _)]

• 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 (Marcus Stollsteimer) [ci skip]

[stomar (Marcus Stollsteimer)]

@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

[zzak (zzak _)]

• 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..

[naruse (Yui NARUSE)]

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

[stomar (Marcus Stollsteimer)]

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 :)

[stomar (Marcus Stollsteimer)]

@zzak (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 (Yui NARUSE) Thanks for explaing, I didn't know that.

[stomar (Marcus Stollsteimer)]

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

[akr (Akira Tanaka)]

• 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.
  [ruby-core:60778] [Bug #9521] and [ruby-core:61718] [Bug #9682]

[akr (Akira Tanaka)]

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.

[usa (Usaku NAKAMURA)]

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

[nagachika (Tomoyuki Chikanaga)]

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

[nagachika (Tomoyuki Chikanaga)]

• 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.