time: add DateTime, DateOnly, TimeOnly format constants

[dsnet]

I propose the declaration of the following format constants to the time package:

const (
    DateTime = "2006-01-02 15:04:05"
    DateOnly = "2006-01-02"
)

Analyzing all Go code on the module proxy (as of 2022-04-01), here's a table of all common time formats sorted in popularity order:

Rank	Frequency	Format
1	75616	time.RFC3339
2	23954	time.RFC3339Nano
3	13312	"2006-01-02 15:04:05"
4	12332	"2006-01-02"
5	11940	time.RFC1123
6	2998	time.RFC1123Z
7	2871	time.UnixDate
8	2843	time.ANSIC
9	2820	"20060102"
10	2600	time.RFC822
11	2522	time.Kitchen
12	2499	"20060102150405"
13	2225	"15:04:05"
14	1503	time.RFC850
15	1410	time.Stamp
16	1374	"2006-01-02T15:04:05Z"
17	1302	"2006-01-02T15:04:05"
18	1152	"2006"
19	1149	"2006/01/02 15:04:05"
20	1133	time.StampMilli
21	1122	time.RFC822Z
22	1059	time.RubyDate
23	962	"15:04"
24	934	"2006-01-02 15:04:05.000"
25	879	"2006010215"
26	685	"15:04:05.000"
27	668	"2006-01-02 15:04"
28	646	"2006/01/02 - 15:04:05"
29	637	"2006/01/02"
30	552	time.StampNano
31	533	time.StampMicro

As can be seen, "2006-01-02 15:04:05" and "2006-01-02" are the 3rd and 4th most popular format constants. They are more popular than most of the other time format constants that did get a named declaration.

Given their popularity, I propose declaring:

const (
    DateTime = "2006-01-02 15:04:05"
    DateOnly = "2006-01-02"
)

Other constant name suggestions welcome.

[meling]

Perhaps TimeOnly for "15:04:05" at 13th place would also make sense.

[mpx]

ISODate: "2006-01-02" Is the ISO 8601 extended date format (basic is 20060102).
ISOTime: "15:04:05" is the ISO 8601 extended time format (basic is 150405).

RFC3339 provides the extended ISO date and time format - using T as the separator (mandatory) and including the timezone.

Perhaps something like ISODateAndTime could be used? Technically, ISODateTime should be RFC3339 without the timezone since ISO requires using the T (hence "DateAndTime").

[rsc]

It sounds like maybe

const (
    ISO8601 = "2006-01-02 15:04:05"
    ISO8601Nano = "2006-01-02 15:04:05.999999999"
    ISO8601Date = "2006-01-02"
)

This would align with RFC3339 and RFC3339Nano and add the date-only form.

Thoughts?

/cc @robpike

[rsc]

Also, thanks for the great data @dsnet

[robpike]

The ISO names are fine, but I see advantages to also having the nicer names like TimeOnly and DateOnly as aliases. I remain a fan of time.Kitchen, which is underused.

[dsnet]

I'm used to reading specs, but I'm overwhelmed by ISO 8601 🤯. On Wikipedia, it says:

Separating date and time parts with other characters such as space is not allowed in ISO 8601, but allowed in its profile RFC 3339.

If true, it seems that ISO8601 = "2006-01-02 15:04:05" is not be valid ISO 8601. What's really odd is that the source of that statement comes from RFC 3339 with no reference to where in ISO 8601 it says that.

(Side comment: Thank you Go language for having a simple and concise language specification).

[rsc]

OK, it sounds like we can't call these ISO8601, and maybe that's not specific enough either. But what should we call them instead?

    DateTime = "2006-01-02 15:04:05"
    DateTimeNano = "2006-01-02 15:04:05.999999999"
    DateOnly = "2006-01-02"
    TimeOnly = "15:04:05"
    TimeOnlyNano = "15:04:05.999999999"

But also the 9999 comes from the RFC3339 definition; Stamp has 0s instead, meaning that the digits are always there:

	Stamp      = "Jan _2 15:04:05"
	StampMilli = "Jan _2 15:04:05.000"
	StampMicro = "Jan _2 15:04:05.000000"
	StampNano  = "Jan _2 15:04:05.000000000"

I don't know which of these we'd want either.

Maybe we are biting off too much and should just do:

DateTime = "2006-01-02 15:04:05"
DateOnly = "2006-01-02"

and stop there?

[dsnet]

DateTime and DateOnly SGTM. I'm also okay with throwing in TimeOnly in the mix per #52746 (comment).

The Nano variants seem a bit excessive and don't have data to support their utility.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[AlexanderYastrebov]

The proposed formats are defined in the Internet Date/Time Format https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 so maybe names could be either RFC3339DateTime, RFC3339Date and RFC3339Time or InternetDateTime InternetDate and InternetTime.

[fzipp]

names could be either RFC3339DateTime, RFC3339Date and RFC3339Time

My preference is for a human-friendly name without yet another number sequence.

[AlexanderYastrebov]

My preference is for a human-friendly name without yet another number sequence.

What about InternetDateTime, InternetDate and InternetTime then to get away without lame Only suffix?

[meling]

My preference is for a human-friendly name without yet another number sequence.

What about InternetDateTime, InternetDate and InternetTime then to get away without lame Only suffix?

Only has an obvious meaning. The Internet prefix has nothing to do with these time formats.

[rsc]

Given @dsnet's data, let's consider doing:

DateTime = "2006-01-02 15:04:05"
DateOnly = "2006-01-02"
TimeOnly = "15:04:05"

Does anyone object to these?

[AlexanderYastrebov]

Analyzing all Go code on the module proxy (as of 2022-04-01), here's a table of all common time formats sorted in popularity order:

Would it be possible to tell how users name these constants?

names could be either RFC3339DateTime, RFC3339Date and RFC3339Time

My preference is for a human-friendly name without yet another number sequence.

Looking at the top two popular formats I think users mean to use "reduced" RFC3339 format. It is not something else because only RFC3339 format puts fields in descending order making string representations sortable. The field separator is also the same -.

The Internet prefix has nothing to do with these time formats.

As per #52746 (comment) these formats are somewhat defined in the RFC section named "Internet Date/Time Format". It also has a note about space separator used in these formats:

NOTE: ISO 8601 defines date and time separated by "T".
Applications using this syntax may choose, for the sake of
readability, to specify a full-date and full-time separated by
(say) a space character.

Usage in situ:

time.Parse(time.DateTime, s)
time.Parse(time.DateOnly, s)
time.Parse(time.TimeOnly, s)

vs

time.Parse(time.RFC3339DateTime, s)
time.Parse(time.RFC3339Date, s)
time.Parse(time.RFC3339Time, s)

vs

time.Parse(time.InternetDateTime, s)
time.Parse(time.InternetDate, s)
time.Parse(time.InternetTime, s)

[rsc]

Would it be possible to tell how users name these constants?

I think these were taken directly from the call sites. They name them like "2006-01-02".

[rsc]

Based on the discussion above, this proposal seems like a likely accept.
— rsc for the proposal review group

[rsc]

No change in consensus, so accepted. 🎉
This issue now tracks the work of implementing the proposal.
— rsc for the proposal review group

[gopherbot]

Change https://go.dev/cl/412495 mentions this issue: time: add DateTime, DateOnly, and TimeOnly

[gopherbot]

Change https://go.dev/cl/433277 mentions this issue: cmd/go/internal: optimize code with newly defined time.DateTime const…

[mvdan]

@gouguoyin this proposal is accepted and implemented, and you don't seem to be proposing anything for the time package, so that seems off-topic to me.