Add UTF-8 string index search

Author: CryZe

crates/splitscript-syntax/src/migration.rs

@@ -181,6 +181,8 @@ pub const CSHARP_STRING_EQUALS_DIAGNOSTIC: MigrationDiagnosticId =
     MigrationDiagnosticId::new("csharp.string.equals-call");
 pub const CSHARP_STRING_SUBSTRING_DIAGNOSTIC: MigrationDiagnosticId =
     MigrationDiagnosticId::new("csharp.string.substring-call");
+pub const CSHARP_STRING_INDEX_OF_DIAGNOSTIC: MigrationDiagnosticId =
+    MigrationDiagnosticId::new("csharp.string.index-of-call");
 pub const CSHARP_NUMERIC_PARSE_DIAGNOSTIC: MigrationDiagnosticId =
     MigrationDiagnosticId::new("csharp.numeric.static-parse-call");
 pub const CSHARP_TIMESPAN_PARSE_DIAGNOSTIC: MigrationDiagnosticId =
@@ -364,6 +366,18 @@ pub const DIAGNOSTICS: &[MigrationDiagnostic] = &[
             "there is no automatic rewrite because the compiler cannot prove the source text is ASCII or recover C# overload semantics from the method name alone",
         ],
     },
+    MigrationDiagnostic {
+        id: CSHARP_STRING_INDEX_OF_DIAGNOSTIC,
+        concept: MigrationConceptId::new("string.index-of"),
+        message: "C# `String.IndexOf` needs an explicit index-model review",
+        primary_label: "SplitScript returns an optional UTF-8 byte offset",
+        notes: &[
+            "rewrite an ordinal ASCII search as `text.indexOf(substring)` and handle `None` instead of comparing the result with C#'s `-1` sentinel",
+            "SplitScript offsets count UTF-8 bytes; C# string offsets count UTF-16 code units, so copied arithmetic is only equivalent for proven ASCII text",
+            "comparison-mode and start-index overloads need separate review; the canonical operation is exact and case-sensitive from the beginning of the string",
+            "there is no automatic rewrite because changing both the index unit and absence representation can require surrounding control-flow changes",
+        ],
+    },
     MigrationDiagnostic {
         id: CSHARP_NUMERIC_PARSE_DIAGNOSTIC,
         concept: MigrationConceptId::new("string.numeric-parse"),
@@ -406,6 +420,7 @@ pub fn legacy_string_method_diagnostic(name: &str) -> Option<MigrationDiagnostic
     match name {
         "Equals" => Some(CSHARP_STRING_EQUALS_DIAGNOSTIC),
         "Substring" => Some(CSHARP_STRING_SUBSTRING_DIAGNOSTIC),
+        "IndexOf" => Some(CSHARP_STRING_INDEX_OF_DIAGNOSTIC),
         _ => None,
     }
 }
@@ -776,6 +791,16 @@ pub const CONCEPTS: &[MigrationConcept] = &[
         cookbook_anchor: Some("c-string-operations"),
         spellings: &[],
     },
+    MigrationConcept {
+        id: MigrationConceptId::new("string.index-of"),
+        name: "Substring position",
+        sources: CSHARP,
+        support: MigrationSupport::TypedPattern,
+        summary: "Use `indexOf` for an optional UTF-8 byte offset; review C# UTF-16 index arithmetic and replace the `-1` sentinel with Option handling.",
+        targets: &[MigrationTarget::StandardLibraryItem("String.indexOf")],
+        cookbook_anchor: Some("c-string-operations"),
+        spellings: &[],
+    },
     MigrationConcept {
         id: MigrationConceptId::new("string.numeric-parse"),
         name: "Numeric string parsing",

docs/ASL_PORTING.md

@@ -111,6 +111,18 @@ For text proven to be ASCII, translate the overload shapes explicitly. C#
 For non-ASCII text, first derive UTF-8 byte boundaries rather than copying the
 original UTF-16 positions.
 
+C# `value.IndexOf(substring)` returns a UTF-16 code-unit index or `-1`.
+SplitScript `value.indexOf(substring)` instead returns a UTF-8 byte offset as
+`u32?`; handle `None` directly. The numeric offsets are equivalent only for
+text proven to be ASCII:
+
+```splitscript
+let separator = current.map.indexOf("_") else return false
+```
+
+Comparison-mode and start-index overloads need an explicit rewrite rather than
+a method-name substitution.
+
 C# `left.Equals(right)` normally becomes `left == right`; SplitScript compares
 strings by exact UTF-8 text rather than GC reference identity. If the source
 intentionally ignores ASCII letter case, write

docs/LANGUAGE.md

@@ -1425,6 +1425,7 @@ is involved:
 | --- | --- |
 | `byteLength()` | UTF-8 byte length |
 | `contains(text)` | Case-sensitive substring test |
+| `indexOf(text)` | First matching UTF-8 byte offset as `u32?` |
 | `startsWith(text)` / `endsWith(text)` | Case-sensitive prefix/suffix tests |
 | `equalsIgnoreAsciiCase(text)` | Equality folding only ASCII letters |
 | `toAsciiLowerCase()` | Lowercase ASCII letters; preserve every other UTF-8 byte |

docs/MIGRATION_CAPABILITIES.md

@@ -13,6 +13,7 @@ This index maps common source-language concepts to canonical SplitScript APIs an
 | `string.equality` — String equality | C# | Supported directly | Use `==` or `!=` for exact string content equality; use `equalsIgnoreAsciiCase` only when ASCII-insensitive matching is intended. Canonical targets: `String`, `String.equalsIgnoreAsciiCase`. [Recipe](ASL_PORTING.md#c-string-operations). |
 | `operator.strict-equality` — Strict equality operators | JavaScript | Supported directly | Use typed `==` and `!=`; SplitScript has no coercing equality operators, so JavaScript's extra `=` is unnecessary. Canonical targets: `==`, `!=`. |
 | `string.substring` — Substring extraction | C# | Use a typed pattern | Use fallible `slice(start, exclusiveEnd)` only after translating C#'s length argument and verifying that UTF-16 source positions are valid UTF-8 byte offsets. Canonical targets: `String.slice`. [Recipe](ASL_PORTING.md#c-string-operations). |
+| `string.index-of` — Substring position | C# | Use a typed pattern | Use `indexOf` for an optional UTF-8 byte offset; review C# UTF-16 index arithmetic and replace the `-1` sentinel with Option handling. Canonical targets: `String.indexOf`. [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). |
 | `type.duration` — Timer durations | C# | Supported directly | Use `Duration` instead of C#'s `TimeSpan`. Canonical targets: `Duration`. |
 | `duration.parse` — Text duration parsing | C# | Use a typed pattern | Replace `TimeSpan.Parse` according to whether the input is fixed data or an already-typed timer value; do not preserve culture-sensitive parsing by default. Canonical targets: `Duration.fromWholeSeconds`, `Duration.fromWholeMilliseconds`, `Duration.fromParts`. |

docs/ROADMAP_ARCHIVE.md

@@ -1,5 +1,16 @@
 # SplitScript roadmap
 
+## 2026-08-09: allocation-free UTF-8 substring positions
+
+- Added `String.indexOf(substring) -> u32?` using the existing allocation-free
+  runtime search helper. It returns the first UTF-8 byte offset, zero for an
+  empty needle, and `None` when absent.
+- Added runtime coverage including a non-ASCII prefix, proving that the result
+  is a byte offset rather than a Unicode-scalar or UTF-16 index.
+- Added a focused C# `IndexOf` diagnostic with no automatic edit because C#
+  uses UTF-16 code units and a `-1` sentinel while SplitScript uses byte offsets
+  and `Option`.
+
 ## 2026-08-09: composable C# duration-constructor migration
 
 - Verified that the common C# forms `TimeSpan.FromSeconds(...)` and

src/codegen/expression.rs

@@ -2129,6 +2129,35 @@ fn compile_expr_unconverted(
                             .function(RuntimeHelperId::StringMatch),
                     ));
             }
+            IntrinsicId::StringIndexOf => {
+                let found = context.matches.intrinsic_temps[&expression][0];
+                let Type::Option(option) = ty else {
+                    unreachable!("String.indexOf returns the declared optional u32")
+                };
+                let option_type = context.gc.val_type(Type::Option(option));
+                compile_receiver(function, target, context);
+                compile_expr(function, args[0], context);
+                function
+                    .instruction(&Instruction::I32Const(0))
+                    .instruction(&Instruction::Call(
+                        context
+                            .runtime_helpers
+                            .function(RuntimeHelperId::StringFind),
+                    ))
+                    .instruction(&Instruction::LocalTee(found))
+                    .instruction(&Instruction::I32Const(0))
+                    .instruction(&Instruction::I32LtS)
+                    .instruction(&Instruction::If(BlockType::Result(option_type)))
+                    .instruction(&Instruction::RefNull(HeapType::Concrete(
+                        context.gc.index(Type::Option(option)),
+                    )))
+                    .instruction(&Instruction::Else)
+                    .instruction(&Instruction::LocalGet(found))
+                    .instruction(&Instruction::StructNew(
+                        context.gc.index(Type::Option(option)),
+                    ))
+                    .instruction(&Instruction::End);
+            }
             IntrinsicId::StringToAsciiLowerCase => {
                 compile_receiver(function, target, context);
                 function.instruction(&Instruction::Call(

src/intrinsic_registry.rs

@@ -302,6 +302,7 @@ const fn synchronous_scratch(id: IntrinsicId) -> Option<ScratchPolicy> {
         IntrinsicId::TimerState => scratch(ScratchType::Core(CoreTypeId::U32), 1),
         IntrinsicId::TimerCurrentSplitIndex => scratch(ScratchType::Core(CoreTypeId::I64), 1),
         IntrinsicId::TimerSegmentWasSplit => scratch(ScratchType::Core(CoreTypeId::I32), 1),
+        IntrinsicId::StringIndexOf => scratch(ScratchType::Core(CoreTypeId::I32), 1),
         IntrinsicId::ProcessFollow
         | IntrinsicId::ProcessReadRelative32
         | IntrinsicId::ProcessReadUtf8
@@ -388,6 +389,7 @@ const fn dependency_roots(id: IntrinsicId) -> &'static [DependencyRoot] {
         | IntrinsicId::StringStartsWith
         | IntrinsicId::StringEndsWith
         | IntrinsicId::StringEqualsIgnoreAsciiCase => &[Helper(Runtime::StringMatch)],
+        IntrinsicId::StringIndexOf => &[Helper(Runtime::StringFind)],
         IntrinsicId::StringToAsciiLowerCase => &[Helper(Runtime::StringToAsciiLowerCase)],
         IntrinsicId::StringReplaceAll => &[Helper(Runtime::StringReplaceAll)],
         IntrinsicId::StringSplit => &[Helper(Runtime::StringSplit)],
@@ -493,6 +495,10 @@ const U64_OPTION: ContractTypeRef = ContractTypeRef::Application {
     constructor: StdlibTypeConstructorId::Option,
     arguments: &[U64],
 };
+const U32_OPTION: ContractTypeRef = ContractTypeRef::Application {
+    constructor: StdlibTypeConstructorId::Option,
+    arguments: &[U32],
+};
 const BOOL_OPTION: ContractTypeRef = ContractTypeRef::Application {
     constructor: StdlibTypeConstructorId::Option,
     arguments: &[BOOL],
@@ -1097,6 +1103,19 @@ pub(crate) const fn contract(id: IntrinsicId) -> IntrinsicContract {
             Everywhere,
             RepresentationPrimitive
         ),
+        IntrinsicId::StringIndexOf => contract!(
+            StringIndexOf,
+            Method,
+            signature(
+                NO_TYPE_PARAMETERS,
+                Some(STRING),
+                params![value(STRING)],
+                U32_OPTION,
+            ),
+            PURE,
+            Everywhere,
+            RepresentationPrimitive
+        ),
         IntrinsicId::StringStartsWith => contract!(
             StringStartsWith,
             Method,

src/stdlib/catalog.rs

@@ -204,6 +204,7 @@ const fn validation_fixture(item: StdlibItemId) -> &'static str {
         | StdlibItemId::TimerIsRunning
         | StdlibItemId::StringByteLength
         | StdlibItemId::StringContains
+        | StdlibItemId::StringIndexOf
         | StdlibItemId::StringStartsWith
         | StdlibItemId::StringEndsWith
         | StdlibItemId::StringEqualsIgnoreAsciiCase

src/stdlib/intrinsics.rs

@@ -61,6 +61,7 @@ macro_rules! trusted_intrinsics {
             RuntimeArchitecture,
             StringLength,
             StringContains,
+            StringIndexOf,
             StringStartsWith,
             StringEndsWith,
             StringEqualsIgnoreAsciiCase,

stdlib/standard.split

@@ -1551,6 +1551,24 @@ intrinsic type String {
         substring: String,
     ) -> bool;
 
+    /// Finds the first exact substring and returns its UTF-8 byte offset.
+    ///
+    /// Returns `None` when the substring is absent. An empty substring is found
+    /// at byte offset zero. Searching is allocation-free and case-sensitive.
+    ///
+    /// # Example
+    ///
+    /// Find a separator in an ASCII scene identifier
+    ///
+    /// ```splitscript
+    /// let separator = sceneName.indexOf("_") else return
+    /// ```
+    @intrinsic(StringIndexOf)
+    fn indexOf(
+        /// The substring to search for.
+        substring: String,
+    ) -> u32?;
+
     /// Tests whether this string starts with an exact prefix.
     ///
     /// Matching is case-sensitive over the UTF-8 text. Every string starts