Re: [RFC] Duration class

Hi On 2026-07-04 11:09, Marc B. wrote:

This is a simplified example what I mean: // Initial version final class Duration {

    public readonly $totalSeconds;
    public int $milliseconds { get => (int)($this->microseconds / 1_000); } // 0 - 999
    public readonly $microseconds; // 0 - 999_999
    public static function from(/* ... */ int $seconds=0, int $milliseconds=0, int $microseconds=0)

} // Next version - introduce nanoseconds final class Duration {

    public readonly int $totalSeconds;
    public int $milliseconds { get => (int)($this->nanoseconds / 1_000_000); } // 0 - 999
    public int $microseconds { get => (int)($this->nanoseconds / 1_000); } // 0 - 999_999
    public readonly int $nanoseconds; // 0 - 999_999_999
    public static function from(/* ... */ int $seconds=0, int $milliseconds=0, int $microseconds=0, int $nanoseconds=0)

} // Next version - introduce picoseconds final class Duration {

    public readonly int $totalSeconds;
    public int $milliseconds { get => (int)($this->picoseconds / 1_000_000_000); } // 0 - 999
    public int $microseconds { get => (int)($this->picoseconds / 1_000_000); } // 0 - 999_999
    public int $nanoseconds { get => (int)($this->picoseconds / 1_000); } // 0 - 999_999_999
    public readonly int $picoseconds; // 0 - 999_999_999_999
    public static function from(/* ... */ int $seconds=0, int $milliseconds=0, int $microseconds=0, int $nanoseconds=0, int $picoseconds=0)

} Introducing nanoseconds and later on picoseconds in that example isn't a big deal anymore.

It would still be, because you might unknowingly lose precision when someone gives you a Duration object with nanoseconds filled in, but you can only deal with microseconds, because your code was written before nanoseconds were supported.. Rounding down / truncating is the wrong behavior in many situations. See the “Passing Duration objects to APIs unable to handle nanosecond precision” section in the RFC.

For both of these, the false variant returns the value as a fixed-point decimal of seconds + fractional seconds, matching the “seconds with a fractional part” design of this RFC. For hrtime() specifically, you can even do the following:

    $duration = Duration::fromSeconds(...hrtime());

which will do the right thing (except for the fact that hrtime() *technically* returns an Instant [1], not a Duration). And of course the new date and time API would not be complete without also providing access to a high-precision (monotonic) clock in a way that cleanly interoperates with the new API. [1] An instant with an unknown origin.

Why would you create a duration directly from a point-in-time ?

I acknowledged in the parentheses that this modeling is not strictly correct from a semantic perspective, but it is meaningful: As Morgan explained, an instant (“point in time”) is effectively an origin + a Duration. Since hrtime() returns an instant retrieved from a monotonic clock, the origin is unknown to you and the only information you know is the duration. Thus you can represent this as just the Duration without losing any information. The only legal operation is calculating the difference, since for that the origin cancels out ((origin + duration1) - (origin + duration2)) is just (duration1 - duration2).

I'd argue that if I have the use case of constructing a duration from a number of seconds *and* multiple different fractions of a second that each could overflow into larger scales, I should likely stop and consider whether what I'm doing is a good idea. But even then:

    Duration::fromSeconds($seconds)
        ->add(Duration::fromMilliseconds($millis))
        ->add(Duration::fromMicroseconds($micros))
        ->add(Duration::fromNanoseconds($nanos));

will work and do the right thing.

The same applies to the nanoseconds argument of your fromSeconds() Duration::fromSeconds($seconds)->add(Duration::fromNanoseconds($nanos))

No, this behaves differently from the fromSeconds() constructor due to possible overflow in the $nanos component. The fromSeconds() constructor takes a fixed-point decimal which is a single semantic value and not appropriately represented by an explicit addition operation.

For the common case of “seconds + fractional seconds”, the fromSeconds() constructor works (and going from fractional milliseconds to fractional nanoseconds is a *1_000_000 operation that should be easy and obvious enough).

The hole point is to not need to manually calculate before and manually make sure it's in the expected range of the limited Duration constructor.

As mentioned in the previous paragraph: Each constructor takes a single “atomic value”. If you have an overflow in the microseconds, then it's no longer a single semantic value, but two values. It's the difference between “I have 1.5 seconds” and “I have 1 second and 500_000 microseconds” where the “and” is the addition operation. When I'm presented a web form as a user and it asks for a Duration with two fields “seconds” and “microseconds”, then I would fully expect a 0 <= microseconds < 1_000_000 validation happening there, and not a silent overflow into the seconds field that I explicitly provided. Similarly when asked for a date with separate year, month, day inputs, I would expect 2026-06-31 to be rejected as invalid instead of silently adjusting it to 2026-07-01, because as a user semantically I'm thinking about entering a single semantic value. Best regards Tim Düsterhus