time: time.Parse example misleading about timezone support

[mirtchovski]

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

go version devel +75055de Tue Nov 22 04:28:59 2016 +0000 darwin/amd64

What operating system and processor architecture are you using (go env)?

GOARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"

What did you do?

Ran the example from time.Parse's documentation on the playground and on a machine set to a timezone other than PST

https://golang.org/pkg/time/#Parse
https://play.golang.org/p/tuBDbz66I0

What did you expect to see?

2013-02-03 19:54:00 -0800 PST

What did you see instead?

2013-02-03 19:54:00 -0000 PST

The issue is that when time.Parse is used with a timezone abbreviation format in a different timezone than the one the abbreviation specifies it will not print a correct offset. For example if the input specifies PST but the code is run on a machine set to MST the offset will be printed as all zeroes (a "fabricated" timezone, as per the documentation). While this is tersely documented, the documentation example provides only the rare "working" case, which is misleading. I suggest a second case is added with a different timezone and the expected output documented in a comment, a minimal (likely insufficient) example:

    // Local timezone is PST
    t, _ := time.Parse(longForm, "Feb 3, 2013 at 7:54pm (PST)") // results in offset -0800
    ...
    t, _ := time.Parse(longForm, "Feb 3, 2013 at 7:54pm (MST)") // results in a fabricated tz, offset -0000

[dgpc]

It would be very helpful if time.Parse understood at least all the standard timezone abbreviations found in RFC822, if not also those found in the IANA TZDB. Different parsing behavior depending on the local time of the system the application is quite unexpected behavior, to me at least.

[ianlancetaylor]

@dgpc The time zones in RFC 822 are misleading for international users. For example, CST is listed in RFC 822, but the same abbreviation is used not only for Central Standard Time but also for China Standard Time and Cuba Standard Time. There is no way we can win here.

[rsc]

I'm sorry the example confused you but (1) as you note, the docs cover this clearly, and (2) as Ian notes, there is no way to understand "all the standard timezone abbreviations", due to the many collisions.