Skip to content

time: improve Documentation for Parse for zone offsets #29351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
abraithwaite opened this issue Dec 20, 2018 · 2 comments
Closed

time: improve Documentation for Parse for zone offsets #29351

abraithwaite opened this issue Dec 20, 2018 · 2 comments
Labels
Documentation Issues describing a change to documentation. NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Unplanned

Comments

@abraithwaite
Copy link
Contributor

abraithwaite commented Dec 20, 2018 •
edited
Loading

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

$ go version
go version go1.11.4 darwin/amd64

Does this issue reproduce with the latest release?

Yes. Checked master and docs have not changed in tip either.

What did you do?

https://play.golang.org/p/bvmvzOstarf

Edit: the zone in this should be PST, but the result is the same ^

What did you expect to see?

I expected to see the timezone offset to be set accordingly.

What did you see instead?

The timezone numeric offset was not set, despite Zone() returning a text zone.

Proposal

For those unfamiliar with timezones, we are unaware that timezone abbreviations are ambiguous. The docs make it clear that in order for those textual time zones to be parsed and set an offset, it must be parsed in the context of a location. However, it's not immediately clear that you will have a problem trying to parse dates with a timezone abbreviation.

I propose adding a simple line: "Timezone abbreviations like "MST" are ambiguous, therefore..." to the docs.

go/src/time/format.go

Lines 764 to 772 in 84066f1

// When parsing a time with a zone abbreviation like MST, if the zone abbreviation
// has a defined offset in the current location, then that offset is used.
// The zone abbreviation "UTC" is recognized as UTC regardless of location.
// If the zone abbreviation is unknown, Parse records the time as being
// in a fabricated location with the given zone abbreviation and a zero offset.
// This choice means that such a time can be parsed and reformatted with the
// same layout losslessly, but the exact instant used in the representation will
// differ by the actual zone offset. To avoid such problems, prefer time layouts
// that use a numeric zone offset, or use ParseInLocation.

We discovered this during a migration from Javascript, which does set a numeric offset even in the absence of a predefined location (servers location is UTC, but still parses PDT as -07:00)
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Dec 20, 2018
@agnivade
Copy link
Contributor

/cc @robpike

@agnivade agnivade changed the title Improve Documentation for time.Parse for zone offsets time: improve Documentation for Parse for zone offsets Jan 7, 2019
@ALTree ALTree added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Jul 3, 2019
@seankhliao seankhliao added this to the Unplanned milestone Aug 20, 2022
@seankhliao
Copy link
Member

looks like this was added.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
5 participants
@agnivade @ALTree @abraithwaite @gopherbot @seankhliao