Add splitWithOffset for PREG_SPLIT_OFFSET_CAPTURE

Author: Seldaek

src/Preg.php

@@ -189,11 +189,15 @@ public static function replaceCallbackArray(array $pattern, $subject, $limit = -
      * @param string $pattern
      * @param string $subject
      * @param int    $limit
-     * @param int    $flags
+     * @param int    $flags PREG_SPLIT_NO_EMPTY or PREG_SPLIT_DELIM_CAPTURE
      * @return list<string>
      */
     public static function split($pattern, $subject, $limit = -1, $flags = 0)
     {
+        if (($flags & PREG_SPLIT_OFFSET_CAPTURE) !== 0) {
+            throw new \InvalidArgumentException('PREG_SPLIT_OFFSET_CAPTURE is not supported as it changes the type of $matches, use splitWithOffset() instead');
+        }
+
         $result = preg_split($pattern, $subject, $limit, $flags);
         if ($result === false) {
             throw PcreException::fromFunction('preg_split', $pattern);
@@ -202,6 +206,24 @@ public static function split($pattern, $subject, $limit = -1, $flags = 0)
         return $result;
     }
 
+    /**
+     * @param string $pattern
+     * @param string $subject
+     * @param int    $limit
+     * @param int    $flags PREG_SPLIT_NO_EMPTY or PREG_SPLIT_DELIM_CAPTURE
+     * @return list<array{string, int}>
+     * @phpstan-return list<array{string, int<0, max>}>
+     */
+    public static function splitWithOffset($pattern, $subject, $limit = -1, $flags = 0)
+    {
+        $result = preg_split($pattern, $subject, $limit, $flags | PREG_SPLIT_OFFSET_CAPTURE);
+        if ($result === false) {
+            throw PcreException::fromFunction('preg_split', $pattern);
+        }
+
+        return $result;
+    }
+
     /**
      * @template T of string|\Stringable
      * @param string   $pattern