docs: Instant vs ZonedDateTime

[iloveitaly]

Love the library!

I feel like I'm missing something obvious:

start_of_day = Instant.now().to_tz("UTC").start_of_day()

This is the best way I've found to get the start of the current day. It looks like you can't do this via the Instant object and converting to a ZonedDateTime is the only way to get start_of_day helpers and friends.

However, there's no now() method on ZonedDateTime, which makes getting the current time cumbersome. It's also confusing to me why Instant doesn't have the ZonedDateTime helpers.

I'm happy to contribute changes to the docs to explain this. If someone could explain to me how it works first! Thanks.

[ariebovenberg]

Hi @iloveitaly, thanks for posting: I'm always happy to hear feedback about the API 🙌

First, the short answer: ZonedDateTime does have a .now(), Perhaps it wasn't showing up for you in the autocomplete, or you missed it in the docs? The idiomatic way to get the start of the day in a particular timezone is:

ZonedDateTime.now(<chosen timezone>).start_of_day()

Or, if you'd like to get the start of the day in the currently set system timezone

SystemDateTime.now().start_of_day()

If you're only interested in the current date on the system, you can also do Date.today_in_system_tz()

---

Now, on to the deeper discussion

It's also confusing to me why Instant doesn't have the ZonedDateTime helpers.

There's definitely room for improvements to the docs here, but the absence of many of ZonedDateTime's methods and properties from Instant is intentional. This is because questions like "what is the start of this day" cannot be answered without knowing the timezone. Even a seemingly simple question like "what year is it" can give different results between timezones (i.e. around new year's eve). Instant is explicitly independent of timezones, making it very easy to reason about time as a linear concept. A consequence of this design it that it forces you to involve timezones when your use case requires it. You can't do Instant.now().year. While defaulting to UTC might be useful in many cases, it could silently trip up developers that haven't paused to think about the implications of asking these questions.

You are certainly not alone in your struggles. Question for you: what would have been most helpful for you to clear this up?

• A dedicated section in the "overview" documentation?
• a FAQ entry?
• having Instant.start_of_day() exist but raise a descriptive exception?

Also, feel free to share a bit more of your use case this also helps me improve the API.