[ruby-core:61564] [ruby-trunk - Bug #9521] [Doc] Fix error in Time.parse documentation (in lib/time)

Issue #9521 has been updated by 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  :) 

----------------------------------------
Bug #9521: [Doc] Fix error in Time.parse documentation (in lib/time)
https://bugs.ruby-lang.org/issues/9521#change-45847

* Author: Marcus Stollsteimer
* Status: Feedback
* Priority: Normal
* Assignee: Zachary Scott
* Category: doc
* Target version: 
* ruby -v: ruby 2.1.0p0 (2013-12-25 revision 44422) [i686-linux]
* Backport: 1.9.3: UNKNOWN, 2.0.0: UNKNOWN, 2.1: UNKNOWN
----------------------------------------
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.


---Files--------------------------------
doc_lib_time.patch (1.13 KB)


-- 
httsp://bugs.ruby-lang.org/