Add stringToChars and charsToString for character decomposition

atom_concat joins symbols but cannot split one, so a typed symbol name such as
e1_ep could not be taken apart into a base and a sort at run time. These are the
inverse pair: stringToChars splits a String into an Expression of
single-character symbols, and charsToString joins one back.

Characters are single-character symbols, matching hyperon-experimental and
mettalog (SWI string_chars). charsToString takes its list unevaluated, like
car-atom, because the characters of "+ab" are (+ a b) and evaluating the
argument would run an addition instead of joining it back; a computed list goes
in through let. Iterating with the spread keeps astral code points whole.

Author: MesTTo

packages/core/src/builtins.ts

@@ -1532,6 +1532,31 @@ const pettaEntries: Array<[string, GroundFn]> = [
     "atom_concat",
     (a) => ok(sym(a.map((x) => (x.kind === "sym" ? x.name : (asStr(x) ?? format(x)))).join(""))),
   ],
+  // stringToChars/charsToString are the inverse pair atom_concat lacks: split a String into an Expression
+  // of single-character symbols and join it back. Chars are single-character symbols, matching
+  // hyperon-experimental and mettalog (SWI `string_chars`). Iterating with the spread keeps astral code
+  // points (surrogate pairs) intact.
+  [
+    "stringToChars",
+    (a) => {
+      const s = asStr(a[0]!);
+      if (a.length !== 1 || s === undefined) return ierr("stringToChars expects a String");
+      return ok(expr([...s].map((ch) => sym(ch))));
+    },
+  ],
+  [
+    "charsToString",
+    (a) => {
+      const chars = a[0]!;
+      if (a.length !== 1 || chars.kind !== "expr")
+        return ierr("charsToString expects an Expression of characters");
+      return ok(
+        gstr(
+          chars.items.map((x) => (x.kind === "sym" ? x.name : (asStr(x) ?? format(x)))).join(""),
+        ),
+      );
+    },
+  ],
   // parse a string of MeTTa source into its (first) atom; sread is PeTTa's alias.
   [
     "parse",

packages/core/src/stdlib.test.ts

@@ -104,3 +104,42 @@ describe("spaces: get-atoms follows LeaTTa add-atom semantics", () => {
     ).toEqual(["(quote (foo (+ 1 1)))"]);
   });
 });
+
+describe("stdlib stringToChars / charsToString", () => {
+  it("stringToChars splits a string into single-character symbols", () => {
+    expect(r1('!(stringToChars "abc")')).toEqual(["(a b c)"]);
+  });
+
+  it("stringToChars of the empty string is the empty expression", () => {
+    expect(r1('!(stringToChars "")')).toEqual(["()"]);
+  });
+
+  it("charsToString joins a character list into a string", () => {
+    expect(r1("!(charsToString (a b c))")).toEqual(['"abc"']);
+  });
+
+  it("round-trips a string through its characters", () => {
+    // charsToString takes an Expression argument (unevaluated, like car-atom and hyperon-experimental), so
+    // a decoder binds the character list with let, or walks it with list ops, rather than nesting directly.
+    expect(r1('!(let $cs (stringToChars "e1_ep") (charsToString $cs))')).toEqual(['"e1_ep"']);
+  });
+
+  it("decomposes a legacy typed-symbol name into its characters", () => {
+    expect(r1('!(stringToChars "e1_ep")')).toEqual(["(e 1 _ e p)"]);
+  });
+
+  it("round-trips a string whose characters are operator symbols", () => {
+    // This is why charsToString takes Expression rather than %Undefined%: the character list of "+ab" is
+    // `(+ a b)`, so evaluating the argument would run it as an addition instead of joining it back.
+    expect(r1('!(stringToChars "+ab")')).toEqual(["(+ a b)"]);
+    expect(r1('!(let $cs (stringToChars "+ab") (charsToString $cs))')).toEqual(['"+ab"']);
+  });
+
+  it("keeps an astral character whole rather than splitting its surrogate pair", () => {
+    expect(r1('!(stringToChars "a\u{1F600}b")')).toEqual(["(a \u{1F600} b)"]);
+  });
+
+  it("evaluates the argument of stringToChars, so it composes with String-producing calls", () => {
+    expect(r1("!(stringToChars (repr foo))")).toEqual(["(f o o)"]);
+  });
+});

packages/core/src/stdlib.ts

@@ -92,6 +92,14 @@ export const STDLIB_SRC = `
   ; atom as written; to repr a reduced form, evaluate it first (e.g. bind it with let).
   (: repr (-> Atom String))
 
+  ; stringToChars splits a String into an Expression of single-character symbols; charsToString is the
+  ; inverse. The character list is ordinary data that car-atom/decons-atom walk, which is what lets a
+  ; legacy typed symbol name be taken apart into a base and a sort at run time. charsToString takes its
+  ; list unevaluated, like car-atom: the characters of "+ab" are (+ a b), which evaluating would run as an
+  ; addition. Bind a computed list with let, e.g. (let $cs (stringToChars $s) (charsToString $cs)).
+  (: stringToChars (-> String Expression))
+  (: charsToString (-> Expression String))
+
   ; trace! prints its first argument and returns the (evaluated) second.
   (: trace! (-> %Undefined% Atom %Undefined%))
   (= (trace! $msg $ret) (let $unit (println! $msg) $ret))