proposal: time: direct support for Unix millis and micros

[aebrahim]

Initial tl;dr: Go could make timestamp handling much easier by providing the following functions in its time library:

func (t Time) UnixMicro() int64 { ... }
func (t Time) UnixMilli() int64 { ... }
func FromUnixMicro(us int64) Time { ... }
func FromUnixMilli(ms int64) Time { ... }

Golang has time.Time as the idiomatic way of representing a time. However, not every API we encounter has this, and lots of them return Unix-style timestamps as int64 (sometimes uint64) in units of ms, us, or ns. For example, this will always occur when using API's that operate on protocol buffers, which use integers for timestamps instead of a native time type.

If we happen to have nanosecond timestamps, go is pretty nice. However, if we're using microseconds, then it gets fairly annoying to use time.Time, as you'll have to do error-prone type conversions everywhere, or rely on a timeutil library you write yourself for something which feels like it should be built in.

This is the type of stuff we have to do right now when dealing with niceapi that uses time.Time and otherapi that uses microseconds:

ts := otherapi.GetTimestamp()
t := time.Unix(0, ts * 1000) // one unit conversion, potential cause for bugs
niceapi.Use(t)

// elsewhere
t := niceApi.WhatTime()
ts := t.UnixNano() / 1000 // second unit conversion, potential cause for bugs
otherApi.Use(ts)

But why not

t := time.FromUnixMicro(otherapi.GetTimestamp()) // seems way less error prone to me
niceapi.Use(t)

// elsewhere
ts := niceApi.WhatTime().UnixMicro() // so easy!
otherApi.Use(ts)

[cespare]

I'm in favor of this. At $WORK we have an auxiliary time package that defines

func FromUnixMilli(ms int64) time.Time
func UnixMilli(t time.Time) int64

and these see a fair amount of use since ms-since-epoch is a common timestamp standard (as one example, you see it a lot in Javascript/web contexts since Date.now() returns ms).

[rsc]

The fact that Date.now() returns ms in Javascript is good context.

What common systems use micros?

The getters on time are unobjectionable; the new constructor names are not as nice. It would be easier to accept this proposal if we had a better idea for the names.

[aebrahim]

@rsc what do you think would be nicer for the constructor names? Is it better to name them UnixMicro and UnixMilli (to match the identically named getter and constructor style already being used)?

[aebrahim]

I don't think we should add milli without adding micro, because it would be a seemingly arbitrary omission to have 10^0, 10^-3, 10^-9, completely skipping 10^-6

But in any case, I looked around and I found a few instances of use for microseconds in time as well:
https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/TimeUnit.html#toMicros(long)
https://docs.python.org/2/library/datetime.html#datetime.time.microsecond
https://hackage.haskell.org/package/time-units-1.0.0/docs/Data-Time-Units.html
http://erlang.org/doc/man/erlang.html#type_time_unit
http://pubs.opengroup.org/onlinepubs/7908799/xsh/systime.h.html
http://www.cplusplus.com/reference/chrono/microseconds/

For cases that use floats instead of ints, microsecond precision also seems to be used sometimes:
http://php.net/manual/en/function.microtime.php
https://www.postgresql.org/docs/current/static/functions-datetime.html#FUNCTIONS-DATETIME-CURRENT
https://mariadb.com/kb/en/mariadb/microseconds-in-mariadb/

[rsc]

@aebrahim I didn't look at all of those, but the ones I did all seemed to be about turning (in Go terms) a time.Duration into microseconds, not about a time stamp expressed in microseconds since 1970. Go already does have time.Microsecond for computing with durations.

[aebrahim]

OK, I see what you mean. Here's a list of functions that use seconds, microseconds % seconds since the unix epoch:

• Unix gettimeofday
• Perl gettimeofday
• PHP gettimeofday
• python -c "import datetime; print(repr(datetime.datetime.now()))"
• Erlang:now
• Ruby time.at(seconds, microseconds_with_frac)

[rsc]

@aebrahim OK, but that's still not really motivation for adding t.UnixMicros() int64. What I'm hoping for is some evidence that this is a common serialized time format, used in file formats, network protocols, or other places where times are written down.

[mattalbr]

So a bunch of thoughts on this:

1. Supporting ns and s is arbitrary, ms and us seem logica extensions
2. time.Microsecond isn't good enough. One of the main arguments for passing around a Time instead of an int is that you don't have those pesky unit mismatch bugs. But because the time library uses constants instead of functions, you end up with conversion bugs ("do I multiply or divide by time.Microsecond....?").
3. If you're looking for how ugly things are with the current library, just read through http://stackoverflow.com/questions/24122821/go-golang-time-now-unixnano-convert-to-milliseconds and try not to scream at your monitor. If you succeed, you have more willpower than I do.

[ianlancetaylor]

Personally I don't see anything very wrong with

t.UnixNano() * int64(time.Nanosecond) / int64(time.Microsecond)

Not that I object strongly to t.UnixMicro() but it seems easy enough to convert from nanoseconds to microseconds.

I do agree with Russ: we should add UnixMicro if there is demand. Simply saying that it is a logical extension is not enough. Every new feature makes the package harder to understand. We should only add features that carry their weight.

[aebrahim]

My main issue with this is that it's the opposite of what you'd expect from unit conversions.

t.UnixNano() * int64(time.Nanosecond) / int64(time.Microsecond)

However, this is how you would do a unit conversion, with microseconds in the numerator instead of denominator:
40000 nanoseconds * 1 microsecond / 1000 nanoseconds.

This seems makes an already error prone operation even worse. This is way more error prone than just using microseconds everywhere to start with instead of using go's time.

[minux]

The formula is not too hard to come up, even if from unit conversion perspective: to convert ns to us, we need to multiply us/ns. assuming Go's abstract time unit is UNIT, then time.Nanosecond = UNIT/ns, and time.Microsecond = UNIT/us. Therefore to get the number of us/ns, we need scale = time.Nanosecond / time.Microsecond. That is: t.UnixNano() * time.Nanosecond / time.Microsecond.

[aebrahim]

I personally think that the math working out only with UNIT/ns really violates the principle of least astonishment. Especially when in other places, we do things like 3 * time.Microsecond