Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

time: document Location's effect on Time more? #23316

Closed
pjebs opened this issue Jan 3, 2018 · 11 comments
Closed

time: document Location's effect on Time more? #23316

pjebs opened this issue Jan 3, 2018 · 11 comments

Comments

@pjebs
Copy link
Contributor

@pjebs pjebs commented Jan 3, 2018

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
Copy link
Contributor

@bradfitz bradfitz commented Jan 3, 2018

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.

@bradfitz bradfitz changed the title time.In seems to not work time: document Location's effect on Time more? Jan 3, 2018
@bradfitz bradfitz added this to the Go1.11 milestone Jan 3, 2018
@ulikunitz
Copy link
Contributor

@ulikunitz ulikunitz commented Jan 3, 2018

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
Copy link
Contributor

@bradfitz bradfitz commented Jan 3, 2018

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
Copy link
Contributor

@ulikunitz ulikunitz commented Jan 4, 2018

@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
Copy link

@gopherbot gopherbot commented Jun 20, 2018

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

@pjebs
Copy link
Contributor Author

@pjebs pjebs commented Jun 20, 2018

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
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Jun 20, 2018

@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
Copy link
Contributor Author

@pjebs pjebs commented Jun 21, 2018

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
Copy link
Contributor

@bradfitz bradfitz commented Jun 21, 2018

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

@pjebs pjebs closed this Jun 21, 2018
@bradfitz
Copy link
Contributor

@bradfitz bradfitz commented Jun 21, 2018

@pjebs, why are you closing it?

@pjebs
Copy link
Contributor Author

@pjebs pjebs commented Jun 21, 2018

I thought it was now sorted.

@pjebs pjebs reopened this Jun 21, 2018
@gopherbot gopherbot closed this in 3198b90 Jun 29, 2018
@golang golang locked and limited conversation to collaborators Jun 29, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants
You can’t perform that action at this time.