Stdlib: sprintf() for VM, JIT, and AOT

docs/bootstrap-inventory.md

@@ -1,5 +1,3 @@
-Wrote /compiler/docs/bootstrap-inventory.md (252 files, 10 blockers)
-Wrote /compiler/docs/bootstrap-profile.json (2 AOT lint targets, 2 excluded files)
 # Bootstrap inventory (vm.php path)
 
 Auto-generated by `script/bootstrap-inventory.php`. Tracks **Phase A** of [#212](https://github.com/PurHur/php-compiler/issues/212) (self-host bootstrap).
@@ -10,9 +8,9 @@ Regenerate: `php script/bootstrap-inventory.php`
 
 | Metric | Count |
 |--------|------:|
-| PHP files on vm.php path | 252 |
+| PHP files on vm.php path | 255 |
 | Source constructs flagged (blockers) | 10 |
-| Source constructs flagged (warnings) | 657 |
+| Source constructs flagged (warnings) | 661 |
 
 ## Compiler CFG gaps (`lib/Compiler.php`)
 
@@ -53,6 +51,7 @@ These `LogicException` messages indicate CFG ops or expressions not yet lowered:
 | `ext/standard/JitRandomBytes.php` | 0 | 1 |
 | `ext/standard/JitRealpath.php` | 0 | 1 |
 | `ext/standard/JitRequestBody.php` | 0 | 1 |
+| `ext/standard/JitSprintf.php` | 0 | 1 |
 | `ext/standard/JitStrPad.php` | 0 | 1 |
 | `ext/standard/JitStrRepeat.php` | 0 | 1 |
 | `ext/standard/JitStrReplace.php` | 0 | 1 |
@@ -63,13 +62,14 @@ These `LogicException` messages indicate CFG ops or expressions not yet lowered:
 | `ext/standard/JitStrpos.php` | 0 | 1 |
 | `ext/standard/JitUrlencode.php` | 0 | 1 |
 | `ext/standard/JitWebParams.php` | 0 | 11 |
-| `ext/standard/Module.php` | 0 | 115 |
+| `ext/standard/Module.php` | 0 | 116 |
 | `ext/standard/VmDate.php` | 0 | 1 |
 | `ext/standard/VmExit.php` | 0 | 2 |
 | `ext/standard/VmFs.php` | 0 | 3 |
 | `ext/standard/VmJson.php` | 0 | 1 |
 | `ext/standard/VmNumberFormat.php` | 0 | 1 |
 | `ext/standard/VmScope.php` | 0 | 3 |
+| `ext/standard/VmSprintf.php` | 0 | 1 |
 | `ext/standard/VmString.php` | 0 | 4 |
 | `ext/standard/abs.php` | 0 | 1 |
 | `ext/standard/array_combine.php` | 0 | 3 |
@@ -154,6 +154,7 @@ These `LogicException` messages indicate CFG ops or expressions not yet lowered:
 | `ext/standard/scandir.php` | 0 | 1 |
 | `ext/standard/sin.php` | 0 | 1 |
 | `ext/standard/sort_.php` | 0 | 3 |
+| `ext/standard/sprintf_.php` | 0 | 1 |
 | `ext/standard/sqrt.php` | 0 | 1 |
 | `ext/standard/str_contains.php` | 0 | 1 |
 | `ext/standard/str_ends_with.php` | 0 | 1 |
@@ -377,6 +378,11 @@ These `LogicException` messages indicate CFG ops or expressions not yet lowered:
 **Warnings** (review for bootstrap subset):
 - 1 class method(s) — PHPCfg Op\Stmt\ClassMethod not lowered in Compiler
 
+### `ext/standard/JitSprintf.php`
+
+**Warnings** (review for bootstrap subset):
+- 2 class method(s) — PHPCfg Op\Stmt\ClassMethod not lowered in Compiler
+
 ### `ext/standard/JitStrPad.php`
 
 **Warnings** (review for bootstrap subset):
@@ -503,57 +509,58 @@ These `LogicException` messages indicate CFG ops or expressions not yet lowered:
 - new array_pop (line 82)
 - new array_shift (line 83)
 - new sort_ (line 84)
-- new array_values (line 85)
-- new array_keys (line 86)
-- new array_merge (line 87)
-- new array_slice (line 88)
-- new explode (line 89)
-- new implode (line 90)
-- new str_replace (line 91)
-- new nl2br (line 92)
-- new array_reverse (line 93)
-- new array_search (line 94)
-- new array_sum (line 95)
-- new array_product (line 96)
-- new array_flip (line 97)
-- new array_unique (line 98)
-- new array_fill (line 99)
-- new array_combine (line 100)
-- new range (line 101)
-- new bin2hex (line 102)
-- new hex2bin (line 103)
-- new random_bytes (line 104)
-- new str_pad (line 105)
-- new str_split (line 106)
-- new htmlspecialchars (line 107)
-- new strip_tags (line 108)
-- new header_ (line 109)
-- new header_remove (line 110)
-- new header_list (line 111)
-- new getallheaders_ (line 112)
-- new http_response_code (line 113)
-- new json_encode (line 114)
-- new web_int (line 115)
-- new web_string (line 116)
-- new web_bool (line 117)
-- new urlencode (line 118)
-- new rawurlencode (line 119)
-- new urldecode (line 120)
-- new rawurldecode (line 121)
-- new parse_url (line 122)
-- new dirname (line 123)
-- new basename (line 124)
-- new realpath (line 125)
-- new file_get_contents (line 126)
-- new getenv_ (line 127)
-- new putenv_ (line 128)
-- new extract_ (line 129)
-- new compact_ (line 130)
-- new scandir (line 131)
-- new glob_ (line 132)
-- new time (line 133)
-- new date (line 134)
-- new gmdate (line 135)
+- new sprintf_ (line 85)
+- new array_values (line 86)
+- new array_keys (line 87)
+- new array_merge (line 88)
+- new array_slice (line 89)
+- new explode (line 90)
+- new implode (line 91)
+- new str_replace (line 92)
+- new nl2br (line 93)
+- new array_reverse (line 94)
+- new array_search (line 95)
+- new array_sum (line 96)
+- new array_product (line 97)
+- new array_flip (line 98)
+- new array_unique (line 99)
+- new array_fill (line 100)
+- new array_combine (line 101)
+- new range (line 102)
+- new bin2hex (line 103)
+- new hex2bin (line 104)
+- new random_bytes (line 105)
+- new str_pad (line 106)
+- new str_split (line 107)
+- new htmlspecialchars (line 108)
+- new strip_tags (line 109)
+- new header_ (line 110)
+- new header_remove (line 111)
+- new header_list (line 112)
+- new getallheaders_ (line 113)
+- new http_response_code (line 114)
+- new json_encode (line 115)
+- new web_int (line 116)
+- new web_string (line 117)
+- new web_bool (line 118)
+- new urlencode (line 119)
+- new rawurlencode (line 120)
+- new urldecode (line 121)
+- new rawurldecode (line 122)
+- new parse_url (line 123)
+- new dirname (line 124)
+- new basename (line 125)
+- new realpath (line 126)
+- new file_get_contents (line 127)
+- new getenv_ (line 128)
+- new putenv_ (line 129)
+- new extract_ (line 130)
+- new compact_ (line 131)
+- new scandir (line 132)
+- new glob_ (line 133)
+- new time (line 134)
+- new date (line 135)
+- new gmdate (line 136)
 - 2 class method(s) — PHPCfg Op\Stmt\ClassMethod not lowered in Compiler
 
 ### `ext/standard/VmDate.php`
@@ -591,6 +598,11 @@ These `LogicException` messages indicate CFG ops or expressions not yet lowered:
 - new Variable (line 92)
 - 6 class method(s) — PHPCfg Op\Stmt\ClassMethod not lowered in Compiler
 
+### `ext/standard/VmSprintf.php`
+
+**Warnings** (review for bootstrap subset):
+- 5 class method(s) — PHPCfg Op\Stmt\ClassMethod not lowered in Compiler
+
 ### `ext/standard/VmString.php`
 
 **Warnings** (review for bootstrap subset):
@@ -1036,6 +1048,11 @@ These `LogicException` messages indicate CFG ops or expressions not yet lowered:
 - 2 class method(s) — PHPCfg Op\Stmt\ClassMethod not lowered in Compiler
 - 1 closure(s)
 
+### `ext/standard/sprintf_.php`
+
+**Warnings** (review for bootstrap subset):
+- 2 class method(s) — PHPCfg Op\Stmt\ClassMethod not lowered in Compiler
+
 ### `ext/standard/sqrt.php`
 
 **Warnings** (review for bootstrap subset):

docs/bootstrap-profile.json

@@ -1,4 +1,3 @@
-Wrote /compiler/docs/bootstrap-profile.json (2 AOT lint targets, 2 excluded files)
 {
     "phase": "B",
     "issue": 212,
@@ -50,6 +49,7 @@ Wrote /compiler/docs/bootstrap-profile.json (2 AOT lint targets, 2 excluded file
         "ext/standard/JitRandomBytes.php",
         "ext/standard/JitRealpath.php",
         "ext/standard/JitRequestBody.php",
+        "ext/standard/JitSprintf.php",
         "ext/standard/JitStrPad.php",
         "ext/standard/JitStrRepeat.php",
         "ext/standard/JitStrReplace.php",
@@ -67,6 +67,7 @@ Wrote /compiler/docs/bootstrap-profile.json (2 AOT lint targets, 2 excluded file
         "ext/standard/VmJson.php",
         "ext/standard/VmNumberFormat.php",
         "ext/standard/VmScope.php",
+        "ext/standard/VmSprintf.php",
         "ext/standard/VmString.php",
         "ext/standard/abs.php",
         "ext/standard/array_combine.php",
@@ -151,6 +152,7 @@ Wrote /compiler/docs/bootstrap-profile.json (2 AOT lint targets, 2 excluded file
         "ext/standard/scandir.php",
         "ext/standard/sin.php",
         "ext/standard/sort_.php",
+        "ext/standard/sprintf_.php",
         "ext/standard/sqrt.php",
         "ext/standard/str_contains.php",
         "ext/standard/str_ends_with.php",
@@ -287,9 +289,9 @@ Wrote /compiler/docs/bootstrap-profile.json (2 AOT lint targets, 2 excluded file
         "test/bootstrap-aot/echo_hello.php"
     ],
     "totals": {
-        "inventory_files": 252,
+        "inventory_files": 255,
         "excluded": 2,
-        "eligible": 250,
+        "eligible": 253,
         "aot_lint_targets": 2
     }
 }

docs/capabilities.md

@@ -101,6 +101,7 @@ Auto-generated by `script/capability-matrix.php`. Do not edit by hand.
 | `sin` | yes | yes | yes | standard |  |
 | `sizeof` | yes | yes | yes | standard |  |
 | `sort` | yes | yes | yes | standard |  |
+| `sprintf` | yes | yes | yes | standard | JIT PHPT; AOT PHPT |
 | `sqrt` | yes | yes | yes | standard |  |
 | `str_contains` | yes | yes | yes | standard | AOT PHPT |
 | `str_ends_with` | yes | yes | yes | standard | AOT PHPT |

ext/standard/JitSprintf.php

@@ -0,0 +1,111 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PHPCompiler\ext\standard;
+
+use PHPCompiler\JIT\Context;
+use PHPCompiler\JIT\JitValueBox;
+use PHPCompiler\JIT\Variable as JITVariable;
+use PHPLLVM\Value;
+
+/**
+ * LLVM JIT/AOT helper for sprintf() (%s, %d, %f, %%).
+ */
+final class JitSprintf
+{
+    public static function format(Context $context, JITVariable ...$args): Value
+    {
+        $argc = \count($args);
+        if ($argc < 1) {
+            throw new \LogicException('sprintf() requires at least one argument');
+        }
+        if (JITVariable::TYPE_STRING !== $args[0]->type) {
+            throw new \LogicException('sprintf() format must be a string in this compiler build');
+        }
+        $fmt = $context->helper->loadValue($args[0]);
+        $numArgs = $argc - 1;
+        if (0 === $numArgs) {
+            $nullArgv = $context->builder->pointerCast(
+                $context->getTypeFromString('int64')->constInt(0, false),
+                $context->getTypeFromString('__value__*')
+            );
+
+            return $context->builder->call(
+                $context->lookupFunction('__compiler_sprintf'),
+                $fmt,
+                $context->getTypeFromString('int64')->constInt(0, false),
+                $nullArgv
+            );
+        }
+
+        $valueTy = $context->getTypeFromString('__value__');
+        $argvSlot = $context->builder->alloca($valueTy, $numArgs, 'sprintf_argv');
+        for ($i = 0; $i < $numArgs; ++$i) {
+            $slot = $context->builder->inBoundsGEP(
+                $argvSlot,
+                $context->getTypeFromString('int32')->constInt(0, false),
+                $context->getTypeFromString('int64')->constInt($i, false)
+            );
+            self::writeArg($context, $slot, $args[$i + 1]);
+        }
+        $argvPtr = $context->builder->pointerCast(
+            $argvSlot,
+            $context->getTypeFromString('__value__*')
+        );
+        $argcVal = $context->getTypeFromString('int64')->constInt($numArgs, false);
+
+        return $context->builder->call(
+            $context->lookupFunction('__compiler_sprintf'),
+            $fmt,
+            $argcVal,
+            $argvPtr
+        );
+    }
+
+    private static function writeArg(Context $context, Value $slot, JITVariable $arg): void
+    {
+        $ptr = JitValueBox::pointer($context, $slot);
+        switch ($arg->type) {
+            case JITVariable::TYPE_NULL:
+                $context->builder->call($context->lookupFunction('__value__writeNull'), $ptr);
+                return;
+            case JITVariable::TYPE_NATIVE_LONG:
+                JitValueBox::writeLong($context, $slot, $context->helper->loadValue($arg));
+                return;
+            case JITVariable::TYPE_NATIVE_DOUBLE:
+                $context->builder->call(
+                    $context->lookupFunction('__value__writeDouble'),
+                    $ptr,
+                    $context->helper->loadValue($arg)
+                );
+                return;
+            case JITVariable::TYPE_NATIVE_BOOL:
+                JitValueBox::writeBool($context, $slot, $context->helper->loadValue($arg));
+                return;
+            case JITVariable::TYPE_STRING:
+                $str = $context->helper->loadValue($arg);
+                $owned = $context->builder->call(
+                    $context->lookupFunction('__string__separate'),
+                    $str
+                );
+                $context->builder->call(
+                    $context->lookupFunction('__value__writeString'),
+                    $ptr,
+                    $owned
+                );
+                return;
+            case JITVariable::TYPE_VALUE:
+                JitValueBox::copyFromPointer(
+                    $context,
+                    $slot,
+                    $context->helper->loadValue($arg)
+                );
+                return;
+            default:
+                throw new \LogicException(
+                    'sprintf() argument must be a scalar value in this compiler build'
+                );
+        }
+    }
+}

ext/standard/Module.php

@@ -82,6 +82,7 @@ public function getFunctions(): array
             new array_pop(),
             new array_shift(),
             new sort_(),
+            new sprintf_(),
             new array_values(),
             new array_keys(),
             new array_merge(),