time: document behaviour of Parse in the presence of >9 fractional second digits

[myitcv]

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

$ go version
go version devel go1.18-16d6a5233a Tue Jan 25 00:39:08 2022 +0000 linux/arm64

Does this issue reproduce with the latest release?

Yes

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

go env Output

$ go env
GO111MODULE=""
GOARCH="arm64"
GOBIN=""
GOCACHE="/home/myitcv/.cache/go-build"
GOENV="/home/myitcv/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="arm64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/myitcv/gostuff/pkg/mod"
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/myitcv/gostuff"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/myitcv/gos"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/myitcv/gos/pkg/tool/linux_arm64"
GOVCS=""
GOVERSION="devel go1.18-16d6a5233a Tue Jan 25 00:39:08 2022 +0000"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/dev/null"
GOWORK=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build3242720047=/tmp/go-build -gno-record-gcc-switches"

What did you do?

https://go-review.googlesource.com/c/go/+/353713/ made a change to Parse() to truncate fractional seconds longer than 9 digits.

I defer to others on whether truncating, rounding or error-ing is the "right" answer here, but I think a doc update is in order whatever the conclusion. As was pointed out in #48685, certain such inputs resulted in an error prior to CL 353713, and some people might have been relying on that behaviour.

What did you expect to see?

https://pkg.go.dev/time@go1.18beta1 to mention of the behaviour when >9 fractional second digits are provided.

Such a change might also warrant a mention in the release notes, given the behaviour change.

What did you see instead?

As it stands https://pkg.go.dev/time@go1.18beta1 makes no mention.

CC @rsc via https://dev.golang.org/owners

CC @AlexanderYastrebov and @jtbandes from #48685

[ianlancetaylor]

Can you suggest how the documentation should be changed? Thanks.

[myitcv]

I haven't looked into this fully, but I know that the behaviour pre CL 353713 caused some such inputs to time.Parse() to return an error. Post CL 353713, there is no error for those same inputs. Which begs the question for those people who previously saw/relied on the error, what is the behaviour now?

My only suggestion therefore would be to add some appropriate wording to https://pkg.go.dev/time@go1.18beta1#Parse that explains the new behaviour.

As I mentioned above, I very much defer to you/others on whether this change in behaviour warrants a mention in the release notes that references the https://pkg.go.dev/time@go1.18beta1#Parse docs I propose.

[ianlancetaylor]

Here is an example that causes an error with Go 1.17:

	fmt.Println(time.Parse(time.RFC3339, "2021-09-29T16:04:33.100000000001Z"))

With Go 1.17 this prints

0001-01-01 00:00:00 +0000 UTC parsing time "2021-09-29T16:04:33.100000000001Z": fractional second out of range

With Go tip this prints

2021-09-29 16:04:33.1 +0000 UTC <nil>

This seems clearly better. But I don't know how to document this except to say something like "fractional seconds that are too small to represent in a Time value are ignored." Does that seem like a useful addition?

[ianlancetaylor]

To put it another way, to me this seems to be clearly a bug fix. It's difficult for me to imagine that anybody relied on the error they got from using 10 or more digits in the fractional part. Especially since this, for example, does not give an error with Go 1.17, but instead returns the wrong result.

	fmt.Println(time.Parse(time.RFC3339, "2021-09-29T16:04:33.000100000001Z"))

1.17:

2021-09-29 16:04:33.100000001 +0000 UTC <nil>

tip:

2021-09-29 16:04:33.0001 +0000 UTC <nil>

[myitcv]

But I don't know how to document this except to say something like "fractional seconds that are too small to represent in a Time value are ignored." Does that seem like a useful addition?

Yes, something like that would work well.

To put it another way, to me this seems to be clearly a bug fix.

Agreed.

It's difficult for me to imagine that anybody relied on the error they got from using 10 or more digits in the fractional part. Especially since this...

Good point, thanks for that example.

The small doc change still seems worthwhile to my mind, but I totally defer to your judgement, especially with the 1.18 release not far away.

[ianlancetaylor]

I see this as a bug fix rather than a behavior change as such, so I don't think it needs to be explicitly called out in the release notes.

I'll send a patch for the docs.

[gopherbot]

Change https://golang.org/cl/381155 mentions this issue: time: document that Parse truncates to nanosecond precision

[myitcv]

I see this as a bug fix rather than a behavior change as such, so I don't think it needs to be explicitly called out in the release notes.

👍

I'll send a patch for the docs.

I just +1-ed. I'll defer to someone who owns the package to +2.