Skip to content
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.

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

time: improve Documentation for Parse for zone offsets #29351

abraithwaite opened this issue Dec 20, 2018 · 1 comment

time: improve Documentation for Parse for zone offsets #29351

abraithwaite opened this issue Dec 20, 2018 · 1 comment


Copy link

@abraithwaite abraithwaite commented Dec 20, 2018

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?

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.


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.


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)

Copy link

@agnivade agnivade commented Dec 23, 2018

/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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants