µPitch: add `Duration.nanoseconds(_:)`

This suggestion seems to be a clear API and could be used starting from minutes, resulting in the existing names until seconds, then continuing with unixMinutes, unixHours, unixDays, and unixWeeks. Thanks to the unix prefix developers would immediately understand that something is different about these compared to seconds and below.

If the documentation additionally mentions that these durations do not support leap seconds or summer time/winter time adjustments and should therefore not be used for calculating "the same time at a different day" and if the docs even mentioned how to do that correctly using a Calendar, then this added API surface could even help prevent current misusage by doing the calculation manually by the developer.

Additionally, we could also add functions named minutes, hours, days, and weeks (and even months and years) that take a calendar system as a parameter and together with their unix counterparts give developers full flexibility while at the same time communicating that anything above seconds is not exact anymore.

This would make calendar-based time calculation more discoverable. The docs could even state something like "calling this is equivalent to Calendar..." teaching them about the other API right when they need to learn it. I'm a big fan of meeting people where they are, even if that means we have two ways of doing the same thing – as long as the "convenience" APIs simply call into the "source" ones. And I think it's very common and natural that people want to call something like Date.now.advanced(by: .days(3, calendar: .current)) rather than having to start with Calendar.current.... This expresses the main intention first (moving the date by a certain duration) and the calendar becomes just a required implementation detail (a parameter), which I feel is more intuitive than the current API. Why not allow both?

3 Likes