Add Unicode-scalar string padding

Author: CryZe

crates/splitscript-syntax/src/migration.rs

@@ -189,6 +189,8 @@ pub const CSHARP_STRING_REPLACE_DIAGNOSTIC: MigrationDiagnosticId =
     MigrationDiagnosticId::new("csharp.string.replace-call");
 pub const CSHARP_STRING_TRIM_DIAGNOSTIC: MigrationDiagnosticId =
     MigrationDiagnosticId::new("csharp.string.trim-call");
+pub const CSHARP_STRING_PADDING_DIAGNOSTIC: MigrationDiagnosticId =
+    MigrationDiagnosticId::new("csharp.string.padding-call");
 pub const CSHARP_STRING_IS_NULL_OR_EMPTY_DIAGNOSTIC: MigrationDiagnosticId =
     MigrationDiagnosticId::new("csharp.string.is-null-or-empty-call");
 pub const CSHARP_STRING_JOIN_DIAGNOSTIC: MigrationDiagnosticId =
@@ -424,6 +426,19 @@ pub const DIAGNOSTICS: &[MigrationDiagnostic] = &[
             "there is no automatic rewrite because the compiler cannot prove that the input's surrounding whitespace is ASCII",
         ],
     },
+    MigrationDiagnostic {
+        id: CSHARP_STRING_PADDING_DIAGNOSTIC,
+        concept: MigrationConceptId::new("string.padding"),
+        message: "C# string padding needs an explicit width-model review",
+        primary_label: "use `padStart(width, fill)` or `padEnd(width, fill)`",
+        notes: &[
+            "rewrite `text.PadLeft(width, fill)` as `text.padStart(width, fill)` and `text.PadRight(width, fill)` as `text.padEnd(width, fill)`",
+            "SplitScript always requires one `char` fill; pass `' '` explicitly for C# overloads that omit the padding character",
+            "SplitScript width counts Unicode scalar values, while C# width counts UTF-16 code units; copied widths are equivalent for proven ASCII text",
+            "padding returns the original immutable string when it is already wide enough and otherwise performs one exact-sized allocation",
+            "there is no automatic rewrite because direction, omitted fill, and the surrounding width assumptions need to remain visible",
+        ],
+    },
     MigrationDiagnostic {
         id: CSHARP_STRING_IS_NULL_OR_EMPTY_DIAGNOSTIC,
         concept: MigrationConceptId::new("string.null-or-empty"),
@@ -494,6 +509,7 @@ pub fn legacy_string_method_diagnostic(name: &str) -> Option<MigrationDiagnostic
         "LastIndexOf" => Some(CSHARP_STRING_LAST_INDEX_OF_DIAGNOSTIC),
         "Replace" => Some(CSHARP_STRING_REPLACE_DIAGNOSTIC),
         "Trim" => Some(CSHARP_STRING_TRIM_DIAGNOSTIC),
+        "PadLeft" | "PadRight" => Some(CSHARP_STRING_PADDING_DIAGNOSTIC),
         _ => None,
     }
 }
@@ -933,6 +949,19 @@ pub const CONCEPTS: &[MigrationConcept] = &[
         cookbook_anchor: Some("c-string-operations"),
         spellings: &[],
     },
+    MigrationConcept {
+        id: MigrationConceptId::new("string.padding"),
+        name: "String padding",
+        sources: CSHARP,
+        support: MigrationSupport::TypedPattern,
+        summary: "Use `padStart(width, fill)` or `padEnd(width, fill)` with an explicit character; review C# UTF-16 widths against SplitScript's Unicode-scalar widths.",
+        targets: &[
+            MigrationTarget::StandardLibraryItem("String.padStart"),
+            MigrationTarget::StandardLibraryItem("String.padEnd"),
+        ],
+        cookbook_anchor: Some("c-string-operations"),
+        spellings: &[],
+    },
     MigrationConcept {
         id: MigrationConceptId::new("string.null-or-empty"),
         name: "Nullable string emptiness",

docs/ASL_PORTING.md

@@ -128,6 +128,20 @@ immutable string when nothing changes. The compiler does not rewrite `Trim()`
 automatically because Unicode whitespace, character-array overloads,
 `TrimStart`, and `TrimEnd` have different semantics.
 
+C# `PadLeft` and `PadRight` map to directionally named immutable operations:
+
+```splitscript
+let chapter = chapterNumber as String
+let chapterKey = chapter.padStart(2, '0')
+let column = chapterKey.padEnd(8, ' ')
+```
+
+SplitScript always requires the fill `char`; pass `' '` explicitly for C#
+overloads that omit it. Width counts Unicode scalar values rather than .NET
+UTF-16 code units or terminal display columns, so copied widths are directly
+equivalent only for text proven to be ASCII. An already-wide string is reused;
+otherwise the result is allocated once at its exact UTF-8 byte length.
+
 C# combines nullability and emptiness in `String.IsNullOrEmpty(value)`.
 SplitScript keeps those concerns in the type. A required `String` cannot be
 null, so use its source-defined method directly:

docs/LANGUAGE.md

@@ -1433,6 +1433,7 @@ is involved:
 | `toAsciiLowerCase()` | Lowercase ASCII letters; preserve every other UTF-8 byte |
 | `toAsciiUpperCase()` | Uppercase ASCII letters; preserve every other UTF-8 byte |
 | `trimAsciiWhitespace()` | Remove ASCII boundary whitespace; preserve interior and non-ASCII bytes |
+| `padStart(width, fill)` / `padEnd(width, fill)` | Pad to a minimum Unicode-scalar length with one `char` |
 | `split(delimiter)` | Fallible exact split preserving leading, repeated, and trailing empty segments |
 | `parse<T>()` | Strict fallible ASCII decimal parsing into an inferred numeric type |
 | `byteAt(byteIndex)` | Fallible raw UTF-8 byte lookup; continuation bytes remain observable |

docs/MIGRATION_CAPABILITIES.md

@@ -18,6 +18,7 @@ This index maps common source-language concepts to canonical SplitScript APIs an
 | `string.last-index-of` — Last substring position | C# | Use a typed pattern | Use `lastIndexOf` for an optional final UTF-8 byte offset; review C# UTF-16 index arithmetic and replace the `-1` sentinel with Option handling. Canonical targets: `String.lastIndexOf`. [Recipe](ASL_PORTING.md#c-string-operations). |
 | `string.replacement` — Exact string replacement | C# | Use a typed pattern | Use fallible `replaceAll` for immutable exact replacement; explicitly handle failure and translate a null C# replacement to an empty string only when deletion was intended. Canonical targets: `String.replaceAll`. [Recipe](ASL_PORTING.md#c-string-operations). |
 | `string.ascii-trim` — ASCII whitespace trimming | C# | Use a typed pattern | Use `trimAsciiWhitespace` for text known to use ASCII boundary whitespace; review Unicode and character-set trimming explicitly. Canonical targets: `String.trimAsciiWhitespace`. [Recipe](ASL_PORTING.md#c-string-operations). |
+| `string.padding` — String padding | C# | Use a typed pattern | Use `padStart(width, fill)` or `padEnd(width, fill)` with an explicit character; review C# UTF-16 widths against SplitScript's Unicode-scalar widths. Canonical targets: `String.padStart`, `String.padEnd`. [Recipe](ASL_PORTING.md#c-string-operations). |
 | `string.null-or-empty` — Nullable string emptiness | C# | Use a typed pattern | Use `String.isEmpty` for required strings and match `String?` explicitly when absence should also count as empty. Canonical targets: `String.isEmpty`. [Recipe](ASL_PORTING.md#c-string-operations). |
 | `string.join` — String collection joining | C# | Use a typed pattern | Use `String.join(values, separator)` for a typed string array; convert C# object, variadic, enumerable, and range overloads explicitly. Canonical targets: `String.join`. [Recipe](ASL_PORTING.md#c-string-operations). |
 | `string.numeric-parse` — Numeric string parsing | C# | Supported directly | Replace static Parse/TryParse calls and output parameters with fallible `text.parse()` and ordinary Result handling. Canonical targets: `String.parse`. [Recipe](ASL_PORTING.md#c-string-operations). |

docs/ROADMAP_ARCHIVE.md

@@ -1,5 +1,19 @@
 # SplitScript roadmap
 
+## 2026-08-10: Unicode-scalar string padding
+
+- Added immutable `String.padStart(width, fill)` and
+  `String.padEnd(width, fill)` for corpus-backed zero-padding and diagnostic
+  table alignment without adopting C# method aliases or optional parameters.
+- Defined width as a count of Unicode scalar values. The runtime counts UTF-8
+  leading bytes, reuses an already-wide string, and otherwise encodes the fill
+  `char` directly into one exact-sized output allocation.
+- Added focused `PadLeft`/`PadRight` migration guidance covering direction,
+  explicit space filling, and the difference between .NET UTF-16 code units,
+  Unicode scalar values, and terminal display columns.
+- Extended catalog, documentation, diagnostics, and deterministic Wasm runtime
+  coverage across ASCII and multibyte receivers and fill characters.
+
 ## 2026-08-09: allocation-free reverse string search
 
 - Added `String.lastIndexOf(substring) -> u32?` for the recurring path,

src/codegen/expression.rs

@@ -2185,6 +2185,18 @@ fn compile_expr_unconverted(
                         .function(RuntimeHelperId::StringTrimAsciiWhitespace),
                 ));
             }
+            IntrinsicId::StringPadStart | IntrinsicId::StringPadEnd => {
+                compile_receiver(function, target, context);
+                compile_expr(function, args[0], context);
+                compile_expr(function, args[1], context);
+                function
+                    .instruction(&Instruction::I32Const(
+                        (builtin == IntrinsicId::StringPadEnd) as i32,
+                    ))
+                    .instruction(&Instruction::Call(
+                        context.runtime_helpers.function(RuntimeHelperId::StringPad),
+                    ));
+            }
             IntrinsicId::StringReplaceAll => {
                 compile_receiver(function, target, context);
                 compile_expr(function, args[0], context);

src/codegen/runtime_helper_registry.rs

@@ -105,6 +105,7 @@ pub(super) const DESCRIPTORS: &[RuntimeHelperDescriptor] = &[
     helper!(StringInspect, (StringValue, I32, I32) -> (I32, I32), deps [], imports [], build_string_inspect),
     helper!(StringSlice, (StringValue, I32, I32) -> (StringValue), deps [], imports [], build_string_slice),
     helper!(StringTrimAsciiWhitespace, (StringValue) -> (StringValue), deps [StringSlice], imports [], build_string_trim_ascii_whitespace),
+    helper!(StringPad, (StringValue, I32, I32, I32) -> (StringValue), deps [], imports [], build_string_pad),
     helper!(ScanProcessRange, (I64, I64, I64, I32, I32, I32) -> (I64), deps [], imports [ProcessRead], build_scan_process_range),
     helper!(ReadRelative32, (I64, I64) -> (I64), deps [], imports [ProcessRead], build_read_relative32),
     helper!(StringFromMemory, (I32, I32) -> (StringValue), deps [], imports [], build_string_from_memory),

src/codegen/runtime_helpers.rs

@@ -157,6 +157,10 @@ pub(super) fn build_string_trim_ascii_whitespace(inputs: &RuntimeHelperInputs<'_
     )
 }
 
+pub(super) fn build_string_pad(inputs: &RuntimeHelperInputs<'_>) -> Function {
+    strings::compile_string_pad(inputs.gc)
+}
+
 pub(super) fn build_scan_process_range(inputs: &RuntimeHelperInputs<'_>) -> Function {
     process::compile_scan_process_range(inputs.abi, inputs.memory.scratch().scan)
 }