runmat 0.3.6 → 0.4.1

package/dist/generated/builtins/cell2mat.js

@@ -0,0 +1,142 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "cell2mat",
+    "category": "cells/core",
+    "keywords": [
+        "cell2mat",
+        "cell arrays",
+        "matrix conversion",
+        "block concatenation",
+        "gpu fallback"
+    ],
+    "summary": "Convert the contents of a MATLAB cell array into a dense numeric, logical, complex, or character matrix.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "cell2mat executes on the host. GPU-resident tensors inside the cell array are gathered before concatenation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::cells::core::cell2mat::tests",
+        "integration": "builtins::cells::core::cell2mat::tests::cell2mat_gpu_cells_are_gathered"
+    },
+    "description": "`cell2mat(C)` concatenates the numeric, logical, complex, or character arrays stored in the cell array `C` into a single dense MATLAB array. The cell array must form a rectangular block structure: all cells in the same row share the same number of rows, all cells in the same column share the same number of columns, and higher-dimensional extents agree everywhere.",
+    "behaviors": [
+        "Works for cell arrays whose elements are **numeric**, **logical**, **complex**, or **character** arrays (including scalars and empties). Mixed types are rejected.",
+        "RunMat currently represents cell arrays as 2-D grids. The first dimension tiles rows, the second tiles columns, and any higher dimensions inside each element must agree exactly across all cells.",
+        "Empty cells contribute zero extent in their tiling dimension while preserving type information.",
+        "The output array uses column-major layout for numeric, logical, and complex data, and matches MATLAB character array semantics for text.",
+        "Calling `cell2mat` on an empty cell array returns the empty double matrix `0×0`."
+    ],
+    "examples": [
+        {
+            "description": "Converting a 2-by-2 cell array of scalars into a matrix",
+            "input": "C = {1, 2; 3, 4};\nA = cell2mat(C)",
+            "output": "A =\n     1     2\n     3     4"
+        },
+        {
+            "description": "Concatenating blocks of different column widths",
+            "input": "C = {[1 2], [3 4 5]; [6 7], [8 9 10]};\nA = cell2mat(C)",
+            "output": "A =\n     1     2     3     4     5\n     6     7     8     9    10"
+        },
+        {
+            "description": "Converting logical cell contents into a logical matrix",
+            "input": "C = {true(2,1), false(2,1)};\nM = cell2mat(C)",
+            "output": "M =\n  2×2 logical array\n     1     0\n     1     0"
+        },
+        {
+            "description": "Handling complex-valued blocks",
+            "input": "C = {1+2i, [3+4i 5+6i]};\nZ = cell2mat(C)",
+            "output": "Z =\n   1.0000 + 2.0000i   3.0000 + 4.0000i   5.0000 + 6.0000i"
+        },
+        {
+            "description": "Producing character matrices from cell arrays of character rows",
+            "input": "C = {'foo', 'bar'; 'baz', 'qux'};\nS = cell2mat(C)",
+            "output": "S =\n    'foobar'\n    'bazqux'"
+        },
+        {
+            "description": "Tiling higher-dimensional numeric blocks",
+            "input": "C = {ones(2,2,3), 2*ones(2,1,3)};\nX = cell2mat(C);\nsize(X)",
+            "output": "ans =\n     2     3     3"
+        },
+        {
+            "description": "Working with empty cells",
+            "input": "C = {[], []; [], []};\nA = cell2mat(C);\nsize(A)",
+            "output": "ans =\n     0     0"
+        },
+        {
+            "description": "Gathering GPU tensors stored inside cells",
+            "input": "G = gpuArray(ones(4,1));\nC = {G, 2*G};\nH = cell2mat(C);   % gathered back to host automatically\nclassUnderlying(H)",
+            "output": "ans =\n    'double'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What element types does `cell2mat` support?",
+            "answer": "Numeric doubles (scalars or arrays), complex doubles, logical values, and character arrays. Mixed types are not allowed; every populated cell must have the same fundamental type."
+        },
+        {
+            "question": "Can I convert a cell array that contains structs or strings?",
+            "answer": "No. `cell2mat` requires array-like contents. Use specialised functions such as `string` or `char` converters for string data, or bespoke logic for structs and tables."
+        },
+        {
+            "question": "Do the cell contents need identical shapes?",
+            "answer": "Cells in the same row must share the same number of rows. Cells in the same column must share the same number of columns. Any higher dimensions must agree across all cells. Violations produce a descriptive error that mirrors MATLAB's behaviour."
+        },
+        {
+            "question": "What happens with empty cells?",
+            "answer": "Empty cells contribute zero extent along their tiling dimension. For example, if every element in a row is empty, the resulting matrix has zero rows for that block. Completely empty cell arrays produce the `0×0` empty double matrix."
+        },
+        {
+            "question": "Does `cell2mat` return GPU arrays when inputs are gpuArray elements?",
+            "answer": "Not yet. RunMat gathers GPU elements to the host before concatenating. Future releases may introduce GPU-resident cell storage, at which point providers can supply dedicated kernels."
+        }
+    ],
+    "links": [
+        {
+            "label": "cell",
+            "url": "./cell"
+        },
+        {
+            "label": "mat2cell",
+            "url": "./mat2cell"
+        },
+        {
+            "label": "cellfun",
+            "url": "./cellfun"
+        },
+        {
+            "label": "cellstr",
+            "url": "./cellstr"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/cells/core/cell2mat.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/cells/core/cell2mat.rs"
+    },
+    "gpu_residency": "You usually do NOT need to call `gpuArray` before `cell2mat`. The builtin always gathers GPU-resident elements to the host so it can stitch the resulting matrix in CPU memory. Explicitly wrapping each cell in `gpuArray` is harmless, but there is no residency benefit because the final result is a standard CPU array.",
+    "gpu_behavior": [
+        "`cell2mat` is inherently a host operation because MATLAB cell arrays live on the CPU heap. If a cell element is a GPU tensor (`gpuArray`) RunMat gathers it to host memory before concatenating. Providers do **not** need to implement bespoke kernels: the builtin terminates GPU fusion groups, materialises the inputs on the host, and returns a host-resident array."
+    ],
+    "key": "cell2mat",
+    "slug": "cell2mat",
+    "categoryPath": [
+        "cells",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=cell2mat.js.map

package/dist/generated/builtins/cell2mat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell2mat.js","sourceRoot":"","sources":["../../../src/generated/builtins/cell2mat.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/cellfun.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=cellfun.d.ts.map

package/dist/generated/builtins/cellfun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cellfun.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/cellfun.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAqKjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/cellfun.js

@@ -0,0 +1,170 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "cellfun",
+    "category": "cells/core",
+    "keywords": [
+        "cellfun",
+        "cell arrays",
+        "functional programming",
+        "uniformoutput",
+        "errorhandler"
+    ],
+    "summary": "Apply a function to every element of one or more cell arrays, mirroring MATLAB's cellfun behaviour.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "cellfun executes on the host. GPU-resident elements are gathered automatically before the callback is invoked."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::cells::core::cellfun::tests",
+        "integration": "builtins::cells::core::cellfun::tests::cellfun_error_handler_recovers"
+    },
+    "description": "`cellfun` maps a function over one or more cell arrays. Each cell's contents become inputs to the supplied function handle (or builtin name), and the results are collected either into a numeric/logical/complex array (`'UniformOutput', true`, the default) or into a new cell array (`'UniformOutput', false`). RunMat follows MATLAB's semantics for result collection, broadcasting extra arguments, the `'ErrorHandler'` hook, and the `'UniformOutput'` toggle.",
+    "behaviors": [
+        "All cell array inputs must share the same size. Extra arguments that are **not** cell arrays are treated as constants and forwarded to every invocation.",
+        "The callback may be supplied as a function handle (`@sin`), an anonymous function, or one of MATLAB's short string identifiers (for example `'isempty'` or `'isclass'`).",
+        "With `'UniformOutput', true` (default) the callback must return scalars (numeric, logical, or complex). The results are packed into an array that mirrors the cell array shape. Mixed real/complex outputs automatically promote to complex.",
+        "With `'UniformOutput', false` the callback may return arbitrary values; RunMat stores them in a new cell array that matches the input dimensions.",
+        "`'ErrorHandler', handler` intercepts runtime errors. When the callback throws, RunMat calls `handler(errStruct, cellValue1, cellValue2, ..., extraArg1, extraArg2, ...)`. The structure contains the fields `identifier`, `message`, `index` (1-based linear index), and `indices` (1×N vector of subscripts). The handler's return value is inserted into the result.",
+        "GPU values inside the cells are gathered to host memory before the callback runs so that uniform outputs can be materialised in CPU tensors today."
+    ],
+    "examples": [
+        {
+            "description": "Computing string lengths across a cell array",
+            "input": "C = {'apple', 'banana', 'cherry'};\nlengths = cellfun(@length, C)",
+            "output": "lengths =\n     5     6     6"
+        },
+        {
+            "description": "Mapping across two cell arrays in lockstep",
+            "input": "A = {1, 2, 3};\nB = {4, 5, 6};\ntotals = cellfun(@plus, A, B)",
+            "output": "totals =\n     5     7     9"
+        },
+        {
+            "description": "Keeping non-scalar outputs as cells",
+            "input": "names = {'Ada', 'Linus', 'Katherine'};\nupper = cellfun(@upper, names, 'UniformOutput', false)",
+            "output": "upper =\n  1×3 cell array\n    {'ADA'}    {'LINUS'}    {'KATHERINE'}"
+        },
+        {
+            "description": "Supplying additional arguments alongside each cell",
+            "input": "C = {magic(3), eye(3)};\ndiag3 = cellfun('size', C, 2)",
+            "output": "diag3 =\n     3     3"
+        },
+        {
+            "description": "Handling callback failures with `'ErrorHandler'`",
+            "input": "C = {'42', 'NaN', '3.14'};\nhandler = @(err, value) NaN;\nnumbers = cellfun(@str2double, C, 'ErrorHandler', handler)",
+            "output": "numbers =\n   42     NaN    3.1400"
+        },
+        {
+            "description": "Using builtin short names instead of function handles",
+            "input": "cells = {[], 1:5, zeros(0, 3)};\nempty_flags = cellfun('isempty', cells)",
+            "output": "empty_flags =\n     1     0     1"
+        },
+        {
+            "description": "Returning rich metadata in the error handler",
+            "input": "cells = {1, 'two', 3};\neh = @(err, value) sprintf('%s @ %d', err.identifier, err.index);\nresults = cellfun(@(x) x + 1, cells, 'UniformOutput', false, 'ErrorHandler', eh)",
+            "output": "results =\n  1×3 cell array\n    {[2]}    {[117 120 112]}    {[4]}"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `cellfun` modify the original cell array?",
+            "answer": "No. The builtin reads the cell contents, calls the supplied function, and returns a new array. The original cell array is never mutated."
+        },
+        {
+            "question": "What happens when the callback returns mixed real and complex values?",
+            "answer": "RunMat promotes the entire output to a complex array when `'UniformOutput', true`. Real results are converted to complex numbers with zero imaginary parts to match MATLAB."
+        },
+        {
+            "question": "Can the callback return strings or structs?",
+            "answer": "Yes, but you must specify `'UniformOutput', false`. That tells RunMat to collect results into a cell array rather than forcing scalar concatenation."
+        },
+        {
+            "question": "Are GPU arrays supported?",
+            "answer": "Yes. Inputs that live on the GPU are automatically gathered before the callback executes so the function can operate on host values. The final result is host-resident today."
+        },
+        {
+            "question": "How are errors reported to `'ErrorHandler'`?",
+            "answer": "The handler receives a structure with `identifier`, `message`, `index`, and `indices` fields followed by the values that triggered the error. Returning a value from the handler lets execution continue; rethrowing propagates the failure just like MATLAB."
+        },
+        {
+            "question": "Do extra non-cell arguments need to be the same size as the cells?",
+            "answer": "No. Extra arguments are treated as constants and forwarded unchanged for every element. Only the cell array inputs must agree on size."
+        },
+        {
+            "question": "Can `cellfun` be used with anonymous functions that capture variables?",
+            "answer": "Absolutely. Captures are forwarded to the generated closure before the cell elements, so anonymous functions behave the same way they do in MATLAB."
+        },
+        {
+            "question": "What are the default output types for empty inputs?",
+            "answer": "When the cell arrays are empty and `'UniformOutput', true`, RunMat returns an empty double array (size matches the input). For `'UniformOutput', false`, the result is an empty cell array."
+        },
+        {
+            "question": "Does `cellfun` support MATLAB's `'isclass'` short name?",
+            "answer": "Yes. RunMat maps `'isclass'` to the `class` builtin internally so you can write `cellfun('isclass', C, 'double')` just like in MATLAB."
+        },
+        {
+            "question": "What does cellfun do in MATLAB?",
+            "answer": "`cellfun` applies a function to each cell of a cell array and returns the collected results. For example, `cellfun(@length, C)` returns the length of each cell's contents."
+        },
+        {
+            "question": "How is cellfun different from arrayfun?",
+            "answer": "`cellfun` operates on cell arrays, while `arrayfun` operates on numeric or logical arrays. Use `cellfun` when your data is stored in cells (e.g., variable-length strings), and `arrayfun` for uniform numeric data."
+        },
+        {
+            "question": "Can cellfun return non-uniform outputs?",
+            "answer": "Yes. Set `'UniformOutput'` to `false` to collect results into a cell array when the function returns different sizes or types across cells."
+        }
+    ],
+    "links": [
+        {
+            "label": "cell",
+            "url": "./cell"
+        },
+        {
+            "label": "cell2mat",
+            "url": "./cell2mat"
+        },
+        {
+            "label": "mat2cell",
+            "url": "./mat2cell"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "cellstr",
+            "url": "./cellstr"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/cells/core/cellfun.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/cells/core/cellfun.rs"
+    },
+    "gpu_behavior": [
+        "`cellfun` itself is a host operation. RunMat gathers GPU-resident inputs before calling the callback and stores the outputs on the host. This guarantees deterministic behaviour even when the callback returns GPU arrays. Future acceleration hooks can elide the gather step when providers support nested callbacks, but no provider work is required for correctness today."
+    ],
+    "key": "cellfun",
+    "slug": "cellfun",
+    "categoryPath": [
+        "cells",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=cellfun.js.map

package/dist/generated/builtins/cellfun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cellfun.js","sourceRoot":"","sources":["../../../src/generated/builtins/cellfun.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/cellstr.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=cellstr.d.ts.map

package/dist/generated/builtins/cellstr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cellstr.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/cellstr.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA0IjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/cellstr.js

@@ -0,0 +1,143 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "cellstr",
+    "category": "cells/core",
+    "keywords": [
+        "cellstr",
+        "cell array",
+        "character vectors",
+        "string conversion",
+        "text",
+        "gpu fallback"
+    ],
+    "summary": "Convert character arrays, string arrays, or cell arrays of text into cell arrays of character vectors with MATLAB-compatible trimming semantics.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/cellstr.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host. GPU-resident inputs are gathered automatically and the result is always a host cell array."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::cells::core::cellstr::tests"
+    },
+    "description": "`cellstr` converts character arrays, string arrays, or cell arrays of character vectors into a cell array whose elements are character vectors (1-by-N char arrays). Trailing spaces in character array rows are trimmed to match MATLAB behaviour.",
+    "behaviors": [
+        "`cellstr(A)` with a character array `A` returns an `m × 1` cell array whose entries correspond to the rows of `A`, with trailing spaces removed from each row.",
+        "`cellstr(S)` with a string array `S` returns a cell array of the same size; each string scalar is converted to a character vector.",
+        "`cellstr(C)` with a cell array `C` normalises the contents so that every element becomes a character vector. String scalars are converted, existing character vectors are preserved, and any other type triggers an error just like MATLAB.",
+        "String arrays of any dimensionality preserve their exact shape. Ordering follows MATLAB's column-major semantics so downstream indexing sees the expected elements.",
+        "Empty character arrays result in empty cell arrays (for example, `0 × n` char arrays map to `0 × 1` cells). Empty strings become `\"\"` character vectors stored in single-cell outputs.",
+        "Missing string scalars are rendered as the literal `'<missing>'`, matching MATLAB's textual representation.",
+        "Inputs that are not text (numeric tensors, logical arrays, structs, GPU tensors, etc.) raise a MATLAB-compatible usage error.",
+        "Cell elements must already be text. Any numeric, logical, or GPU value inside the cell raises an error so that downstream code never sees non-text rows."
+    ],
+    "examples": [
+        {
+            "description": "Converting a character matrix into a column cell array",
+            "input": "A = ['apple '; 'berry '; 'citrus'];\nC = cellstr(A)",
+            "output": "C =\n  3x1 cell array\n    {'apple'}\n    {'berry'}\n    {'citrus'}"
+        },
+        {
+            "description": "Removing trailing spaces automatically",
+            "input": "words = ['a   '; 'b   '; 'c   '];\nC = cellstr(words)",
+            "output": "C =\n  3x1 cell array\n    {'a'}\n    {'b'}\n    {'c'}"
+        },
+        {
+            "description": "Converting a string array while preserving shape",
+            "input": "S = [\"north\" \"south\"; \"east\" \"west\"];\nC = cellstr(S)",
+            "output": "C =\n  2x2 cell array\n    {'north'}    {'south'}\n    {'east'}     {'west'}"
+        },
+        {
+            "description": "Normalising a cell array that mixes strings and character vectors",
+            "input": "C = {\"left\", 'right'};\nout = cellstr(C)",
+            "output": "out =\n  1x2 cell array\n    {'left'}    {'right'}"
+        },
+        {
+            "description": "Handling empty character arrays",
+            "input": "emptyChars = char.empty(0, 5);\nC = cellstr(emptyChars);\nsize(C)",
+            "output": "ans =\n     0     1"
+        },
+        {
+            "description": "Converting a single string scalar",
+            "input": "single = \"RunMat\";\nC = cellstr(single)",
+            "output": "C =\n  1x1 cell array\n    {'RunMat'}"
+        },
+        {
+            "description": "Validating non-text inputs",
+            "input": "try\n    cellstr(42);\ncatch ME\n    disp(ME.message)\nend",
+            "output": "cellstr: input must be a character array, string array, or cell array of character vectors"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `cellstr` trim whitespace inside the text?",
+            "answer": "No. Only trailing spaces added by rectangular character arrays are removed. Interior spaces and tabs are preserved exactly as supplied."
+        },
+        {
+            "question": "What happens when a cell element is not text?",
+            "answer": "`cellstr` raises an error: every element must be a character vector or string scalar. This matches MATLAB and prevents silent conversion of unsupported data such as numeric arrays."
+        },
+        {
+            "question": "Can the output stay on the GPU?",
+            "answer": "Not yet. The resulting cell array always lives on the host. Future versions may add GPU-backed cell containers, in which case the GPU metadata in this builtin will be updated accordingly without breaking user code."
+        },
+        {
+            "question": "Are string arrays with missing values supported?",
+            "answer": "Yes. Missing string scalars (rendered as `<missing>`) convert to the character vector `'<missing>'` in the output cell array."
+        },
+        {
+            "question": "How are empty inputs handled?",
+            "answer": "Empty character arrays become empty cell arrays (`0×1`). Empty string arrays return empty cell arrays matching their size. Empty strings become single cells that contain a 1×0 character vector."
+        },
+        {
+            "question": "Does `cellstr` copy existing cell arrays?",
+            "answer": "Yes. The builtin returns a fresh cell array where each element is normalised to a character vector. Elements that are already character vectors are cloned so that downstream code can modify the result without mutating the source cell."
+        }
+    ],
+    "links": [
+        {
+            "label": "cell",
+            "url": "./cell"
+        },
+        {
+            "label": "cell2mat",
+            "url": "./cell2mat"
+        },
+        {
+            "label": "cellfun",
+            "url": "./cellfun"
+        },
+        {
+            "label": "mat2cell",
+            "url": "./mat2cell"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/cells/core/cellstr.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/cells/core/cellstr.rs"
+    },
+    "gpu_residency": "No. `cellstr` executes on the host. If the input originates from the GPU (for example, a cell array whose elements were gathered lazily), RunMat performs the gather automatically before formatting the text. The output always resides on the CPU heap, mirroring MATLAB where cell arrays of text are CPU-managed containers.",
+    "gpu_behavior": [
+        "`cellstr` is a host-only builtin. If the input or any nested cell elements contain GPU tensors, RunMat gathers them to the host before conversion (including nested elements inside cell arrays). The resulting cell array is always allocated in host memory. No provider hooks are required at this stage, but the GPU metadata keeps the runtime aware that residency does not propagate past this builtin."
+    ],
+    "key": "cellstr",
+    "slug": "cellstr",
+    "categoryPath": [
+        "cells",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=cellstr.js.map

package/dist/generated/builtins/cellstr.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cellstr.js","sourceRoot":"","sources":["../../../src/generated/builtins/cellstr.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/char.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=char.d.ts.map

package/dist/generated/builtins/char.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"char.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/char.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA4KjB,CAAC;AAEF,eAAe,UAAU,CAAC"}