Home /Modules/text/SLString.sleela

SLString.sleela

lib/text/SLString.sleela · 821 line(s) · sleela

< lib/text/SLString.sleela >
< SLeeLa Standard Library Definition. >
< Definition: The comprehensive SLeeLa text/String contract (SLString) for the >
< text library family. >
<  >
< SLString is the language-facing String surface. SLeeLa's built-in `String` >
< scalar exposes only concatenation (+) and equality (==/!=) to source code; >
< there is no char type and no char-level indexing. So this class is organised >
< in two honest layers: >
<  >
< * IN-LANGUAGE operations -- length-independent text work that can be >
< expressed with +, ==, stored fields, and String[]/int[] arrays with >
< loops. These are implemented here and return real results. >
< * BRIDGED operations -- char-level work (charAt, substring, indexOf, >
< case mapping, trimming, splitting, ordering) that requires the raw code >
< units. SLeeLa never sees those, so these methods cross the explicit >
< VM/OS bridge: each returns a stable, inspectable bridge-call descriptor >
< and the native runtime fulfils it -- the same "never fake it" contract >
< the codec/Java-envelope surfaces use. A method is never a silent lie: >
< a bridged op advertises that it is bridged. >
<  >
< Bridge descriptor schema (shared across the text family): >
< "text.bridge:<op>[:<receiver>][:<arg>...]" >
< Field 1 is always the literal "text.bridge"; field 2 is the op name; the >
< remaining fields are the receiver value then the operation arguments. The >
< helpers bridge()/bridgeArg()/bridgeArg2() build it; bridgeOp(d) reads the op >
< back out so a caller or test can reason about a descriptor in-language. >
<  >
< Comments use the angle-bracket style (< line, << block >>). Methods resolve >
< on class-typed fields per syntax 1.11+. #sleela 2.1 enables the full surface. >
#sleela 2.5
material;

class SLString {

  < ---- identity ------------------------------------------------------ >
  int id() { return 0; }
  String name() { return "SLString"; }

  < ---- backing value ------------------------------------------------- >
  < The text this SLString wraps. value == "" is the canonical empty state. >
  String value = "";

  < ---- construction / lifecycle -------------------------------------- >
  < Library convention is an explicit initialiser rather than a constructor. >
  void set(String v)   { value = v; }
  String get()         { return value; }
  void clear()         { value = ""; }
  < fluent seed >
  SLString with(String v) { value = v; return this; }

  < SLCloneable intent: a detached copy of this SLString. >
  SLString copy() { SLString c = new SLString(); c.set(value); return c; }

  < SLDisposable intent: release to the canonical empty state. >
  void dispose() { value = ""; }

  < ==================================================================== >
  < IN-LANGUAGE operations (real, no bridge) >
  < ==================================================================== >

  < Concatenation: the one native String operator besides compare. >
  String concat(String other)            { return value + other; }

  < Equality / emptiness via the native == on strings. >
  boolean equals(String other)           { return value == other; }
  boolean isEmpty()                       { return value == ""; }
  boolean notEmpty()                      { return value != ""; }

  < Null/absence helpers (a SLeeLa String field may be unset == null). >
  boolean isNull()                        { return value == null; }
  boolean isBlankLike()                   { return value == null || value == ""; }

  < Append/prepend mutate the wrapped value and return it fluently. >
  SLString append(String tail)  { value = value + tail; return this; }
  SLString prepend(String head) { value = head + value; return this; }
  SLString appendLine(String tail) { value = value + tail + "\n"; return this; }

  < repeat(n): value repeated n times (n <= 0 yields ""). Built with a loop >
  < over the native + operator -- fully in-language. >
  String repeat(int n) {
    String out = "";
    int i = 0;
    while (i < n) { out = out + value; i = i + 1; }
    return out;
  }

  < join(parts, sep): join a String[] with a separator. In-language: loop + +. >
  String join(String[] parts, String sep) {
    String out = "";
    int i = 0;
    int n = arrayLength(parts);
    while (i < n) {
      if (i > 0) { out = out + sep; }
      out = out + parts[i];
      i = i + 1;
    }
    return out;
  }

  < joinLines(parts): join a String[] with newlines. >
  String joinLines(String[] parts) { return join(parts, "\n"); }

  < surround / quote: wrap the value with affixes (in-language). >
  String surround(String left, String right) { return left + value + right; }
  String quote()  { return "\"" + value + "\""; }
  String parens() { return "(" + value + ")"; }

  < -------------------------------------------------------------------- >
  < Static-style helpers: the same in-language operations as free functions >
  < over explicit arguments, for callers that do not wish to seed value first. >
  < -------------------------------------------------------------------- >
  String concatBoth(String a, String b)   { return a + b; }
  boolean equalsText(String a, String b)  { return a == b; }
  boolean isEmptyText(String s)           { return s == ""; }
  String repeatText(String s, int n) {
    String out = "";
    int i = 0;
    while (i < n) { out = out + s; i = i + 1; }
    return out;
  }

  < -------------------------------------------------------------------- >
  < Added in-language helpers (all real: built from +, ==, loops, arrays). >
  < These extend the dependable, non-bridged surface. >
  < -------------------------------------------------------------------- >

  < repeatWithSep(n, sep): the value repeated n times, separated by sep. >
  < e.g. value "ab", n 3, sep "," -> "ab,ab,ab". n <= 0 yields "". >
  String repeatWithSep(int n, String sep) {
    String out = "";
    int i = 0;
    while (i < n) {
      if (i > 0) { out = out + sep; }
      out = out + value;
      i = i + 1;
    }
    return out;
  }

  < times(n): fluent in-place repeat -- sets value to itself n times. >
  SLString times(int n) { value = repeat(n); return this; }

  < defaultIfEmpty / defaultIfBlank: fall back when unset/empty. Real: uses >
  < only == against "" and null. >
  String defaultIfEmpty(String fallback) {
    if (value == null || value == "") { return fallback; }
    return value;
  }
  SLString orElse(String fallback) { value = defaultIfEmpty(fallback); return this; }

  < equalsAnyOf(options): true if value equals any element of the array. Real: >
  < native == in a loop. >
  boolean equalsAnyOf(String[] options) {
    int i = 0;
    int n = arrayLength(options);
    while (i < n) {
      if (value == options[i]) { return true; }
      i = i + 1;
    }
    return false;
  }

  < equalsNoneOf(options): the complement of equalsAnyOf. >
  boolean equalsNoneOf(String[] options) { return !equalsAnyOf(options); }

  < ensurePrefix / ensureSuffix: add an affix only if not already fully equal >
  < to being the whole value (in-language: we can test whole-string equality, >
  < not substring, so this guards against double-wrapping an exact match). >
  String ensureExact(String required) {
    if (value == required) { return value; }
    return required + value;
  }

  < wrapEach(parts, left, right): wrap every element of a String[] and return a >
  < new String[] of the same length. Real: array alloc + loop + +. >
  String[] wrapEach(String[] parts, String left, String right) {
    int n = arrayLength(parts);
    String[] out = new String[n];
    int i = 0;
    while (i < n) { out[i] = left + parts[i] + right; i = i + 1; }
    return out;
  }

  < joinNonEmpty(parts, sep): join a String[] with sep, skipping null/"" parts. >
  < Real: == tests + loop. >
  String joinNonEmpty(String[] parts, String sep) {
    String out = "";
    boolean first = true;
    int i = 0;
    int n = arrayLength(parts);
    while (i < n) {
      String p = parts[i];
      if (p != null && p != "") {
        if (!first) { out = out + sep; }
        out = out + p;
        first = false;
      }
      i = i + 1;
    }
    return out;
  }

  < countParts(parts): number of non-null, non-empty elements in a String[]. >
  int countParts(String[] parts) {
    int c = 0;
    int i = 0;
    int n = arrayLength(parts);
    while (i < n) {
      if (parts[i] != null && parts[i] != "") { c = c + 1; }
      i = i + 1;
    }
    return c;
  }

  < lines(parts) / csv(parts): common joins as named conveniences. >
  String lines(String[] parts)  { return join(parts, "\n"); }
  String csv(String[] parts)    { return join(parts, ","); }
  String spaced(String[] parts) { return join(parts, " "); }

  < concatAll(parts): concatenate every element of a String[] with no separator >
  < (real: loop + +). The separator-less sibling of join. >
  String concatAll(String[] parts) {
    String out = "";
    int i = 0;
    int n = arrayLength(parts);
    while (i < n) { out = out + parts[i]; i = i + 1; }
    return out;
  }

  < wrapIfNotEmpty(left, right): surround the value only when it is non-empty; an >
  < empty/unset value stays "" (real: == guard). Avoids emitting bare affixes. >
  String wrapIfNotEmpty(String left, String right) {
    if (value == null || value == "") { return ""; }
    return left + value + right;
  }

  < prefixIf(cond, head) / suffixIf(cond, tail): conditionally affix the value >
  < and return the result (real). Handy when assembling text from flags. >
  String prefixIf(boolean cond, String head) {
    if (cond) { return head + value; }
    return value;
  }
  String suffixIf(boolean cond, String tail) {
    if (cond) { return value + tail; }
    return value;
  }

  < ==================================================================== >
  < CHAR-CELL VIEW -- REAL char-level ops over an explicit String[] of cells >
  < ==================================================================== >
  < The built-in String is opaque, so charAt/substring/indexOf must normally >
  < be bridged. But when a caller represents text as a String[] whose cells are >
  < the individual glyphs (a "char-cell view"), these operations become fully >
  < in-language and REAL -- no bridge, no faking -- because the decomposition >
  < was supplied explicitly. Produce cells at the boundary (e.g. from the >
  < bridged chars()/split() the runtime fulfils, or from a known literal set), >
  < then do dependable char-level work here. fromCells() rejoins to a String. >
  < Indices are int (0-based); out-of-range access returns "" rather than >
  < failing, matching the library's fail-soft convention. >

  < fromCells(cells): rejoin a char-cell array into a String (real). >
  String fromCells(String[] cells) {
    String out = "";
    int i = 0;
    int n = arrayLength(cells);
    while (i < n) { out = out + cells[i]; i = i + 1; }
    return out;
  }

  < lengthCells(cells): real character length of a char-cell view. >
  int lengthCells(String[] cells) { return arrayLength(cells); }

  < charAtCells(cells, i): the glyph at index i, or "" if out of range (real). >
  String charAtCells(String[] cells, int i) {
    if (i < 0 || i >= arrayLength(cells)) { return ""; }
    return cells[i];
  }

  < substringCells(cells, from, to): the cells in [from, to) rejoined (real). >
  < from is clamped to 0, to is clamped to the length; from >= to yields "". >
  String substringCells(String[] cells, int from, int to) {
    String out = "";
    int n = arrayLength(cells);
    int i = from;
    if (i < 0) { i = 0; }
    int end = to;
    if (end > n) { end = n; }
    while (i < end) { out = out + cells[i]; i = i + 1; }
    return out;
  }

  < indexOfCell(cells, needle): first index whose cell == needle, else -1 (real). >
  int indexOfCell(String[] cells, String needle) {
    int i = 0;
    int n = arrayLength(cells);
    while (i < n) {
      if (cells[i] == needle) { return i; }
      i = i + 1;
    }
    return -1;
  }

  < lastIndexOfCell(cells, needle): last matching index, else -1 (real). >
  int lastIndexOfCell(String[] cells, String needle) {
    int i = arrayLength(cells) - 1;
    while (i >= 0) {
      if (cells[i] == needle) { return i; }
      i = i - 1;
    }
    return -1;
  }

  < containsCell(cells, needle): true if any cell equals needle (real). >
  boolean containsCell(String[] cells, String needle) {
    return indexOfCell(cells, needle) >= 0;
  }

  < countCell(cells, needle): how many cells equal needle (real). >
  int countCell(String[] cells, String needle) {
    int c = 0;
    int i = 0;
    int n = arrayLength(cells);
    while (i < n) {
      if (cells[i] == needle) { c = c + 1; }
      i = i + 1;
    }
    return c;
  }

  < startsWithCells(cells, prefix): does the cell view begin with the prefix >
  < cell array? Real: element-wise == over the leading cells. >
  boolean startsWithCells(String[] cells, String[] prefix) {
    int pn = arrayLength(prefix);
    if (pn > arrayLength(cells)) { return false; }
    int i = 0;
    while (i < pn) {
      if (cells[i] != prefix[i]) { return false; }
      i = i + 1;
    }
    return true;
  }

  < endsWithCells(cells, suffix): does the cell view end with the suffix cells? >
  boolean endsWithCells(String[] cells, String[] suffix) {
    int sn = arrayLength(suffix);
    int cn = arrayLength(cells);
    if (sn > cn) { return false; }
    int i = 0;
    while (i < sn) {
      if (cells[cn - sn + i] != suffix[i]) { return false; }
      i = i + 1;
    }
    return true;
  }

  < reverseCells(cells): the glyphs in reverse order, rejoined (real). >
  String reverseCells(String[] cells) {
    String out = "";
    int i = arrayLength(cells) - 1;
    while (i >= 0) { out = out + cells[i]; i = i - 1; }
    return out;
  }

  < replaceCells(cells, from, to): every cell equal to `from` becomes `to`; >
  < returns a new String[] of the same length (real). >
  String[] replaceCells(String[] cells, String from, String to) {
    int n = arrayLength(cells);
    String[] out = new String[n];
    int i = 0;
    while (i < n) {
      if (cells[i] == from) { out[i] = to; } else { out[i] = cells[i]; }
      i = i + 1;
    }
    return out;
  }

  < equalsCells(a, b): element-wise equality of two char-cell views (real). >
  boolean equalsCells(String[] a, String[] b) {
    int n = arrayLength(a);
    if (n != arrayLength(b)) { return false; }
    int i = 0;
    while (i < n) {
      if (a[i] != b[i]) { return false; }
      i = i + 1;
    }
    return true;
  }

  < padCellsLeft / padCellsRight(cells, width, padCell): pad the view to a real >
  < target character width with padCell, returning a String (real). If the view >
  < is already >= width, it is returned rejoined unchanged. >
  String padCellsLeft(String[] cells, int width, String padCell) {
    String pad = "";
    int n = arrayLength(cells);
    int i = n;
    while (i < width) { pad = pad + padCell; i = i + 1; }
    return pad + fromCells(cells);
  }
  String padCellsRight(String[] cells, int width, String padCell) {
    String out = fromCells(cells);
    int n = arrayLength(cells);
    int i = n;
    while (i < width) { out = out + padCell; i = i + 1; }
    return out;
  }

  < padCenterCells(cells, width, padCell): centre the view in a real character >
  < width, padding both sides with padCell. Any odd remainder goes on the right >
  < (matching common centre-text conventions). If the view is already >= width, >
  < it is returned rejoined unchanged. Fully in-language (loops + +). >
  String padCenterCells(String[] cells, int width, String padCell) {
    int n = arrayLength(cells);
    if (n >= width) { return fromCells(cells); }
    int total = width - n;
    int left = total / 2;
    int right = total - left;
    String lpad = "";
    int i = 0;
    while (i < left) { lpad = lpad + padCell; i = i + 1; }
    String rpad = "";
    i = 0;
    while (i < right) { rpad = rpad + padCell; i = i + 1; }
    return lpad + fromCells(cells) + rpad;
  }

  < truncateCells(cells, width, ellipsisCell): if the view is longer than width >
  < real characters, keep the first (width - 1) cells and append ellipsisCell so >
  < the result is exactly `width` cells wide; otherwise return it unchanged. A >
  < width <= 0 yields "". Real: slice + append over the supplied cells. >
  String truncateCells(String[] cells, int width, String ellipsisCell) {
    int n = arrayLength(cells);
    if (width <= 0) { return ""; }
    if (n <= width) { return fromCells(cells); }
    String out = "";
    int keep = width - 1;
    int i = 0;
    while (i < keep) { out = out + cells[i]; i = i + 1; }
    return out + ellipsisCell;
  }

  < sliceCells(cells, from, to): the cells in [from, to) as a NEW String[] (real). >
  < from is clamped to 0, to to the length; from >= to yields an empty array. >
  < This is the array-returning sibling of substringCells (which rejoins). >
  String[] sliceCells(String[] cells, int from, int to) {
    int n = arrayLength(cells);
    int lo = from;
    if (lo < 0) { lo = 0; }
    int hi = to;
    if (hi > n) { hi = n; }
    if (lo >= hi) { return new String[0]; }
    int len = hi - lo;
    String[] out = new String[len];
    int i = 0;
    while (i < len) { out[i] = cells[lo + i]; i = i + 1; }
    return out;
  }

  < insertCells(cells, at, ins): a NEW cell array with the cells of `ins` spliced >
  < in before index `at` (at clamped to [0, len]). Real: array alloc + copy loops. >
  String[] insertCells(String[] cells, int at, String[] ins) {
    int n = arrayLength(cells);
    int m = arrayLength(ins);
    int pos = at;
    if (pos < 0) { pos = 0; }
    if (pos > n) { pos = n; }
    String[] out = new String[n + m];
    int o = 0;
    int i = 0;
    while (i < pos) { out[o] = cells[i]; o = o + 1; i = i + 1; }
    int j = 0;
    while (j < m) { out[o] = ins[j]; o = o + 1; j = j + 1; }
    while (i < n) { out[o] = cells[i]; o = o + 1; i = i + 1; }
    return out;
  }

  < deleteCellsRange(cells, from, to): a NEW cell array with [from, to) removed >
  < (from clamped to 0, to to the length; from >= to removes nothing). Real. >
  String[] deleteCellsRange(String[] cells, int from, int to) {
    int n = arrayLength(cells);
    int lo = from;
    if (lo < 0) { lo = 0; }
    int hi = to;
    if (hi > n) { hi = n; }
    if (lo >= hi) {
      String[] same = new String[n];
      int k = 0;
      while (k < n) { same[k] = cells[k]; k = k + 1; }
      return same;
    }
    int removed = hi - lo;
    String[] out = new String[n - removed];
    int o = 0;
    int i = 0;
    while (i < lo) { out[o] = cells[i]; o = o + 1; i = i + 1; }
    i = hi;
    while (i < n) { out[o] = cells[i]; o = o + 1; i = i + 1; }
    return out;
  }

  < -------------------------------------------------------------------- >
  < Multi-cell SUBSEQUENCE ops. The single-cell helpers above (indexOfCell, >
  < replaceCells, ...) match one glyph at a time; these match a whole cell >
  < sequence, giving real substring search/replace entirely in-language. >
  < -------------------------------------------------------------------- >

  < matchesAt(cells, at, needle): does the needle cell-sequence occur in `cells` >
  < starting exactly at index `at`? Real: element-wise == over the window. >
  boolean matchesAt(String[] cells, int at, String[] needle) {
    int nn = arrayLength(needle);
    int cn = arrayLength(cells);
    if (at < 0 || at + nn > cn) { return false; }
    int i = 0;
    while (i < nn) {
      if (cells[at + i] != needle[i]) { return false; }
      i = i + 1;
    }
    return true;
  }

  < indexOfSeqCells(cells, needle): first start index where the needle sequence >
  < occurs, or -1. An empty needle matches at 0 (as substring search does). Real. >
  int indexOfSeqCells(String[] cells, String[] needle) {
    int nn = arrayLength(needle);
    int cn = arrayLength(cells);
    if (nn == 0) { return 0; }
    int start = 0;
    while (start + nn <= cn) {
      if (matchesAt(cells, start, needle)) { return start; }
      start = start + 1;
    }
    return -1;
  }

  < lastIndexOfSeqCells(cells, needle): last start index of the needle sequence, >
  < or -1. Empty needle matches at the end. Real. >
  int lastIndexOfSeqCells(String[] cells, String[] needle) {
    int nn = arrayLength(needle);
    int cn = arrayLength(cells);
    if (nn == 0) { return cn; }
    int start = cn - nn;
    while (start >= 0) {
      if (matchesAt(cells, start, needle)) { return start; }
      start = start - 1;
    }
    return -1;
  }

  < containsSeqCells / startsWithSeqCells / endsWithSeqCells: multi-cell forms of >
  < the single-cell predicates, built on matchesAt / indexOfSeqCells (real). >
  boolean containsSeqCells(String[] cells, String[] needle) {
    return indexOfSeqCells(cells, needle) >= 0;
  }
  boolean startsWithSeqCells(String[] cells, String[] needle) {
    return matchesAt(cells, 0, needle);
  }
  boolean endsWithSeqCells(String[] cells, String[] needle) {
    int nn = arrayLength(needle);
    int cn = arrayLength(cells);
    if (nn > cn) { return false; }
    return matchesAt(cells, cn - nn, needle);
  }

  < countSeqCells(cells, needle): number of NON-OVERLAPPING occurrences of the >
  < needle sequence. An empty needle yields 0 (no progress possible). Real. >
  int countSeqCells(String[] cells, String[] needle) {
    int nn = arrayLength(needle);
    int cn = arrayLength(cells);
    if (nn == 0) { return 0; }
    int c = 0;
    int start = 0;
    while (start + nn <= cn) {
      if (matchesAt(cells, start, needle)) { c = c + 1; start = start + nn; }
      else { start = start + 1; }
    }
    return c;
  }

  < replaceSeqCells(cells, from, to): replace every NON-OVERLAPPING occurrence of >
  < the `from` cell-sequence with the `to` cell-sequence, returning the rejoined >
  < String. An empty `from` returns the view unchanged. Real: scan + rebuild. >
  String replaceSeqCells(String[] cells, String[] from, String[] to) {
    int fn = arrayLength(from);
    int cn = arrayLength(cells);
    if (fn == 0) { return fromCells(cells); }
    String out = "";
    int i = 0;
    while (i < cn) {
      if (i + fn <= cn && matchesAt(cells, i, from)) {
        int j = 0;
        int tn = arrayLength(to);
        while (j < tn) { out = out + to[j]; j = j + 1; }
        i = i + fn;
      } else {
        out = out + cells[i];
        i = i + 1;
      }
    }
    return out;
  }

  < splitCellsOn(cells, sepCell): split the view on each cell equal to sepCell, >
  < returning the segments as a NEW String[] (each segment is the rejoined run >
  < of cells between separators; adjacent separators yield "" segments). Real. >
  String[] splitCellsOn(String[] cells, String sepCell) {
    int n = arrayLength(cells);
    < first pass: count segments (separators + 1) >
    int segs = 1;
    int i = 0;
    while (i < n) { if (cells[i] == sepCell) { segs = segs + 1; } i = i + 1; }
    String[] out = new String[segs];
    int s = 0;
    String cur = "";
    i = 0;
    while (i < n) {
      if (cells[i] == sepCell) { out[s] = cur; s = s + 1; cur = ""; }
      else { cur = cur + cells[i]; }
      i = i + 1;
    }
    out[s] = cur;
    return out;
  }

  < -------------------------------------------------------------------- >
  < Case mapping through an EXPLICIT case-pair table. SLeeLa cannot know the >
  < Unicode case of an opaque glyph, so true case mapping is bridged. But when >
  < the caller supplies the mapping as two parallel String[] tables (fromSet[k] >
  < maps to toSet[k]), per-cell translation is fully real and honest -- the >
  < semantics are exactly what the caller declared, nothing assumed. >
  < -------------------------------------------------------------------- >

  < mapCell(cell, fromSet, toSet): the mapped cell if `cell` equals some >
  < fromSet[k] (first match wins), else `cell` unchanged. Real. >
  String mapCell(String cell, String[] fromSet, String[] toSet) {
    int n = arrayLength(fromSet);
    if (arrayLength(toSet) < n) { n = arrayLength(toSet); }
    int k = 0;
    while (k < n) {
      if (cell == fromSet[k]) { return toSet[k]; }
      k = k + 1;
    }
    return cell;
  }

  < mapCells(cells, fromSet, toSet): translate every cell through the pair table >
  < and return a NEW String[] of the same length (real). >
  String[] mapCells(String[] cells, String[] fromSet, String[] toSet) {
    int n = arrayLength(cells);
    String[] out = new String[n];
    int i = 0;
    while (i < n) { out[i] = mapCell(cells[i], fromSet, toSet); i = i + 1; }
    return out;
  }

  < mapCellsToString(cells, fromSet, toSet): as mapCells, rejoined to a String. >
  String mapCellsToString(String[] cells, String[] fromSet, String[] toSet) {
    return fromCells(mapCells(cells, fromSet, toSet));
  }

  < trimCells(cells, blankCell): drop leading and trailing cells equal to >
  < blankCell, returning the rejoined inner String (real). All-blank -> "". >
  String trimCells(String[] cells, String blankCell) {
    int n = arrayLength(cells);
    int lo = 0;
    while (lo < n && cells[lo] == blankCell) { lo = lo + 1; }
    int hi = n - 1;
    while (hi >= lo && cells[hi] == blankCell) { hi = hi - 1; }
    String out = "";
    int i = lo;
    while (i <= hi) { out = out + cells[i]; i = i + 1; }
    return out;
  }

  < ==================================================================== >
  < BRIDGED operations (char-level; cross the explicit VM/OS bridge) >
  < Each returns a stable, inspectable bridge-call descriptor rather than a >
  < fabricated result, so a caller / native runtime can dispatch honestly. >
  < ==================================================================== >

  < Descriptor builders. >
  String bridge(String op)                 { return "text.bridge:" + op + ":" + value; }
  String bridgeArg(String op, String a)    { return "text.bridge:" + op + ":" + value + ":" + a; }
  String bridgeArg2(String op, String a, String b) {
    return "text.bridge:" + op + ":" + value + ":" + a + ":" + b;
  }

  < bridgeOp(fields): read the op name back out of a descriptor that has been >
  < split on ":" into fields (field 0 == "text.bridge", field 1 == the op). >
  < Real: a caller that split the descriptor (e.g. via the bridged split()) can >
  < reason about it fully in-language. Returns "" if the array is malformed. >
  String bridgeOp(String[] fields) {
    if (arrayLength(fields) < 2) { return ""; }
    if (fields[0] != "text.bridge") { return ""; }
    return fields[1];
  }

  < isBridgeDescriptor(fields): true if the split fields name a text.bridge >
  < descriptor for a known op (real; composes bridgeOp + isBridged). >
  boolean isBridgeDescriptor(String[] fields) {
    return bridgeOp(fields) != "" && isBridged(bridgeOp(fields));
  }

  < Descriptor introspection: does this string name a bridged op, and which? >
  boolean isBridged(String op) {
    return op == "length"     || op == "charAt"    || op == "codePointAt"
        || op == "substring"  || op == "indexOf"   || op == "lastIndexOf"
        || op == "contains"   || op == "startsWith"|| op == "endsWith"
        || op == "replace"    || op == "replaceAll"|| op == "replaceFirst"
        || op == "toUpperCase"|| op == "toLowerCase"|| op == "trim"
        || op == "strip"      || op == "stripLeading" || op == "stripTrailing"
        || op == "split"      || op == "compareTo" || op == "matches"
        || op == "format"     || op == "formatWith"|| op == "chars"
        || op == "codePoints" || op == "normalize" || op == "equalsIgnoreCase"
        || op == "compareToIgnoreCase" || op == "hashCode" || op == "lengthValue";
  }
  < bridgeKind(op): "int" / "boolean" / "string" / "string[]" -- the TYPE the >
  < runtime yields for a bridged op, so a caller knows how to read the result >
  < even though the descriptor itself is carried as a String. >
  String bridgeKind(String op) {
    if (op == "length" || op == "lengthValue" || op == "indexOf"
        || op == "lastIndexOf" || op == "codePointAt" || op == "compareTo"
        || op == "compareToIgnoreCase" || op == "hashCode") { return "int"; }
    if (op == "contains" || op == "startsWith" || op == "endsWith"
        || op == "matches" || op == "equalsIgnoreCase") { return "boolean"; }
    if (op == "split" || op == "chars" || op == "codePoints") { return "string[]"; }
    return "string";
  }

  < Length / indexing -- bridged (no in-language char access). >
  < length() returns the descriptor; lengthValue() signals the int-typed form. >
  String length()            { return bridge("length"); }
  String lengthValue()       { return bridge("lengthValue"); }
  String charAt(String idx)  { return bridgeArg("charAt", idx); }
  String codePointAt(String idx) { return bridgeArg("codePointAt", idx); }
  String chars()             { return bridge("chars"); }

  < Slicing / search -- bridged. >
  String substring(String from, String to) { return bridgeArg2("substring", from, to); }
  String indexOf(String needle)            { return bridgeArg("indexOf", needle); }
  String lastIndexOf(String needle)        { return bridgeArg("lastIndexOf", needle); }
  String contains(String needle)           { return bridgeArg("contains", needle); }
  String startsWith(String prefix)         { return bridgeArg("startsWith", prefix); }
  String endsWith(String suffix)           { return bridgeArg("endsWith", suffix); }

  < Length / indexing (continued) -- bridged. >
  String codePoints()        { return bridge("codePoints"); }

  < Transformation -- bridged. >
  String toUpperCase()                     { return bridge("toUpperCase"); }
  String toLowerCase()                     { return bridge("toLowerCase"); }
  String trim()                            { return bridge("trim"); }
  String strip()                           { return bridge("strip"); }
  < strip only the leading / trailing run of Unicode whitespace -- char-level, >
  < so bridged (the in-language trimCells covers the explicit char-cell case). >
  String stripLeading()                    { return bridge("stripLeading"); }
  String stripTrailing()                   { return bridge("stripTrailing"); }
  < Unicode normalization (NFC/NFD/NFKC/NFKD named by `form`) -- bridged. >
  String normalize(String form)            { return bridgeArg("normalize", form); }
  String replace(String from, String to)   { return bridgeArg2("replace", from, to); }
  String replaceAll(String regex, String to){ return bridgeArg2("replaceAll", regex, to); }
  < replaceFirst: replace only the first regex match -- bridged. >
  String replaceFirst(String regex, String to){ return bridgeArg2("replaceFirst", regex, to); }

  < Splitting / matching / ordering / hashing -- bridged. >
  String split(String regex)               { return bridgeArg("split", regex); }
  String matches(String regex)             { return bridgeArg("matches", regex); }
  String compareTo(String other)           { return bridgeArg("compareTo", other); }
  String compareToIgnoreCase(String other) { return bridgeArg("compareToIgnoreCase", other); }
  String equalsIgnoreCase(String other)    { return bridgeArg("equalsIgnoreCase", other); }
  String hashCode()                        { return bridge("hashCode"); }

  < Formatting -- bridged (format uses the native formatter over the bridge). >
  String format(String pattern)            { return bridgeArg("format", pattern); }
  < formatWith(pattern, arg): single-argument printf-style format -- bridged. >
  String formatWith(String pattern, String arg) { return bridgeArg2("formatWith", pattern, arg); }

  < ---- introspection ------------------------------------------------- >
  String typeName()   { return "SLeeLa.text.SLString"; }
  boolean available() { return true; }

  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  < Eleven catalogued attributes with getter/setter pairs, so a GUI, loader, >
  < or catalog can read and (where appropriate) override each record. >
  < Values are faithful to the subject's real origin where publicly known. >
  String metaVersion = "1.1.0";
  int metaId = 11519;
  String metaAuthor = "SLeeLa standard library";
  String metaDate = "2026-10-23";
  String metaCopyright = "MEARVK LLC";
  String metaTrademark = "none";
  String metaCorporation = "MEARVK LLC";
  String metaOrigin = "International";
  String metaBirthDate = "2026";
  < maturity/robustness on a 1..10 scale >
  int metaScienceRating = 9;
  String metaNationalSchedule = "The Java Language Specification; Unicode / ISO/IEC 10646";

  String getMetaVersion() { return metaVersion; }
  void setMetaVersion(String v) { metaVersion = v; }
  int getMetaId() { return metaId; }
  void setMetaId(int v) { metaId = v; }
  String getAuthor() { return metaAuthor; }
  void setAuthor(String v) { metaAuthor = v; }
  String getDate() { return metaDate; }
  void setDate(String v) { metaDate = v; }
  String getCopyright() { return metaCopyright; }
  void setCopyright(String v) { metaCopyright = v; }
  String getTrademark() { return metaTrademark; }
  void setTrademark(String v) { metaTrademark = v; }
  String getCorporation() { return metaCorporation; }
  void setCorporation(String v) { metaCorporation = v; }
  String getOrigin() { return metaOrigin; }
  void setOrigin(String v) { metaOrigin = v; }
  String getBirthDate() { return metaBirthDate; }
  void setBirthDate(String v) { metaBirthDate = v; }
  int getScienceRating() { return metaScienceRating; }
  void setScienceRating(int v) { metaScienceRating = v; }
  String getNationalSchedule() { return metaNationalSchedule; }
  void setNationalSchedule(String v) { metaNationalSchedule = v; }
}