time: add Time.ZoneBounds

[mjonss]

Export Location.lookup() as Location.Lookup() to help finding DST transitions.

Sometimes one want to find the when a zone transition starts or ends, which is already implemented in the non exported func (l *Location) lookup(sec int64) (name string, offset int, start, end int64, isDST bool)

Example: I need to correct '2021-03-28 02:30:00' in 'Europe/Amsterdam', which is in the non-existing hour during DST transition between CET and CEST, to the first coming valid time.
I.e. there is a requirement to have a function that takes a date and time in a DST Location and if it is incorrect, correct it to the first following correct date and time.

Setting the time and then reading it back may give a new time that is not at the DST transition, like: https://go.dev/play/p/sJdTyNZJPT6

And I don't expect time.Date() to change it current behaviour, but if there was an efficient way to find the DST transition one could easily just check the DST transition and correct it one self.

[ianlancetaylor]

We don't want to simply export the current Location.lookup method. That method takes and returns a number of seconds in the Unix epoch, but an exported method should use time.Time. For an exported API we should probably return some indication of ambiguity, when a time.Time value exists in two different timezones (e.g., when the hour between 1am and 2am is repeated in typical daylight savings time transitions).

Want to propose a useful API to export? Thanks.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[rsc]

It sounds like the need here is for a new method on time.Time that tells the time zone transitions to either side of the instant that is described by the time.Time? Do I have that right?

[mjonss]

It sounds like the need here is for a new method on time.Time that tells the time zone transitions to either side of the instant that is described by the time.Time? Do I have that right?

Yes, the primary need is to find the time zone transitions, since that information already exists, but is not exposed.

[ianlancetaylor]

Thanks. What about

// ZoneBounds returns the bounds of the time zone in effect at time t.
// The zone begins at start and the next zone begins at end.
// If the zone begins at the beginning of time, start will be returned as a zero Time.
// If the zone goes on forever, end will be returned as a Time in the very distant future.
// The Location of the returned times will be the same as t.
func (t Time) ZoneBounds() (start, end Time)

[martin-sucha]

Yeah, that might work. I like that ZoneBounds is simple. There are a couple limitations of that interface though, see below.

If the zone goes on forever, end will be returned as a Time in the very distant future.

Should we expose that future time as a constant or add a method to check for it (similar to IsZero()) to time.Time? Consider a program that prints the next 10 zone transitions is given a location that goes on forever without transitions, like UTC. That program will need to determine when to stop iterating.

How is the user supposed to iterate backwards in time? Subtract Duration(1) from start and call ZoneBounds() on the result?

So, daylight saving time flag, zone name and offset will be exposed with Time.IsDST and Time.Zone, right? IsDST/Zone do lookups currently, is it okay if we first do lookup in ZoneBounds() and then again for IsDST/Zone calls? While we could theoretically cache lookup results in Time, I would be cautious about making Time bigger.

If we wanted iteration that is O(1) instead of needing to do O(log N) lookup every time, we could cache the zone index, but it would require an additional type. What about something like

type Zone struct {
	// location that the zone is part of.
	location *Location
	// index of the current zone in Location.tx.
	// -1 if the first zone (lookupFirstZone) is used.
	// 0..len(Location.tx)-1 for a zone starting with the given transition index.
	// len(Location.tx) if we used extend string to build this Zone.
	index int
	// start time of the zone.
	// Zero time if the zone starts at the beginning of time.
	// This identifies the zone instance when using extend string.
	start Time
}

// Name of the zone.
func (z Zone) Name() string

// Offset of the zone east of UTC.
func (z Zone) Offset() Duration

// Start is the time when the zone starts.
// If the zone begins at the beginning of time, start will be returned as a zero Time and ok will be false.
func (z Zone) Start() (start Time, ok bool)

// End is the time when next zone starts.
// If the zone goes on forever, end will be returned as a Time in the very distant future and ok will be false.
func (z Zone) End() (end Time, ok bool)

// IsDST reports whether the time in the zone is in Daylight Savings Time.
func (z Zone) IsDST() bool

// LaterZone returns the next zone.
// If there is no later zone, LaterZone returns (z, false).
func (z Zone) LaterZone() (later Zone, ok bool)

// EarlierZone returns the previous zone.
// If there is no previous zone, EarlierZone returns (z, false).
func (z Zone) EarlierZone() (earlier Zone, ok bool)

// LookupZone describes the zone in effect at t.
// The Location of the times returned by the Zone will be the same as t.Location().
func (t Time) LookupZone() Zone

Disadvatages:

• Larger API surface.

Advantages:

• Efficient iteration of zones.
• Easy to add a field to the result in the future if needed.

For a use case like building a VTIMEZONE, we could add methods like:

// IsExtended returns true if the Zone was computed from an extend string.
func (z Zone) IsExtended() bool

// Extend returns the zone extend string.
func (l *Location) Extend() string

However, the name Zone might clash with types proposed in #49951. We could use ZoneIter instead of Zone, but I don't like ZoneIter as much as Zone.

[ianlancetaylor]

Should we expose that future time as a constant or add a method to check for it (similar to IsZero()) to time.Time?

Fair question. There is a tension between returning a zero result for the end of time and returning a time in the distant future. Returning a zero result makes it easy to see that there is no information but harder to write a quick comparison to see whether a time is in range. Defining a new constant or method extends the API only for purposes of this new method, which seems unfortunate.

How is the user supposed to iterate backwards in time?

Is this a common operation that needs to be supported efficiently in the low-level time package?

[martin-sucha]

If we are going to expose zone boundaries, we should probably document what a zone boundary is or isn't.

In valid TZif files, it seems that a transition time is when at least one of the following changes (RFC 8536, section 2):

• UT offset
• whether daylight saving time is in effect
• time zone abbreviation

although there is the following in RFC 8536, section 3.2:

Each value is used as a transition time at which the rules for computing local time may change.

so I'm not sure whether it is guaranteed that something changes.

Also I have no idea how the properties of boundaries look like if we are getting the zone data from another source, for example Windows.

[rsc]

If we wanted to do a scan of all known time zone changes at a given location, then assuming there are N of them, that scan takes O(N log N) with the simple API and O(N) with the complex API. But log N is tiny, since N is two per year. Is it really worth all this new API just to save a small constant factor? It seems hard to believe that it would be.

It seems like in the ZoneBounds API, end needs to be zero if there is no future switch, just so that loops can see a value to terminate with.

[rsc]

@mjonss would the API in #50062 (comment) address your use case?