proposal: time: Add RFC3339Milli and/or RFC3339Micro convenience constants to standard library

[mattwelke]

When I searched for this issue first, I found an issue in this repo and followed a chain of issues until I found this original issue where this was already suggested: #13291. Because that issue is locked, I can't add suggestion there. That's why I'm opening a new issue.

I'd like to request again that this be done. I understand the original feelings of the maintainers, where they hesitated to add more to a standard library without justification. Here's a use case I encountered today that I believe justifies this change. We use BigQuery on GCP, where we often use TIMESTAMP columns. They support up to microsecond precision, but no more precision than this. Some mechanisms for parsing values from strings into these columns will fail if the string has too much precision:

---

The solution for this particular use case is to provide a string with no more than microsecond precision:

---

The next level of precision the time package convenience constants provide is second precision with the time.RFC3339 constant. Unfortunately for us, this doesn't work for our use case, where we need at least millisecond precision in order to meaningfully use the data stored in those TIMESTAMP columns. I had to add code to our own code base that our developers will have to remember exists and that they must use instead of first looking at the standard library:

const (
	timeFormatRFC3339Micro = "2006-01-02T15:04:05.999999Z07:00"
)

---

I understand that as developers, it's our job to validate our data properly before storing it, but it would still be very useful to have an easy way, built into the language, for Go developers to parse standard time strings with more than second precision if nanosecond precision is too much for their use case.

[MiChAeLoKGB]

There are multiple languages that do not support precision resolution above microseconds (e.g. PHP).

At work we had to communicate with API's written in other languages like PHP and we either had to:

1. change the PHP side to strip additional precision resolution and keep the GO unchanged (ugly, wrong place to do such a "fix", slows down the app and a pain to do for multiple API's)
2. create custom RFC3339Micro constant and use that for our custom Time struct Marshall method.

Same applied to clients written for our API in other languages. Again, let's say your API is in GO, but you also provide a PHP client. You either have to write the client so it can cope with the nanosecond precision resolution, or return time in microseconds (IMO option 2 is preferred).

Not having to create a file with single missing time constant for every project would be nice.

[rsc]

t.Format(time.RFC3339Milli) (proposed) is equivalent to t.Round(time.Millisecond).Format(time.RFC3339Nano) (today), because RFC3339Nano uses .999999999 and when seconds fractions are formatted with 9s in a template, trailing zeros are discarded, not formatted.

We do have Stamp, StampMilli, StampMicro, and StampNano, but those are using .000, .000000, and .000000000.
That is, StampNano and RFC3339Nano are inconsistent about trailing zeros.

It would be inconsistent with RFC3339Nano to define RFC3339Milli with .000, but it would be inconsistent with StampMilli to define it with .999.

Rather than add more inconsistency, it seems like t.Round(time.Millisecond).Format(time.RFC3339Nano) is very clear and equivalent to what we'd provide with an explicit RFC3339Milli.

[mattwelke]

@rsc Thanks for that info. It appears that this could be better solved by documentation that instructs people to round their times to drop unneeded precision before formatting, like your example. I withdraw my proposal.

[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

[rsc]

This proposal has been declined as retracted.
— rsc for the proposal review group