Dup of #9346?

@ianlancetaylor #9346 was "frozen due to age" so PLEASE do not close this issue in favor of that other issue. I would like to keep this issue open since it doesn't seem like the other issue was resolved and we can't comment on it now since it was frozen due to age.

So I see two issues here:

• The example of RFC3339 output cannot be parsed and seems inaccurate.
• Parse(t.Format(F), F) should be valid and succeed without error. You should be able to successfully parse back into a time a string that you just formatted from a time. Parse/Format should be inverses of each other and both need to be reversible.

If the second bullet point doesn't hold, then time.Format is too risky to be used for serialization, because imagine if I format a bunch of times into strings to record them into a data file as in:

# File.csv
timeStr,Format
2006-01-02T15:04:05-07:00,RFC3339

I should be able to read this file back in and Parse back my time strings into time objects so I can use them. If I cannot, then time.Parse is risky and not useful for serialization. Even if this just applies to RFC3339, I really feel that we should fix this edge case/bug in RFC3339.

Thoughts?

I'm happy to help with a PR for a doc or code change if somebody can point me in the right direction as to how to get started.

Thanks! :-)

Your second bullet point does not hold. In general Parse and Format are not inverses of each other.

The best way to serialize and deserialize time.Time values is to use the MarshalText and UnmarshalText methods (or MarshalBinary and UnmarshalBinary). See https://golang.org/pkg/encoding; time.Time implements all of those interfaces.

Edit: Fixed typo in URL.

@ianlancetaylor thanks for responding. When you say "in general, Parse and Format are not inverses of each other", that alarms me. If that's the case, then what's the point of those methods? What is Parse parsing? Why is the output format of Format structured?

If you're suggesting that I use MarshalText etc., then how would I exchange times with a non-go program that doesn't support MarshalText formats? Not everbody uses JSON, so how would I interoperate with a non-go program to which I send RFC3339-formatted times and from which I would receive RFC3339-formatted times? If go's Format and Parse can't handle this format reliably then maybe RFC3339 should be removed from go?

Sorry, I'm not trying to be harsh here, but I'm really surprised to hear that Format/Parse are not inverses of each other ... What is their purpose and why are they paired in the same go pkg to use the same space of format strings then?

Thanks again, and I really appreciate your feedback and the work of the go team!

Best,

Joel

The point of the Format method and Parse function is for producing and parsing human-readable time strings. I understand why you expect them to be inverses, but that is not how they are documented. They are pretty close to being inverses. I forget where it fails.

If you want to define your own format to interoperate with a non-Go program, then define that format. You should be able to design a format that can use Format to produce that format and Parse to parse it.

By the way, I took a closer look at your program, and you are trying to use time.Parse to parse time.RFC3339 as though it were a formatted date. It is not. You will not be able to produce the same value as the constant time.RFC3339 using the Format method. And in your second call to Parse you seem to have reversed the format and the string you want to parse.

@ianlancetaylor thanks for replying. You're right, I did mixup the order of the layout and the value to be parsed (I'd argue that since Format expects the layout as the first arg, then so too should Parse, but my fault for not reading the arg sig in this case). I corrected my program and appended it below:

package main

import (
	"fmt"
	"time"
)

func main() {
	// From https://golang.org/pkg/time/#pkg-constants
	//
	//     RFC3339     = "2006-01-02T15:04:05Z07:00"
	timeStr := "2006-01-02T15:04:05Z07:00"

	// time.Parse fails on the sentinel example given in godoc
	parsed, errParsed := time.Parse(time.RFC3339, timeStr)
	fmt.Printf("parsed %v errParsed %v\n", parsed, errParsed)

	loc, errLoc := time.LoadLocation("MST")
	fmt.Printf("loc %v errLoc %v\n", loc, errLoc)

	t := time.Date(2006, 1, 2, 15, 4, 5, 0, loc)
	tStr := t.Format(time.RFC3339)

	fmt.Printf("tStr %v timeStr %v tStr == timeStr %v\n", tStr, timeStr, tStr == timeStr)

	// time.Parse fails on the sentinel example given in godoc
	parsed, errParsed = time.Parse(time.RFC3339, tStr)
	fmt.Printf("parsed %v errParsed %v\n", parsed, errParsed)
}

Now the output is as follows:

parsed 0001-01-01 00:00:00 +0000 UTC errParsed parsing time "2006-01-02T15:04:05Z07:00": extra text: 07:00
loc MST errLoc <nil>
tStr 2006-01-02T15:04:05-07:00 timeStr 2006-01-02T15:04:05Z07:00 tStr == timeStr false
parsed 2006-01-02 15:04:05 -0700 -0700 errParsed <nil>

So now the roundtrip within go DOES succeed (yay!) but the sentinel example given in the godoc "2006-01-02T15:04:05Z07:00" still does NOT parse.

Where does the godoc say that "the point of the Format method and Parse function is for producing and parsing human-readable time strings"?

I disagree that "this is not how they are documented". The documentation of the Parse method states Parse parses a formatted string and returns the time value it represents. "formatted" here refers to what? The logical conclusion reading this, IMHO, would be "formatted == formatted by the Format method". Is there another interpretation that was intended? The documentation of Parse explicitly mentions RFC3339 and also mentions time.Format in terms of layout, so it's reasonable to conclude from that mention that Format and Parse are interoperable in their formats. The example given in the godoc mentions that // The layout string used by the Parse function and Format method // shows by example how the reference time should be represented..

So maybe the confusion was the the value given in

const (
...
RFC3339     = "2006-01-02T15:04:05Z07:00"
...
)

is NOT actually representative of the values produced by Format for RFC3339 nor is it representative of the values that can be parsed by Parse for RFC3339? If that's the case, then I'd argue that it's misleading to represent the const as something that looks like a formatted time when in fact it's not a format that can be either produced by Format or parsed by Parse. In that case, since it's probably risky to change a const, maybe we could at least add a comment to the go src or at least the godoc to warn others about this?

I'm really not trying to be a PITA here, but I did find this confusing and was very surprise by go's behavior here and I just want to prevent others from having the same confusion.

Thanks again for your help! :-)

Yes, it is confusing, and there have been many dups of #9346.

RFC3339 is not a formatted time. It's a time format. Time formats do look like formatted times, by design, but they are not identical.

Fixes to the docs are always welcome, but make sure they are correct.

OK, I'll take a look next week when I have time ... Is there a procedure for updating the official godocs? Thanks!

Thanks. It's just like contributing source code: https://golang.org/doc/contribute.html

Change https://golang.org/cl/74231 mentions this issue: time: document valid layouts are not valid Parse values

Change https://golang.org/cl/74890 mentions this issue: time: improve comments about valid layouts being invalid Parse values