proposal: time: add civil time package

[jba]

I propose a package with minimal implementations of the types Date, Time and DateTime, which represent times without a corresponding location.

A civil time or date does not represent a point or interval of time, but they are useful for representing events transpiring between humans. For example, your birthday begins at midnight on your birthdate regardless of where you are in the world. If you're turning 21, you can buy a drink in New York at midnight, but teleport instantaneously to San Francisco and you'll be denied, because it is 9 PM the day before.

In practice, the main motivation for these types is to represent values in database-like storage systems, like BigQuery and Spanner (and other, non-Google products).

The package currently exists at cloud.google.com/go/civil, and has been in use by the BigQuery and Spanner client libraries for a few months. For now, I'd like to move it to golang.org/x/time/civil. It is probably too esoteric to be worth including in the standard library, but if there were ever a "second-tier" set of packages that augmented the standard library, it could live there. (See #17244.)

A CL is in progress at https://go-review.googlesource.com/c/38571.

[bradfitz]

If you're turning 18, you can buy a drink in New York at midnight, but teleport instantaneously to San Francisco and you'll be denied, because it is 9 PM the day before.

And because the drinking age in California is 21. The ballot measure never happened.

[jba]

21 in NY too, it turns out. Edited comment.

[kevinburke]

fun story... the drinking age is 21 in every state because of a law that withheld federal highway money unless states mandated 21 as the drinking age. https://en.wikipedia.org/wiki/National_Minimum_Drinking_Age_Act

[rsc]

On hold for #17244, which in turn is essentially blocked on understanding the long-term plan for package management. Soon.

[FlorianUekermann]

I left a comment on the implementation in the CL. I'll mirror the parts that are not about implementation details here:

In my opinion time.Duration already implements a civil time (see #20757 for a list of issues that may be interesting).

Please clarify the difference between a civil date and just a normal date (dates don't have timezone issues to my knowledge, especially because they don't represent a moment in time).
If a civil date is just a date I don't think creating a civil package is appropriate. A simple date package or adding a Date type to the time package would be sufficient. The latter would also be useful for reusing unexported functionality from time.

There are multiple tiny "date" packages that look more or less the same (I implemented one here https://godoc.org/github.com/infobaleen/date, but there are others which are practically identical).

[jba]

time.Duration paired with a reference time could represent a civil DateTime (not a civil Time, which is an odd beast that is nevertheless present in many SQL versions). We'd still want another type for DateTime because of the reference time. Also, the range of time.Duration is about 290 years, not nearly long enough for the range of applications we'd like to support (Sumerian calendars to Star Trek chronologies).

Since we need a civil DateTime type, and a civil Time type to support SQL, it seems reasonable to put the Date type in the same package with them. Since the time package is big enough as it is, a small, separate package makes sense.

[FlorianUekermann]

time.Duration paired with a reference time could represent a civil DateTime. . We'd still want another type for DateTime because of the reference time.

type Civil struct{ Date time.Date; Time time.Duration }, assuming a time.Date type (#21365) is implemented. Basically just two int64s in a struct.

Also, the range of time.Duration is about 290 years, not nearly long enough for the range of applications we'd like to support (Sumerian calendars to Star Trek chronologies).

Maybe I misunderstood the goal, as I don't see the range problem you are mentioning. Are you considering other calendars where a day doesn't have 24*60*60*1e9 nanoseconds?

[bradfitz]

Maybe I misunderstood the goal, as I don't see the range problem you are mentioning. Are you considering other calendars where a day doesn't have 246060*1e9 nanoseconds?

Other calendars are not a goal. The time package documents that:

The calendrical calculations always assume a Gregorian calendar, with no leap seconds.

[jba]

type Civil struct{ Date time.Date; Time time.Duration }, assuming a time.Date type (#21365) is implemented. Basically just two int64s in a struct.

Where does that type live? And what about the type that just represents a time of day (civil.TIme in my package)?

Maybe I misunderstood the goal, as I don't see the range problem you are mentioning. Are you considering other calendars where a day doesn't have 246060*1e9 nanoseconds?

I didn't understand your proposal. I thought you wanted to represent a DateTime as a duration from some single reference time, like Unix represents time as an offset from 1/1/1970.

[FlorianUekermann]

Where does that type live?

I don't have a strong opinion on that. I would suggest putting it in "exp" first and integrating it in "time" later

And what about the type that just represents a time of day (civil.TIme in my package)?

time.Duration is sufficient (look at it's metods). Maybe alias it.
If you need something to support SQL, I think that belongs in/under the sql package. The concept of civil Date and DateTime are useful in a much wider scope, that can be supported mote easily.

[lpar]

I've also needed a pure Date for SQL and other things, but I implemented it by wrapping time.Time. Might that be a better implementation approach?