can UTCDateTime be replaced with Instant?

[bxparks]

(Spun off from #59)

Ah, so you are using UTCDateTime as a substitute for Instant

The whole discussion on whether to have Instant or not probably belongs in its own issue. The fact that most modern libraries have this, is a strong signal for its usefulness. Having both UTCDateTime and Instant would probably be unnecessary

I can see some value in UTCDateTime, because it captures an intent of the developer, and it's more ergonomic than OffsetDateTime(offset=0).

Can UTCDateTime be replaced with an Instant class? The Instant class is a wrapper around an "epoch seconds". It provides type-safety and encapsulation. There should be an unambiguous 1-to-1 conversion between an Instant and UTCDateTime.

Here are some examples from other libraries:

• java.time has an Instant class that wraps a long (seconds) and an int (nanoseconds)
  • "the class stores a long representing epoch-seconds and an int representing nanosecond-of-second,"
• NodaTime implements an Instant class
  • (I don't know how to access its implementation source code)
  • it holds at least an Int64 as "milliseconds from UNIX epoch"
• GoLang provides a Time struct
  • it wraps 3 values: a uint64, an int64, and a pointer to a Location (i.e. TimeZone) object
  • Go's Time class contains a Location object, which makes it different than the Instant class in java.time and NodaTime
  • Go does not have a DateTime class hierarchy. Everything is derived from the Time object
• C++ has std::chrono::time_point which is implemented as a std::chrono::duration
  • I have no idea how it is actually implemented under the covers

I don't know, I can see both Instant and UTCDateTime being useful, because they capture slightly different things, and the ergonomics for the end-users are slightly different.

[bxparks]

It occurs to me that the Instant class would replace the float type returned by the timestamp() function mentioned in #63 .

[ariebovenberg]

My thoughts after some time:

Instant and UTCDateTime are very similar. In the end, if you normalize to UTC, you might as well be dealing with a timestamp/integer: you're usually not interested in the nominal month, day, hour in UTC. You're more likely interested in comparison or adding/subtracting

what I'm tending towards: keep UTCDateTime, but optimize it for comparison and shifting. It would probably be a timestamp under the hood.

[ariebovenberg]

An update to add here: In the rust extension I'm working on, UTCDateTime is Instant in almost everything but name.

Note that I'm still hanging on to the UTCDateTime name for these reasons:

• The name UTCDateTime will be more familiar to most users than Instant
• a UTC datetime is more human-friendly representation of an instant in time than an opaque integer class
• For some contexts such as airline or militairy, UTC datetime is a meaningful concept over an abstract integer
• Having different kinds of XXXXXDateTime in the API is already complex. Making Instant separate from them may confuse users.

---

It occurs to me that the Instant class would replace the float type returned by the timestamp() function mentioned in https://github.com/ariebovenberg/whenever/issues/63 .

Not necessarily... Instant can be opaque while the timestamp must be a an integer with a specific value 🤔

[ariebovenberg]

I've come around to Instant now:

• ~The name UTCDateTime will be more familiar to most users than Instant~ Most modern datetime libraries have Instant (or similar)
• ~a UTC datetime is more human-friendly representation of an instant in time than an opaque integer class~ The Instant repr will be a UTC datetime
• ~For some contexts such as airline or militairy, UTC datetime is a meaningful concept over an abstract integer~ yes, but hardly anybody uses is as a "local" time for calendar operations. In the rare case it is, ZonedDateTime can be used.
• ~Having different kinds of XXXXXDateTime in the API is already complex. Making Instant separate from them may confuse users.~ Still true, but many people are confused by having a separate class for UTC anyway.

The next release will replace UTCDateTime with Instant