time: add microseconds-based APIs

[pmarks-net]

The upper bound of a nanoseconds-since-1970 timestamp is not very far away, on the timescale of human civilization:

time.Unix(0, math.MaxInt64)
2262-04-11 23:47:16.854775807 +0000 UTC

Suggestions for improvement:

• Document the limits at https://golang.org/pkg/time/, and deprecate the UnixNano function.
• Create a UnixMicro function, which works until the year 294247.

I notice a lot of code that tries to implement UnixMicro as UnixNano()/1000, so it would be good to have a centralized, correct implementation.

[griesemer]

For Go25.

[adg]

I don't understand the complaint. This limitation is built into the design, and is why time.Unix first takes a seconds argument followed by a nanoseconds argument for precision.

time.Unix(math.MaxInt64, 0) represents the year 219250468, so I think this API is solid for the foreseeable future.

[adg]

Oh, I see. This is about UnixNano.

Note the docs already cover this:

The result is undefined if the Unix time in nanoseconds cannot be represented by an int64.

[pmarks-net]

The documentation should specify what the limits are, because the actual values can be surprising to people who assume that int64 is practically infinite. It seems bad to promote a time format which is more restrictive than YYYY without spelling out the risks.

And what about creating a microseconds interface? I haven't tested the following code yet, but you can observe that the conversion functions are nontrivial in both directions:

return time.Unix(usec / 1000000, (usec % 1000000) * 1000)

return t.Unix() * 1000000 + int64(t.Nanosecond() / 1000)

[adg]

Who uses microseconds (apart from JavaScript)?

[pmarks-net]

"Microseconds since 1970" a very common format within Google at least. Bigtable and Spanner are among the more prominent users.

[adg]

Seems like something worth considering.