time: document in UnixNano when the value is valid

It is unlikely that the value of UnixNano overflow in most
use cases. However, the max date of 2262 is also within the range
where it may be of concern to some users. Rather than have each
person recompute when this overflows to validate if its okay for
their use case, we just document it as within the years 1678 and
2262, for user's convenience.

Fixes #16977

Change-Id: I4988738c147f4a6d30f8b8735c3941b75113bb16
Reviewed-on: https://go-review.googlesource.com/28478
Reviewed-by: Andrew Gerrand <adg@golang.org>

diff --git a/src/time/time.go b/src/time/time.go
index d04e30fa1fffd33c25557ac886a3bb4abd6f98f0..d3a9d1b3cd99de174e5e5cfbc01197ef8a423294 100644 (file)
--- a/src/time/time.go
+++ b/src/time/time.go
@@ -832,8 +832,9 @@ func (t Time) Unix() int64 {
 
 // UnixNano returns t as a Unix time, the number of nanoseconds elapsed
 // since January 1, 1970 UTC. The result is undefined if the Unix time
-// in nanoseconds cannot be represented by an int64. Note that this
-// means the result of calling UnixNano on the zero Time is undefined.
+// in nanoseconds cannot be represented by an int64 (a date before the year
+// 1678 or after 2262). Note that this means the result of calling UnixNano
+// on the zero Time is undefined.
 func (t Time) UnixNano() int64 {
        return (t.sec+internalToUnix)*1e9 + int64(t.nsec)
 }