Add typed string emptiness

Author: CryZe

crates/splitscript-syntax/src/migration.rs

@@ -187,6 +187,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_IS_NULL_OR_EMPTY_DIAGNOSTIC: MigrationDiagnosticId =
+    MigrationDiagnosticId::new("csharp.string.is-null-or-empty-call");
 pub const CSHARP_NUMERIC_PARSE_DIAGNOSTIC: MigrationDiagnosticId =
     MigrationDiagnosticId::new("csharp.numeric.static-parse-call");
 pub const CSHARP_TIMESPAN_PARSE_DIAGNOSTIC: MigrationDiagnosticId =
@@ -406,6 +408,18 @@ 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_IS_NULL_OR_EMPTY_DIAGNOSTIC,
+        concept: MigrationConceptId::new("string.null-or-empty"),
+        message: "C# `String.IsNullOrEmpty` crosses SplitScript's Option boundary",
+        primary_label: "choose emptiness or optional absence from the value's type",
+        notes: &[
+            "for a required `String`, rewrite `String.IsNullOrEmpty(value)` as `value.isEmpty()` because the value cannot be null",
+            "for `String?`, use `match value { None => true, Some(text) => text.isEmpty() }` so absence remains explicit",
+            "process and state read failures are not automatically null strings; preserve their declared Result or Option policy before checking emptiness",
+            "there is no automatic rewrite because the static call does not reveal whether the migrated value should be required, optional, or fallible",
+        ],
+    },
     MigrationDiagnostic {
         id: CSHARP_NUMERIC_PARSE_DIAGNOSTIC,
         concept: MigrationConceptId::new("string.numeric-parse"),
@@ -459,6 +473,9 @@ pub fn legacy_static_call_diagnostic(path: &[String]) -> Option<MigrationDiagnos
     let [owner, method] = path else {
         return None;
     };
+    if owner == "String" && method == "IsNullOrEmpty" {
+        return Some(CSHARP_STRING_IS_NULL_OR_EMPTY_DIAGNOSTIC);
+    }
     if owner == "Duration" && method == "Parse" {
         return Some(CSHARP_TIMESPAN_PARSE_DIAGNOSTIC);
     }
@@ -874,6 +891,16 @@ pub const CONCEPTS: &[MigrationConcept] = &[
         cookbook_anchor: Some("c-string-operations"),
         spellings: &[],
     },
+    MigrationConcept {
+        id: MigrationConceptId::new("string.null-or-empty"),
+        name: "Nullable string emptiness",
+        sources: CSHARP,
+        support: MigrationSupport::TypedPattern,
+        summary: "Use `String.isEmpty` for required strings and match `String?` explicitly when absence should also count as empty.",
+        targets: &[MigrationTarget::StandardLibraryItem("String.isEmpty")],
+        cookbook_anchor: Some("c-string-operations"),
+        spellings: &[],
+    },
     MigrationConcept {
         id: MigrationConceptId::new("string.numeric-parse"),
         name: "Numeric string parsing",

docs/ASL_PORTING.md

@@ -128,6 +128,28 @@ 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# 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:
+
+```splitscript
+let missingCheckpoint = current.checkpoint.isEmpty()
+```
+
+When the migrated value is deliberately optional, handle both variants:
+
+```splitscript
+let missingCheckpoint = match current.checkpoint {
+    None => true,
+    Some(text) => text.isEmpty(),
+}
+```
+
+A failed process read is not automatically an empty or null string. Decide
+first whether that boundary should remain a `Result`, become a `String?`, or
+retain the last accepted state value. The compiler therefore gives
+`String.IsNullOrEmpty` focused guidance without guessing an automatic rewrite.
+
 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

docs/LANGUAGE.md

@@ -1424,6 +1424,7 @@ is involved:
 | Operation | Behavior |
 | --- | --- |
 | `byteLength()` | UTF-8 byte length |
+| `isEmpty()` | Whether the required string contains zero UTF-8 bytes |
 | `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 |

docs/MIGRATION_CAPABILITIES.md

@@ -17,6 +17,7 @@ This index maps common source-language concepts to canonical SplitScript APIs an
 | `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.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.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.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: typed string emptiness
+
+- Added source-defined `String.isEmpty()` as ordinary composition over
+  `byteLength`, with generated documentation, completion, hover, must-use, and
+  runtime coverage but no backend intrinsic.
+- Added focused guidance for the recurring C# `String.IsNullOrEmpty` pattern.
+  Required strings use `.isEmpty()`, while `String?` must explicitly match
+  `None` and `Some`; failed process reads retain their separate Result policy.
+- Deliberately avoided recreating nullable strings or guessing an automatic
+  rewrite from a static C# call whose migrated value type is not yet known.
+
 ## 2026-08-09: explicit ASCII whitespace trimming
 
 - Added `String.trimAsciiWhitespace()` for recurring corpus parsing of game

src/completion.rs

@@ -1719,6 +1719,7 @@ split {
         let literal = labels(&mut database, "2 => \"½\".");
         for member in [
             "byteLength",
+            "isEmpty",
             "contains",
             "startsWith",
             "endsWith",
@@ -1739,6 +1740,7 @@ split {
         let local = labels(&mut database, "return fraction.");
         for member in [
             "byteLength",
+            "isEmpty",
             "contains",
             "startsWith",
             "endsWith",

stdlib/standard.split

@@ -1533,6 +1533,23 @@ intrinsic type String {
     @intrinsic(StringLength)
     fn byteLength() -> u32;
 
+    /// Reports whether this string contains no UTF-8 bytes.
+    ///
+    /// `String` itself is never absent. Use ordinary `match` on `String?` when
+    /// absence and emptiness should both satisfy a condition.
+    ///
+    /// # Example
+    ///
+    /// Ignore an empty checkpoint name
+    ///
+    /// ```splitscript
+    /// let hasCheckpoint = !checkpointName.isEmpty()
+    /// ```
+    @mustUse("The string emptiness result must be used.")
+    fn isEmpty() -> bool {
+        return self.byteLength() == 0
+    }
+
     /// Tests whether this string contains an exact substring.
     ///
     /// Matching is case-sensitive over the UTF-8 text. An empty substring is

tests/compiler/catalogs_types.rs

@@ -964,6 +964,10 @@ fn standard_library_catalog_is_valid_documented_and_compilable() {
         library.render_signature(StdlibItemId::StringToAsciiLowerCase),
         "String.toAsciiLowerCase() -> String"
     );
+    assert_eq!(
+        library.render_signature(StdlibItemId::StringIsEmpty),
+        "String.isEmpty() -> bool"
+    );
     assert_eq!(
         library.render_signature(StdlibItemId::StringToAsciiUpperCase),
         "String.toAsciiUpperCase() -> String"

tests/compiler/diagnostics_migration.rs

@@ -243,6 +243,46 @@ fn csharp_string_trim_explains_ascii_whitespace_boundaries() {
     }));
 }
 
+#[test]
+fn csharp_is_null_or_empty_explains_required_and_optional_strings() {
+    let source = r#"
+        state "game.exe" {}
+
+        fn missingCheckpoint(value: String?) -> bool {
+            return String.IsNullOrEmpty(value)
+        }
+    "#;
+    let diagnostics = splitscript::compile(source)
+        .expect_err("C# IsNullOrEmpty needs Option-aware migration guidance");
+
+    assert_eq!(diagnostics.len(), 1, "unexpected cascade: {diagnostics:#?}");
+    let diagnostic = &diagnostics[0];
+    assert_eq!(
+        diagnostic.message,
+        "C# `String.IsNullOrEmpty` crosses SplitScript's Option boundary"
+    );
+    assert_eq!(
+        &source[diagnostic.span.start..diagnostic.span.end],
+        "IsNullOrEmpty"
+    );
+    assert!(diagnostic.fixes.is_empty());
+    assert!(
+        diagnostic
+            .notes
+            .iter()
+            .any(|note| { note.contains("required `String`") && note.contains("value.isEmpty()") })
+    );
+    assert!(diagnostic.notes.iter().any(|note| {
+        note.contains("String?") && note.contains("None") && note.contains("Some(text)")
+    }));
+    assert!(
+        diagnostic
+            .notes
+            .iter()
+            .any(|note| note.contains("Result or Option policy"))
+    );
+}
+
 #[test]
 fn csharp_static_numeric_parse_explains_result_based_string_parsing() {
     for call in ["Int32.Parse(text)", "Double.Parse(text)"] {

tests/string_predicates.split

@@ -114,6 +114,9 @@ whileAttached {
     {
         matches += 131072
     }
+    if "".isEmpty() && !"Map_A".isEmpty() {
+        matches += 262144
+    }
     let levelParts = "01_02_0.dds".split(".") else []
     let identifiers = levelParts[0].split("_") else []
     let emptyParts = "_a__".split("_") else []