Add mb_str_split() UTF-8/ASCII chunking (#3299)

docs/capabilities.md

@@ -454,9 +454,11 @@ Auto-generated by `script/capability-matrix.php`. Do not edit by hand.
 | `mb_encoding_aliases` | yes | yes | yes | mbstring |  |
 | `mb_http_output` | yes | yes | yes | mbstring |  |
 | `mb_internal_encoding` | yes | yes | yes | mbstring |  |
+| `mb_list_encodings` | yes | yes | yes | mbstring |  |
 | `mb_preferred_mime_name` | yes | yes | yes | mbstring |  |
 | `mb_scrub` | yes | yes | yes | mbstring | AOT PHPT |
 | `mb_split` | yes | yes | yes | mbstring |  |
+| `mb_str_split` | yes | yes | yes | mbstring |  |
 | `mb_strcut` | yes | yes | yes | mbstring | AOT PHPT |
 | `mb_strimwidth` | yes | yes | yes | mbstring | JIT PHPT; AOT PHPT |
 | `mb_stripos` | yes | yes | yes | mbstring | JIT PHPT; AOT PHPT |

ext/mbstring/Module.php

@@ -34,6 +34,7 @@ public function getFunctions(): array
             new mb_check_encoding(),
             new mb_list_encodings(),
             new mb_strlen(),
+            new mb_str_split(),
             new mb_strwidth(),
             new mb_strimwidth(),
             ...(CompilerVersion::supportsMbStrPad() ? [new mb_str_pad()] : []),

ext/mbstring/VmMbstring.php

@@ -1960,6 +1960,47 @@ private static function mimeHeaderQDecode(string $payload): string
         return $out;
     }
 
+    /**
+     * mb_str_split() — split string into multibyte chunks (php-src ext/mbstring/mbstring.c; #3299).
+     *
+     * @return list<string>
+     */
+    public static function strSplit(string $string, int $length = 1, string $encoding = 'UTF-8'): array
+    {
+        if ($length <= 0) {
+            throw new \ValueError('mb_str_split(): Argument #2 ($length) must be greater than 0');
+        }
+        self::assertSubstrCountEncoding($encoding, 'mb_str_split');
+        if ('ASCII' === $encoding || '8BIT' === $encoding) {
+            return self::strSplitSingleByte($string, $length);
+        }
+        $charLen = VmString::utf8CharLength($string);
+        if (0 === $charLen) {
+            return [];
+        }
+        $result = [];
+        for ($i = 0; $i < $charLen; $i += $length) {
+            $result[] = VmString::utf8CharSubstr($string, $i, min($length, $charLen - $i));
+        }
+
+        return $result;
+    }
+
+    /** @return list<string> */
+    private static function strSplitSingleByte(string $string, int $length): array
+    {
+        $byteLen = VmString::byteLength($string);
+        if (0 === $byteLen) {
+            return [];
+        }
+        $result = [];
+        for ($i = 0; $i < $byteLen; $i += $length) {
+            $result[] = \substr($string, $i, min($length, $byteLen - $i));
+        }
+
+        return $result;
+    }
+
     /**
      * mb_split() — multibyte regex split (php-src ext/mbstring/php_mbregex.c; #13367).
      *

ext/mbstring/mb_str_split.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPCompiler\ext\mbstring;
+
+use PHPCompiler\ext\standard\VmString;
+use PHPCompiler\Frame;
+use PHPCompiler\Func\Internal;
+use PHPCompiler\JIT\Context;
+use PHPCompiler\JIT\Variable as JITVariable;
+use PHPCompiler\VM\BuiltinExecute;
+use PHPCompiler\VM\Variable;
+use PHPLLVM\Value;
+
+/**
+ * mb_str_split() — multibyte string to array (php-src ext/mbstring/mbstring.c; #3299).
+ */
+final class mb_str_split extends Internal
+{
+    public function __construct()
+    {
+        parent::__construct('mb_str_split');
+    }
+
+    public function execute(Frame $frame): void
+    {
+        $argc = \count($frame->calledArgs);
+        if ($argc < 1 || $argc > 3) {
+            throw new \ArgumentCountError(sprintf(
+                'mb_str_split() expects at least 1 argument, %d given',
+                $argc
+            ));
+        }
+        $string = VmString::coerceStringBuiltinArg(
+            $frame->calledArgs[0],
+            'mb_str_split',
+            0,
+            'string'
+        );
+        if (null === $frame->returnVar) {
+            return;
+        }
+        $length = 1;
+        if ($argc >= 2) {
+            $length = VmMbstring::coerceLengthArg($frame, 'mb_str_split', 1);
+        }
+        $encoding = $argc >= 3
+            ? VmMbstring::coerceEncodingArg($frame->calledArgs[2], 'mb_str_split', 2)
+            : 'UTF-8';
+        $result = VmMbstring::strSplit($string, $length, $encoding);
+        BuiltinExecute::writeReturn($frame, static function (Variable $ret) use ($result): void {
+            $ret->array(MbstringState::hashTableFromStringList($result));
+        });
+    }
+
+    public function call(Context $context, JITVariable ...$args): Value
+    {
+        throw new \LogicException('mb_str_split() is not lowered for JIT/AOT in this compiler build');
+    }
+}

test/compliance/cases/stdlib/mb_str_split.phpt

@@ -0,0 +1,35 @@
+--TEST--
+stdlib mb_str_split() UTF-8 and ASCII chunking (VM)
+--FILE--
+<?php
+var_export(mb_str_split('αβγ', 1));
+echo "\n";
+var_export(mb_str_split('ab', 2));
+echo "\n";
+var_export(mb_str_split('hello', 2, 'ASCII'));
+echo "\n";
+var_export(mb_str_split('', 1));
+echo "\n";
+try {
+    mb_str_split('x', 0);
+    echo "no_exception\n";
+} catch (ValueError) {
+    echo "length_zero=ValueError\n";
+}
+--EXPECT--
+array (
+  0 => 'α',
+  1 => 'β',
+  2 => 'γ',
+)
+array (
+  0 => 'ab',
+)
+array (
+  0 => 'he',
+  1 => 'll',
+  2 => 'o',
+)
+array (
+)
+length_zero=ValueError

test/repro/maintainer_gap_mb_str_split.php

@@ -0,0 +1,17 @@
+<?php
+
+var_export(mb_str_split('αβγ', 1));
+echo "\n";
+var_export(mb_str_split('ab', 2));
+echo "\n";
+var_export(mb_str_split('hello', 2, 'ASCII'));
+echo "\n";
+var_export(mb_str_split('', 1));
+echo "\n";
+
+try {
+    mb_str_split('x', 0);
+    echo "fail: no exception for length 0\n";
+} catch (ValueError $e) {
+    echo "length_zero=ValueError\n";
+}