time: document Location's effect on Time more?

[pjebs]

Using Go 1.9

Documenation states:

func (t Time) In(loc *Location) Time
In returns t with the location information set to loc.

My interpretation is that the function In will change the location information but keep all other details the same. The consequence is that it will have a different Unix time usually since they represent different points in time.

startDate := ....   //startDate (time.Time) 2018-01-01 00:00:00 +1100 AEDT
_startDate := time.Date(startDate.Year(), startDate.Month(), startDate.Day(), startDate.Hour(), startDate.Minute(), startDate.Second(), startDate.Nanosecond(), time.UTC)
fmt.Println("startDate", spew.Sdump(startDate), spew.Sdump(startDate.In(time.UTC)), spew.Sdump(_startDate))

Output:

startDate (time.Time) 2018-01-01 00:00:00 +1100 AEDT
 (time.Time) 2017-12-31 13:00:00 +0000 UTC
 (time.Time) 2018-01-01 00:00:00 +0000 UTC

Expected output:
startDate.In(time.UTC)) and _startDate should produce same result

[bradfitz]

The consequence is that it will have a different Unix time usually since they represent different points in time.

That's not how it works.

This is working as intended:

bard:~ $ cat x.go
package main

import (
        "fmt"
        "time"
)

func main() {
        t := time.Now()
        fmt.Printf("%d: %v\n", t.Unix(), t)
        t = t.UTC()
        fmt.Printf("%d: %v\n", t.Unix(), t)
}
bard:~ $ go run x.go
1514954627: 2018-01-02 20:43:47.630243702 -0800 PST m=+0.000320305
1514954627: 2018-01-03 04:43:47.630243702 +0000 UTC

Note the identical unix time.

I admit the docs aren't super clear on this.

[ulikunitz]

UTC is not Unix time. Following short definitions may be helpful.

UTC: Coordinated Universal Time. UTC is within 1 second of the solar mean time at 0" longitude. For most purposes it can be considered to be interchangeable with Greenwich Mean Time (GMT), the latter is however not precisely defined anymore.

Unix time: Unix time is the number of seconds elapsed since 1. 1. 1970 00:00:00 UTC minus the leap seconds since then. (Leap seconds are applied to UTC because earth rotation is not constant and one rotation doesn't take exactly 86400 seconds.)

Local time: Legal time, subject to regulation, at a location. The time at a location may support daylight saving time, so the difference to UTC is not constant.

[bradfitz]

I only used UTC in my example because it was an easy way to get a different Location. I didn't mean to add to any confusion, but I also don't see any confusion about Unix vs UTC above.

[ulikunitz]

@bradfitz: I apologize for the wording, I changed the wording already yesterday, but this change isn't reflected in the emails going out.

What I wonder about what change of documentation is required. The example by @pjebs is using the local time (hour, minutes, second) to initialize _startDate as UTC. This is another point in time and is not equal to the original startDate.

The following program shows the proper use of In:

package main

import (
	"log"
	"time"
)

func main() {
	log.SetFlags(0)

	t0 := time.Now()
	log.Printf("t0: %s", t0)

	locShanghai, err := time.LoadLocation("Asia/Shanghai")
	if err != nil {
		log.Fatalf("LoadLocation error %s", err)
	}

	t1 := t0.In(locShanghai)
	log.Printf("t1: %s", t1)

	if t0.Equal(t1) {
		log.Print("t0 == t1")
	} else {
		log.Print("t0 != t1")
	}
}

[gopherbot]

Change https://golang.org/cl/120060 mentions this issue: time: clarify that Unix/UnixNano don't depend on location

[pjebs]

That's not what it should document. That's obvious.

It should state that once you create a Time struct, it's point in time (also represented by it's unix time) is immutable. Using the In() function does not change that. It only changes it's representation based on the new location.

That was actually what my original concern was about.

[ianlancetaylor]

@pjebs If I understand you correctly, it seems to me that that is already documented.

Changing the location in this way changes only the presentation; it does not change the instant in time being denoted.

[pjebs]

Documenation states:

func (t Time) In(loc *Location) Time
In returns t with the location information set to loc.

Maybe this should be made a bit clearer. My initial belief based on that statement was that the function returns a new Time struct with the same Year,Month,Day,Hour, Minute etc... EXCEPT with loc changed.

[bradfitz]

I've updated CL 120060 with some updated docs on In. PTAL.

[bradfitz]

@pjebs, why are you closing it?

[pjebs]

I thought it was now sorted.