Make Time\Duration exact on 32 bit platforms

multiplyBy() and divideBy() are the two operations whose intermediate values
do not fit in an integer when PHP_INT_SIZE is 4: a duration holds up to
2**61 nanoseconds. They used to throw Time\TimeException there, while the
native implementation computes the result with 64 bit arithmetic.

 * multiplyBy() now multiplies by doubling and adding (seconds, nanoseconds)
   pairs, which is exact whatever the integer width, and no longer needs the
   nanoseconds overflow guard
 * divideBy() falls back to a digit-wise division when the dividend does not
   fit in an integer; every intermediate value stays below 2**53, where
   floats represent integers exactly

The digit-wise division is unreachable on 64 bit platforms, so DurationTest
checks it against intdiv() there, since no CI job runs on 32 bit.

Author: nyamsprod

src/Time/README.md

@@ -7,15 +7,10 @@ added to PHP 8.6 core, for PHP >= 8.1:
 - `Time\TimeException`, `Time\Duration`
 
 The phpt tests of the native implementation, borrowed from php-src, run against
-the polyfill as part of the test suite. Two divergences remain:
-
-- `Duration` is a plain final class with readonly properties instead of a
-  `readonly` class, so `ReflectionClass::newInstanceWithoutConstructor()`
-  succeeds where the native class rejects it; dynamic properties are rejected
-  as they are natively.
-- On 32-bit platforms, operations whose intermediate values do not fit in an
-  integer throw `Time\TimeException` instead of returning the in-range result
-  the native implementation computes with 64-bit arithmetic.
+the polyfill as part of the test suite. One divergence remains: `Duration` is a
+plain final class with readonly properties instead of a `readonly` class, so
+`ReflectionClass::newInstanceWithoutConstructor()` succeeds where the native
+class rejects it. Dynamic properties are rejected as they are natively.
 
 More information can be found in the
 [main Polyfill README](https://github.com/symfony/polyfill/blob/main/README.md).

src/Time/Resources/stubs/Time/Duration.php

@@ -310,23 +310,26 @@ public function multiplyBy(int $factor): self
                 return $this;
             }
 
-            if (0 < $this->seconds && $factor > intdiv(self::MAX_SECONDS, $this->seconds)) {
-                throw new TimeException(self::RANGE_ERROR);
-            }
-
-            if (0 < $this->nanoseconds && $factor > intdiv(\PHP_INT_MAX, $this->nanoseconds)) {
-                throw new TimeException(self::RANGE_ERROR);
-            }
+            // double-and-add: multiplying the nanoseconds directly would overflow
+            $seconds = 0;
+            $nanoseconds = 0;
+            $addSeconds = $this->seconds;
+            $addNanoseconds = $this->nanoseconds;
+
+            while (true) {
+                if (1 & $factor) {
+                    [$seconds, $nanoseconds] = self::addMagnitudes($seconds, $nanoseconds, $addSeconds, $addNanoseconds);
+                }
 
-            $seconds = $this->seconds * $factor;
-            $nanoseconds = $this->nanoseconds * $factor;
-            $carry = intdiv($nanoseconds, self::NANOS_PER_SECOND);
+                if (0 === $factor >>= 1) {
+                    break;
+                }
 
-            if ($carry > self::MAX_SECONDS - $seconds) {
-                throw new TimeException(self::RANGE_ERROR);
+                // the remaining factor is not zero, so an out of range double is out of range for the result too
+                [$addSeconds, $addNanoseconds] = self::addMagnitudes($addSeconds, $addNanoseconds, $addSeconds, $addNanoseconds);
             }
 
-            return self::create($seconds + $carry, $nanoseconds % self::NANOS_PER_SECOND, $this->negative);
+            return self::create($seconds, $nanoseconds, $this->negative);
         }
 
         /**
@@ -354,11 +357,9 @@ public function divideBy(int $divisor): self
 
             $remainder = $this->seconds % $divisor;
 
-            if ($remainder > intdiv(\PHP_INT_MAX - $this->nanoseconds, self::NANOS_PER_SECOND)) {
-                throw new TimeException(self::RANGE_ERROR);
-            }
-
-            $nanoseconds = intdiv($this->nanoseconds + $remainder * self::NANOS_PER_SECOND, $divisor);
+            $nanoseconds = $remainder > intdiv(\PHP_INT_MAX - $this->nanoseconds, self::NANOS_PER_SECOND)
+                ? self::divideNanoseconds($remainder, $this->nanoseconds, $divisor)
+                : intdiv($this->nanoseconds + $remainder * self::NANOS_PER_SECOND, $divisor);
 
             return self::create(intdiv($this->seconds, $divisor), $nanoseconds, $this->negative);
         }
@@ -385,6 +386,69 @@ public function __set(string $name, mixed $value): void
             throw new \Error(\sprintf('Cannot create dynamic property %s::$%s', self::class, $name));
         }
 
+        /**
+         * Adds two non-negative (seconds, nanoseconds) pairs.
+         *
+         * @return array{0: int, 1: int}
+         *
+         * @throws TimeException when the sum is out of the representable range
+         */
+        private static function addMagnitudes(int $seconds, int $nanoseconds, int $addSeconds, int $addNanoseconds): array
+        {
+            if ($seconds > self::MAX_SECONDS - $addSeconds) {
+                throw new TimeException(self::RANGE_ERROR);
+            }
+
+            $seconds += $addSeconds;
+            // the sum of two nanoseconds components is always below 2**31
+            $nanoseconds += $addNanoseconds;
+
+            if ($nanoseconds >= self::NANOS_PER_SECOND) {
+                if (self::MAX_SECONDS === $seconds) {
+                    throw new TimeException(self::RANGE_ERROR);
+                }
+
+                ++$seconds;
+                $nanoseconds -= self::NANOS_PER_SECOND;
+            }
+
+            return [$seconds, $nanoseconds];
+        }
+
+        /**
+         * Returns intdiv($remainder * 1_000_000_000 + $nanoseconds, $divisor) for
+         * a $remainder that is lower than $divisor.
+         *
+         * The dividend does not fit in an integer on 32 bit platforms, so the
+         * division is done one decimal digit at a time. Every intermediate value
+         * stays below 2**53, where floats represent integers exactly.
+         */
+        private static function divideNanoseconds(int $remainder, int $nanoseconds, int $divisor): int
+        {
+            $quotient = 0;
+            $rest = (float) $remainder;
+
+            foreach (str_split(str_pad((string) $nanoseconds, 9, '0', \STR_PAD_LEFT)) as $digit) {
+                $rest = $rest * 10 + (int) $digit;
+                $digit = (int) ($rest / $divisor);
+                $rest -= $digit * $divisor;
+
+                // the float division may be off by one in either direction
+                while (0 > $rest) {
+                    --$digit;
+                    $rest += $divisor;
+                }
+                while ($rest >= $divisor) {
+                    ++$digit;
+                    $rest -= $divisor;
+                }
+
+                $quotient = $quotient * 10 + $digit;
+            }
+
+            return $quotient;
+        }
+
         /**
          * @throws TimeException when the duration is out of the representable range
          */

tests/Time/DurationTest.php

@@ -348,6 +348,35 @@ public static function provideOverflowingOperations(): array
         ];
     }
 
+    /**
+     * The digit-wise division is only reached on 32 bit platforms, where the dividend
+     * does not fit in an integer. Check it here against the integer arithmetic of a
+     * 64 bit platform, since no CI job runs on 32 bit.
+     */
+    public function testDivideNanosecondsMatchesIntegerArithmetic()
+    {
+        if (\PHP_VERSION_ID >= 80600) {
+            $this->markTestSkipped('This checks an implementation detail of the polyfill.');
+        }
+        if (8 > \PHP_INT_SIZE) {
+            $this->markTestSkipped('The expected values are computed with 64 bit integers.');
+        }
+
+        $divideNanoseconds = new \ReflectionMethod(Duration::class, 'divideNanoseconds');
+
+        foreach ([2, 3, 7, 10, 999999999, 1000000000, 1073741823, 2147483647] as $divisor) {
+            foreach ([0, 1, 2, 3, intdiv($divisor, 2), $divisor - 1] as $remainder) {
+                foreach ([0, 1, 5, 999999998, 999999999] as $nanoseconds) {
+                    $this->assertSame(
+                        intdiv($remainder * 1000000000 + $nanoseconds, $divisor),
+                        $divideNanoseconds->invoke(null, $remainder, $nanoseconds, $divisor),
+                        "intdiv($remainder * 1e9 + $nanoseconds, $divisor)"
+                    );
+                }
+            }
+        }
+    }
+
     public function testCompare()
     {
         $this->assertSame(0, Duration::compare(Duration::fromSeconds(1), Duration::fromSeconds(1)));