time: add a sentence about distant times to time.Time.Unix
Since Durations only span 290 years, they are not good for
manipulating very remote times. I bounced off this problem recently
while doing some astronomical calculations and it took me a while to
realize I could get a 64-bit seconds value from time.Time.Unix and
subtract two of them to evaluate the interval.
I thought it worth adding a sentence to make this clear. It didn't
occur to me for quite a while that "Unix time" spans a huge range in
the Go library.
Change-Id: I76c75dc951dfd6bcf86e8b0be3cfec518a3ecdee
Reviewed-on: https://go-review.googlesource.com/c/go/+/213977
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Reviewed-by: Andrew Gerrand <adg@golang.org>
diff --git a/src/time/time.go b/src/time/time.go
index 10a132f..5dc9fa6 100644
--- a/src/time/time.go
+++ b/src/time/time.go
@@ -1148,6 +1148,9 @@
// Unix returns t as a Unix time, the number of seconds elapsed
// since January 1, 1970 UTC. The result does not depend on the
// location associated with t.
+// Unix-like operating systems often record time as a 32-bit
+// count of seconds, but since the method here returns a 64-bit
+// value it is valid for billions of years into the past or future.
func (t Time) Unix() int64 {
return t.unixSec()
}
