Re: [RFC] Duration class

Hi On 2026-07-04 02:42, Pierre Joye wrote:

The $nanoseconds argument in the fromSeconds() constructor is intentionally limited to “the number of nanoseconds in a second” which means that the constructor can be reasoned about taking (fractional) seconds - the base unit of Durations - as a fixed point decimal. I do not consider this a break in the promise.

I do consider it breaks the promise. Additionally, it forces the user to do mental calculation and remember an arbitrary bound of 999,999,999 that doesn't exist in any of the APIs you cited as inspiration. Java's Duration.ofSeconds(long, long) explicitly documents carrying excess nanoseconds into seconds with no cap, Duration.ofSeconds(2, 1_000_000_001) produces the same value as Duration.ofSeconds(3, 1). Rust's Duration::new does the same. Temporal doesn't even carry by default. Temporal.Duration.from({ hours: 200, minutes: 17 }) is valid and preserves both values as given. None of the three reject or restrict a sub-unit's magnitude the way this proposal does.

See my reply to Marc as to how the fromSeconds() constructor is consistent with the other constructors in taking a single semantic value. If you want the overflow behavior, use an addition. For the Rust comparison, I could imagine that this is a deliberate choice to make the constructor infallible. Requiring users to Duration::new(seconds, nanos).expect("success") every time they want to create a Duration from (known-good) values would be pretty unergonomic. And similarly panicking for nanosecond overflow would be unreasonable in case user input makes it into the function. PHP’s (unchecked) exceptions provide a reasonable middle-ground here, because users would be able to cleanly handle the ValueError if they desire to do so. Java would again be closer to PHP here, but I'm not as familiar with how the Exception hierarchy is typically structured there.

A design goal of the constructors was that they are injective functions, i.e. there must be at most one way of creating a Duration with a specific length from any given constructor. This is in order to make it easy to reason about the resulting value, without needing to perform (mental) calculations.

If injectivity were the real goal, none of Java, Rust, or Temporal would be usable APIs by that standard, they're explicitly non-injective by design, and that hasn't stopped them from being the reference implementations you're citing as inspiration.

Yes, *inspiration*. We looked at those to see how others approach the problem, but of course built our own list of requirements and/or goals based on constraints imposed by PHP and also based on our experience of working with dates and times both in PHP and other programming languages. Best regards Tim Düsterhus