kindly CC @rsc (per https://dev.golang.org/owners)

We also believe that the specification of the time package should explicitly state the range of supported dates.

It should be possible to split codepath into slow and fast versions depending on the year value without defining any new constraints on the year value, shouldn't it?

We also believe that the specification of the time package should explicitly state the range of supported dates.

It should be possible to split codepath into slow and fast versions depending on the year value without defining any new constraints on the yer value, shouldn't it?

Thanks @AlexanderYastrebov . It's possible, but I'm not sure if it's suitable. I've changed some functions, like absDate, daysSinceEpoch and Date, and we would add some complexity (and another branch) for a range of date that is unusal and that other languages already don't support. IMHO we should even add some asserts and panic if the year is outside the "new" specification. Make sense?

@normandesjr

IMHO we should even add some asserts and panic if the year is outside the "new" specification. Make sense?

Panicking is a bit extreme, innit?

If I understand Cassio Neri's example C++ code correctly, he restricts values only for the duration of the calculation. Something like this (but also handling negative years):

	const (
		CycleLength     = SomeNumberIDK
		DaysPer400Years = 146097
		YearCycle       = 400 * CycleLength
		DayCycle        = DaysPer400Years * CycleLength
	)
	cycles, year := year / YearCycle, year % YearCycle
	days := CalculateDate(year, month, day)
	days += cycles * DayCycle

I would propose limiting timestamps to those that can be represented by int64 (i.e., handling overflow), or close to it (capping the year value to prevent overflow), and using the mechanism above to deal with calculations whose intermediate values may overflow.

Furthermore, Earth's rotation is slowing down which amplifies the problem

UTC is not the only kind of UT, so this shouldn't prevent me from printing the time when atoms started forming with nanosecond precision in my local timezone, so what if my city or my galaxy doesn't exist yet ;)

I wish to share my experience after having studied the Gregorian calendar and implemented myself support for it in the Linux Kernel, libstdc++, Firefox (for its Javascript engine) and also assisted others to implement them for .NET and Java (ongoing) official standard libraries and also a Rust user library.

The range of supported dates must be very clearly specified by the language as it is a contract which users can rely on. This is the first piece of information that I searched when I implemented these algorithms for any language's standard library.

What should be a reasonable range of dates selected by the language? There's no absolute answer for this question and @normandesjr's proposal cites a few choices taken by different languages. Pragmatism is required to select one since complications come from historical, geographical and astronomical aspects. To know more about the historical and geographical points, please, see my talk at C++ Now 2023 (from 27min7s) but let me elaborate on the astronomical point raised by @normandesjr and commented by @unixdj. This question is not about UTC and time zones.

Astronomers calculate that in the time of the dinosaurs, during a year Earth would spin about 400 times and not the 365 or so that it does nowadays. In other words, years were 400 days or so long. If there were people and computers around at that time they would most certainly not be using a calendar remotely similar to the Gregorian and thus for us to talk about 1st January year -65,000,000 is a bit of nonsense. Similarly, in a few million years the number of days in a year is expected to be far less than 365. I doubt the Gregorian calendar will still be used at this point. We don't need to go that far and even if Earth's movements were steady, the fact that the ratio between the duration of a day and the duration of a year is an irrational number means that the Gregorian calendar will be out of sync with Solstices and Equinoxes in a couple of thousands of years which again raises the question whether the Gregorian calendar will be used, unchanged, at this point.

In light of the above, should Golang commit itself to support a range of Gregorian dates spanning billions of years? IMHO, it should restrict the range to a more pragmatic one that suits well and efficiently the large majority of users now and in many generations to come but no more. A more restricted range allows more algorithms to be used and the best performing one (known or to be discovered) can be implemented. The point is that current users should not pay the price of using less performant algorithms that are destined to become obsolete far in the future just to support the current calendar far beyond its existence.

@normandesjr's proposal suggests picking the same range as C++ (from year -32767 to year 32767), which I believe is a very sensible choice, but anything not much larger than a few thousands of years is more than enough. Notice that changing the internal representation of time and its resolution is not proposed. Only conversion of internal representation from and to calendar dates (year, month, day) are touched.

Another advantage of a more restrictive range is that it allows a unit test to run through all possible dates and check the result. I've done that for libstdc++ and the Linux Kernel and these tests run under a second.

Finally, panicking if the input is out of range is useful. For Firefox, I added just a comment stating support for the range required by the JavaScript specification (Ecma-262). The thoughtful reviewer, Andre Bargul (towards whom I'm very grateful) asked me to assert that condition, which I did. Then a CI test crashed Firefox on this assertion revealing that there's was a bug elsewhere. He then fixed the bug for the benefit of all users.

I hope this helps. Obviously I'd be glad to see my own algorithms being used in Golang but the question of precision of the specification is, in my opinion, more important than the choice of algorithm. @normandesjr's proposal tackles this point. It's a very good proposal.

@cassioneri

The range of supported dates must be very clearly specified by the language

Definitely.

I'm inclined to make this range as broad as possible, because if you have a time.Time value, ideally you should be able to display it. Perhaps rather than restricting the range of supported days, a better idea would be to restrict the range of supported (or even "legal") Time values.

Also, see below regarding API compatibility.

This question is not about UTC and time zones.

Sure, I was not entirely serious about local time. And I was mistaken about UT, I meant TAI (International Atomic Time).

Loved your talk, BTW.

If there were people and computers around at that time they would most certainly not be using a calendar remotely similar to the Gregorian and thus for us to talk about 1st January year -65,000,000 is a bit of nonsense.

I would argue that perpetual Gregorian calendar is a fiction anyway, and astrophysicists talking about "13 billion years ago" is also a bit of nonsense, as you can't have a year without a planet.

Unless you define a year as 31,556,952 SI seconds, then it's fine I guess.

picking the same range as C++ (from year -32767 to year 32767), which I believe is a very sensible choice

The year range that tzcode (zoneinfo's code used in glibc and libc in many other Unix systems) supports is -2,147,481,748 to 2,147,485,547, which is the full range of int32_t whose 0 value means year 1900.

Finally, panicking if the input is out of range is useful.

Here I disagree. The Go standard library generally panics only on application programmer errors or if the internal state goes haywire. E.g., the time package panics on non-initialised Timer or Ticker values, non-positive intervals and nil Location values (application bugs), and on conditions indicating a bug in the standard library.

Time values may come from origins such as user input and database entries, and there may well be code out there that operates on values far away from now (e.g., for carbon dating or astrophysics), formatting the time as fmt.Sprintf(-t.Year() / 1000000, "million years ago"). Because if Go supports timestamps of almost 300 billion years from now, why roll your own?

Besides, introducing panics into date calculation code would break the Go 1 API compatibility promise. Which is another reason to support as wide range as possible.

@unixdj

[...] there may well be code out there that operates on values far away from now (e.g., for carbon dating or astrophysics), formatting the time as fmt.Sprintf(-t.Year() / 1000000, "million years ago").

Indeed, astrophysicists might be interested in billions of years. But this is a niche domain with clever people that are very capable of rolling their own algorithms.

Because if Go supports timestamps of almost 300 billion years from now, why roll your own?

For two reasons.

1. Supporting billions of years rules out algorithms that require fewer instructions (save memory, especially in instruction cache), are faster and spend less energy. Hence, if Golang support billions of years, every user will bear the costs for, presumably, the benefit of a few specialists in niche domains.

2. The clever people from these niche domains might not be interested in Time.Year() after all! Indeed, Time.Year() calculates the "year" that most of us consider in everyday live, i.e., year in the Gregorian calendar. (As you said, the "perpetual Gregorian calendar is a fiction anyway", so who uses it for calculations of billions of years?) Astronomers talk about sideral year, solar year, tropical year, vernal year, etc. They have their own time keeping system called Julian Day Number (JD) invented by Joseph Scaliger in 1583 and based on the average Julian calendar year of 365.25 days. Here is a quote from the International Astronomical Union (IAU) [1]:

Although there are several different kinds of year, the IAU regards a year as a Julian year of 365.25 days (31.5576 million seconds).

Hence, even if Time.Year() supports billion of years, for astronomers, it produces the wrong result and they won't use it.
Furthermore, from the number of SI seconds since the JD epoch, they can get the number of years by a simple division by 31,557,600. In summary, for astronomers Time.Year() is wrong and slower than what they can implement.

[1] https://www.iau.org/public/themes/measuring/

@cassioneri

Although there are several different kinds of year, the IAU regards a year as a Julian year of 365.25 days (31.5576 million seconds).

Interesting, I didn't know this.

But this is a niche domain with clever people that are very capable of rolling their own algorithms.

True. But I suspect that in many cases time.Time is probably involved at some point, which is what I meant by "why not" (it's there, might as well use it). I suspect that people working, say, with dates in Ancient Rome might wrap Time and override some methods for converting dates to use old Roman calendars before a certain date and call standard methods after, and astronomers might display the time as Julian years but convert it using Time.Unix for storage. Go enables this approach quite well, and I've done it with Time (for other reasons).

In any case, the Go core team will likely insist that the Go 1 compatibility promise is not broken.

Look, I understand your point. You never need to display the time of the formation of a galaxy as -11000000000-08-06 11:23:05.123456789 +0200 CEST. And I see that your algorithms are so fast that doing div-mod of the time by 10,000 or 100,000 years (perhaps conditionally after a comparison) will make calculations significantly slower.

Not the whole range works now, mind you. The time pkg doesn't convert dates before year -292277022399 of the perpetual Gregorian calendar, some 250 years after 1970-01-01 - 1<<63 seconds, correctly, and I expect weirdness on the other end too.

But I'm just not sure how much you can further restrict the range without breaking the compatibility promise that the Go team takes quite seriously.

And I hope you can see why panicking is not a good solution for Go, or at least for Go 1. I'm pretty sure the Go team would prefer to cap the value, return sentinel values or even document the limitation and return garbage.

Speaking of which, wouldn't a check like

if uint64(t) >= yearOneMillion {
	cycle, t = t / millionYears, t % millionYears
}
y, m, d := calculate(t)
y += cycle * 1000000

be almost as fast as this, for times within the range?

if t < lowLimit || t > highLimit {
	panic("what are you, an immortal?")
}
y, m, d := calculate(t)

As I wrote in #63844 (comment) it should be possible to have two implementations conditioned on the year value. The existing implementation would need to stay anyways to verify correctness of the new code. Once proof of the pudding exists it might be easier to establish new API constraints.

There is also a related #56909 that reports year overflow above/below certain values

I've given an idea about panic, it was like a suggestion, the main idea here is to have the great benefit of a date algorithm faster (more than 25%) for a range that everybody needs.

Change https://go.dev/cl/548155 mentions this issue: time: improve performance of calendar algorithms and clarify its spec…

I believe there's a misunderstanding about the scope of the proposal. Let me clarify.

It does not propose limiting all functionalities of time to smaller ranges. It covers only functions based on the Gregorian calendar, namely, Date, Year, Month, Day, ISOWeek, YearDay and AddDate.

Functions that only need the number of ticks from epoch remain the same. Going back to the astronomers example, they can get IAU year by calling t.Unix() and dividing the result by 31,557,600. The proposal would not change anything on this perspective and billions of IAU years would still be supported in this way.

@AlexanderYastrebov: There's no need to add an if. The 64-bits version of our algorithms can support billions of Gregorian years. This is more effective than adding the if but still more costly than using the 32-bits version (which supports "only" millions of years.) I'd prefer avoiding extra costs altogether since supporting billions of Gregorian years, as I'm trying to say, is meaningless.

As we can see from comments on other issues, as far as time is concerned, Go is very vague on its promises. People have revoursed to reverse engineering or to look very deeply in the sources to find out supported ranges. IMHO, the current situation is quite messy and fragile. I think this proposal is a step in the right direction to fix many issues. It sets out a reasonable range of dates that is enough for the vast majority, if not all, real users and brings clarity, speed and energy savings for them.

The 64-bits version of our algorithms can support billions of Gregorian years.

I took @normandesjr's code from https://github.com/normandesjr/go/blob/feat/date-algorithm/src/time/time.go and converted absDate and Date to use uint64. It works beautifully. Check this out (I used it outside the Go source tree, to avoid stashing my changes):

https://gist.github.com/unixdj/e31f75d5b49b5a2b3b4fbbae69368937

This is more effective than adding the if but still more costly than using the 32-bits version (which supports "only" millions of years.)

How much overhead does it add?

FWIW, a quick benchmark shows that my version of absDate runs faster. I looked at the assembly and eliminated one addition, but I don't speak amd64. First column: original, second: after changing the beginning of absDate as below, third: uint64, times for 100M runs.

        const (
                s = 3670
                K = 719468 + 146097*s
                L = 400 * s
        )
        N := uint32(abs/secondsPerDay - uint64(unixToInternal+internalToAbsolute)/secondsPerDay + K)

743.328392ms    708.183141ms    644.01476ms
718.081683ms    691.610367ms    653.935377ms
738.729335ms    701.506694ms    656.245927ms
736.034086ms    702.445939ms    641.974361ms
725.429312ms    688.144645ms    639.662721ms
722.263895ms    773.823083ms    657.371755ms
719.608441ms    696.451653ms    649.812959ms
715.551736ms    692.676515ms    647.024967ms

As we can see from comments on other issues, as far as time is concerned, Go is very vague on its promises.

True, unfortunately.

@normandesjr Can you also change isLeap to @cassioneri's algorithm?

@normandesjr Can you also change isLeap to @cassioneri's algorithm?

Done.

I've just did an update with @cassioneri's patch, follow the new benchmark:

Now takes more time now? That's weird.

It does not propose limiting all functionalities of time to smaller ranges. It covers only functions based on the Gregorian calendar, namely, Date, Year, Month, Day, ISOWeek, YearDay and AddDate.

So what would the behavior of Date be for a Time value produced by calling Add with a positive duration on the maximum supported time.Time?

I think we should not only limit the range, but also limit the intermediate values so that they don't exceed that range: it would be surprising to reject a value in time.Date only to have exactly that same value returned from a call to the Date method on a time.Time variable.

• (compare: time: unchecked overflow in Add and AddDays #20678 (comment))