time: add Time.UnixMilli and Time.UnixMicro (like Time.UnixNano)

[willyrgf]

I would like to implement a function time.UnixMills() to return t in int64 of milliseconds, like in the time.UnixNano() returns t in int64 of nanoseconds.
Today If I want to get the value of the time in milliseconds we need to do a lot of calculations, but I know other languages have this function and researching about that I've implemented that function in the time package.
It's a simple function with two const needed to easier understood.

Here is the simplest way that I've found to implement: https://go-review.googlesource.com/c/go/+/290772/1/src/time/time.go

This implementation is based on Rust as_millis(): https://doc.rust-lang.org/src/core/time.rs.html#393

---

EDITED:

First, thanks all for the contributions with all discuss, I had some problems and I couldn't contribute much during the discussions and initially not being able to expose all my points. Now all points have been discussed and we apparently have a consensus.

Just to format the proposal correctly with what was agreed.
Based on the discussions we will have both directions of the converters, generators and consumers and we probably will have something like that:

func (t Time) UnixMilli() int64 {}
func (t Time) UnixMicro() int64 {}

func UnixMilli(msec int64) Time {}
func UnixMicro(usec int64) Time {}

[cespare]

This was previously considered and rejected at #18935 and #27782.

I still think it's worth doing, though. (I think the name would be UnixMilli to match UnixNano, not UnixMills.)

One small thing that has changed since #27782 is that we added time.Duration.Milliseconds (and Microseconds) in #28564. That might lend a bit of weight toward UnixMilli.

To recapitulate some points I made on #27782 after it was closed:

1. I believe this is a common need (at least it has been in my work): proposal: time: direct support for Unix millis and micros - RE: #18935 #27782 (comment)
2. The fact that there's no popular third-party package implementing this isn't evidence of anything other than good taste (left-pad is not the Go way): proposal: time: direct support for Unix millis and micros - RE: #18935 #27782 (comment)

[rsc]

@willyrgf, what is the context where you need to do time calculations in Unix milliseconds?
#27782 was closed because we are unaware of a compelling need that justifies adding to the API.
We've heard a few people say "we use them at work" but nothing more widespread than that.
We are looking for some kind of standard reason you'd need that exact format.

[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

[cwaldren]

At work, we use milliseconds in protobuf messages, databases, and log messages. I can't recall any usage of time.UnixNano() besides converting to milliseconds. In many of these places, authors have debated/searched/reluctantly settled on different approaches, usually one of:

time.UnixNano() / int64(time.Millisecond)
time.UnixNano() / 1e6

This confuses new Go developers ("Am I doing this wrong? I must be missing something obvious.."), and makes normally straightforward code harder to mentally parse. Adding a dedicated user-defined library call to solve this problem isn't satisfactory:

1. It makes the code asymmetric (time.UnixMilli() vs millis.From(time.Now()))
2. It requires all developers to discover this package, then call it out in code reviews or add automatic linting
3. It requires perpetual maintenance, as was called out in another comment in relation to maintaining the standard library. But instead of having one set of maintainers, we have N for every team out there in the world developing with Go.

[ulikunitz]

Please have a look at package https://pkg.go.dev/github.com/ulikunitz/unixtime, which I wrote for #27782.

On pkg.go.dev it has no reported imports, but on github.com there are 865 clones and 145 unique cloners.

[andig]

Used ms timestamps on a couple of php projects, never used nanos except in Go for converting to mill8s.

[msiebuhr]

JavaScript works in milliseconds; e.g. Date.now() and x = new Date(); x.getTime() returns unix-time in milliseconds, as well as new Date(<number>) expecting milliseconds. Any significant JavaScript code-base I ever worked on has made use of milliseconds for date-serialization (and timezone-independent time-comparison).

I've only written a few go-programs with considerable JavaScript-interactions, but in all of those, time.UnixNano() / 1e6 was a fairly common occurrence (and source of bugs if one does not use it often enough to remember if it's 1e3, 1e6 or 1e9...)

[josharian]

Another API option is

func (Time) SinceUnix() time.Duration

Better name welcome.

Then you could write t.SinceUnix().Milliseconds().

Or t.SinceUnix().Seconds() or t.SinceUnix().Nanoseconds(), for that matter.

Other name ideas:

• SinceEpoch
• SinceUnixEpoch
• UnixDuration (via @benhoyt)

[willyrgf]

Thanks everyone for all suggestions, ideas and the questions. I'll edit the proposal and present a more completed proposal with all my arguments for each suggetions, ideas and questions sent here.

[randall77]

Or t.Sub(time.Unix(0,0)).Milliseconds(). No API changes required.

[benhoyt]

@josharian I definitely prefer that suggestion, though my name suggestion would be UnixDuration, as in t.UnixDuration().Milliseconds(). Would have been nice if Unix had returned a duration to begin with, and then we would have only needed one, but oh well.

@randall77's suggestion is not bad, though it's a bit awkward.