runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/union.js

@@ -0,0 +1,168 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "union",
+    "category": "array/sorting_sets",
+    "keywords": [
+        "union",
+        "set",
+        "stable",
+        "rows",
+        "indices",
+        "gpu"
+    ],
+    "summary": "Combine two arrays, returning their union with MATLAB-compatible ordering and index outputs.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/union.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "When no provider hook is available, tensors are gathered to the host and processed with the CPU implementation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::sorting_sets::union::tests",
+        "integration": "builtins::array::sorting_sets::union::tests::union_gpu_roundtrip"
+    },
+    "description": "`union(A, B)` creates the set-theoretic union of inputs `A` and `B`, returning a value array `C` that contains every distinct element (or row) appearing in either input. Optional second and third outputs provide indices back into `A` and `B` that identify which original elements contribute to each value in `C`.",
+    "behaviors": [
+        "`union(A, B)` flattens the inputs column-major, removes duplicates, and returns the sorted union of their values.",
+        "`[C, IA, IB] = union(A, B)` also returns index vectors where `IA` points to the elements in `A` that contribute to `C` and `IB` refers to the elements in `B` that only appear in `B`.",
+        "`union(A, B, 'stable')` preserves the first-seen order: unique values from `A` appear first, followed by new values appearing in `B`.",
+        "`union(A, B, 'rows')` treats each row as a record. Inputs must share the same number of columns.",
+        "Character arrays and string arrays are fully supported in both element and row modes.",
+        "Complex values follow MATLAB's ordering rules (magnitude first, then real/imaginary parts).",
+        "Legacy compatibility flags (`'legacy'` or `'R2012a'`) are not supported in RunMat."
+    ],
+    "examples": [
+        {
+            "description": "Combining Two Numeric Vectors",
+            "input": "A = [5 7 1];\nB = [3 1 1];\n[C, IA, IB] = union(A, B)",
+            "output": "C =\n     1\n     3\n     5\n     7\nIA =\n     3\n     1\n     2\nIB =\n     1"
+        },
+        {
+            "description": "Preserving Input Order with `'stable'`",
+            "input": "A = [5 7 1];\nB = [3 2 4];\nC = union(A, B, 'stable')",
+            "output": "C =\n     5\n     7\n     1\n     3\n     2\n     4"
+        },
+        {
+            "description": "Union of Matrix Rows",
+            "input": "A = [1 2; 3 4; 1 2];\nB = [3 4; 5 6];\n[C, IA, IB] = union(A, B, 'rows')",
+            "output": "C =\n     1     2\n     3     4\n     5     6\nIA =\n     1\n     2\nIB =\n     2"
+        },
+        {
+            "description": "Working with Character Arrays",
+            "input": "A = ['m','z'; 'm','a'];\nB = ['a','x'; 'm','a'];\nunion(A, B)",
+            "output": "ans =\n  4x1 char array\n    a\n    m\n    x\n    z"
+        },
+        {
+            "description": "Union on GPU Data",
+            "input": "G = gpuArray([1 4 2 5]);\nH = gpuArray([2 6]);\n[C, IA, IB] = union(G, H)",
+            "output": "C =\n     1\n     2\n     4\n     5\n     6\nIA =\n     1\n     3\n     4\nIB =\n     2"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "How are the index outputs defined?",
+            "answer": "`IA` lists the positions in `A` that contribute to `C`. `IB` lists the positions in `B` for union values that do not already appear in `A`. Both use MATLAB's one-based indexing."
+        },
+        {
+            "question": "What happens if I request `'stable'` ordering?",
+            "answer": "The output keeps the first occurrence order: all unique values from `A` appear first, followed by new values from `B` in the order they are encountered."
+        },
+        {
+            "question": "Can I use `'rows'` with string or character arrays?",
+            "answer": "Yes. `union` accepts string arrays and character arrays with the `'rows'` option, provided the inputs share the same number of columns."
+        },
+        {
+            "question": "How does `union` treat `NaN` values?",
+            "answer": "All `NaN` values are considered equal. Sorted unions place them at the end, while stable unions keep the first-seen `NaN`."
+        },
+        {
+            "question": "Does GPU execution change the behaviour?",
+            "answer": "No. When a provider does not implement a GPU kernel, RunMat automatically gathers inputs to the host, performs the union there, and returns host-resident outputs that match MATLAB semantics exactly."
+        },
+        {
+            "question": "What if the inputs have different shapes?",
+            "answer": "Element-wise unions accept any shapes; both inputs are flattened column-major. Row-wise unions require matching column counts and two-dimensional inputs."
+        },
+        {
+            "question": "Can I mix data types?",
+            "answer": "No. Inputs must belong to the same class (numeric/logical, complex, char, or string). Mixing classes produces a descriptive error."
+        },
+        {
+            "question": "Are scalar outputs returned as vectors?",
+            "answer": "Scalars follow MATLAB's behaviour: a `1×1` union result is represented as a scalar double."
+        },
+        {
+            "question": "Do trailing spaces matter for character data?",
+            "answer": "Yes. Character arrays treat every character, including trailing spaces, as significant—matching MATLAB's behaviour."
+        },
+        {
+            "question": "Is the `'legacy'` flag supported?",
+            "answer": "No. RunMat only implements the modern MATLAB semantics. Passing `'legacy'` or `'R2012a'` raises an error."
+        }
+    ],
+    "links": [
+        {
+            "label": "unique",
+            "url": "./unique"
+        },
+        {
+            "label": "sort",
+            "url": "./sort"
+        },
+        {
+            "label": "sortrows",
+            "url": "./sortrows"
+        },
+        {
+            "label": "argsort",
+            "url": "./argsort"
+        },
+        {
+            "label": "intersect",
+            "url": "./intersect"
+        },
+        {
+            "label": "ismember",
+            "url": "./ismember"
+        },
+        {
+            "label": "issorted",
+            "url": "./issorted"
+        },
+        {
+            "label": "setdiff",
+            "url": "./setdiff"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/sorting_sets/union.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/sorting_sets/union.rs"
+    },
+    "gpu_behavior": [
+        "`union` is registered as a residency sink. When tensors live on a GPU and the active provider does not expose a dedicated `union` hook, the runtime gathers them to host memory and executes the CPU implementation to guarantee MATLAB-compatible output.",
+        "Future providers may implement `ProviderHook::Custom(\"union\")` to keep data on the device."
+    ],
+    "key": "union",
+    "slug": "union",
+    "categoryPath": [
+        "array",
+        "sorting_sets"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=union.js.map

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

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

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

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

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

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

package/dist/generated/builtins/unique.js

@@ -0,0 +1,192 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "unique",
+    "category": "array/sorting_sets",
+    "keywords": [
+        "unique",
+        "set",
+        "distinct",
+        "stable",
+        "rows",
+        "indices",
+        "gpu",
+        "string",
+        "char"
+    ],
+    "summary": "Return the unique elements or rows of arrays with optional index outputs.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/unique.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uses the provider `unique` hook when available; default providers download to host memory and reuse the CPU implementation."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::array::sorting_sets::unique::tests",
+        "integration": "builtins::array::sorting_sets::unique::tests::unique_gpu_roundtrip"
+    },
+    "description": "`unique` removes duplicates from its input while providing optional index outputs that map between the original data and the returned distinct values (or rows). By default results are sorted, but you can request stable order, operate on rows, and choose whether the first or last occurrence is retained.",
+    "behaviors": [
+        "`unique(A)` flattens numeric, logical, character, string, or complex arrays column-major into a vector of unique values sorted ascending.",
+        "`[C, IA] = unique(A)` also returns the indices of the selected occurrences (`IA`) so that `C = A(IA)`.",
+        "`[C, IA, IC] = unique(A)` provides `IC`, the mapping from each element of `A` to the corresponding index in `C`.",
+        "`unique(A, 'stable')` preserves the first appearance order rather than sorting.",
+        "`unique(A, 'rows')` treats each row as an observation and returns a matrix (or char/string array) whose rows are unique.",
+        "`unique(A, 'last')` or `'first'` controls which occurrence contributes to `IA` (defaults to `'first'`).",
+        "Combinations such as `unique(A, 'rows', 'stable', 'last')` follow MATLAB's precedence rules; mutually exclusive flags (e.g. `'sorted'` with `'stable'`) are rejected.",
+        "Empty inputs return empty outputs with consistent dimensions.",
+        "Legacy switches such as `'legacy'` or `'R2012a'` are not supported; RunMat always follows the modern MATLAB semantics."
+    ],
+    "examples": [
+        {
+            "description": "Getting Sorted Unique Values",
+            "input": "A = [3 1 3 2];\nC = unique(A)",
+            "output": "C =\n     1\n     2\n     3"
+        },
+        {
+            "description": "Preserving Input Order with `'stable'`",
+            "input": "A = [4 2 4 1 2];\nC = unique(A, 'stable')",
+            "output": "C =\n     4\n     2\n     1"
+        },
+        {
+            "description": "Returning Indices for Reconstruction",
+            "input": "A = [7 5 7 3];\n[C, IA, IC] = unique(A);\nreconstructed = C(IC)",
+            "output": "C =\n     3\n     5\n     7\nIA =\n     4\n     2\n     1\nIC =\n     3\n     2\n     3\n     1\nreconstructed =\n     7\n     5\n     7\n     3"
+        },
+        {
+            "description": "Finding Unique Rows in a Matrix",
+            "input": "A = [1 3; 1 3; 2 4; 1 2];\n[C, IA, IC] = unique(A, 'rows')",
+            "output": "C =\n     1     2\n     1     3\n     2     4\nIA =\n     4\n     1\n     3\nIC =\n     2\n     2\n     3\n     1"
+        },
+        {
+            "description": "Selecting Last Occurrences",
+            "input": "A = [9 8 9 7 8];\n[C, IA] = unique(A, 'last')",
+            "output": "C =\n     7\n     8\n     9\nIA =\n     4\n     5\n     3"
+        },
+        {
+            "description": "Working with Empty Arrays",
+            "input": "A = zeros(0, 3);\n[C, IA, IC] = unique(A, 'rows')",
+            "output": "C =\nIA =\nIC ="
+        },
+        {
+            "description": "Using `unique` on GPU Arrays",
+            "input": "G = gpuArray([5 3 5 1]);\n[C, IA, IC] = unique(G, 'stable')",
+            "output": "C =\n     5\n     3\n     1\nIA =\n     1\n     2\n     4\nIC =\n     1\n     2\n     1\n     3"
+        },
+        {
+            "description": "Unique Characters in a Char Array",
+            "input": "chars = ['m','z'; 'm','a'];\n[C, IA] = unique(chars)",
+            "output": "C =\n    a\n    m\n    z\nIA =\n    4\n    1\n    3"
+        },
+        {
+            "description": "Unique Strings with Row Deduplication",
+            "input": "S = [\"alpha\" \"beta\"; \"alpha\" \"beta\"; \"gamma\" \"beta\"];\n[C, IA, IC] = unique(S, 'rows', 'stable')",
+            "output": "C =\n  2x2 string array\n    \"alpha\"    \"beta\"\n    \"gamma\"    \"beta\"\nIA =\n     1\n     3\nIC =\n     1\n     1\n     2"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which ordering does `unique` use by default?",
+            "answer": "Results are sorted in ascending order unless you pass `'stable'`, which preserves the first occurrence order."
+        },
+        {
+            "question": "How are the index outputs defined?",
+            "answer": "`IA` indexes into the original data (or rows). `IC` is a column vector mapping each element (or row) of the input to the position of the corresponding unique value in `C`."
+        },
+        {
+            "question": "What do `'first'` and `'last'` control?",
+            "answer": "They determine whether `IA` references the first or last occurrence of each distinct value/row. They do not affect `C` or `IC`."
+        },
+        {
+            "question": "Can I combine `'rows'` with `'stable'` or `'last'`?",
+            "answer": "Yes. All permutations of `'rows'`, `'stable'`/`'sorted'`, and `'first'`/`'last'` are accepted. The runtime enforces MATLAB's validation rules."
+        },
+        {
+            "question": "Does `unique` support complex numbers or characters?",
+            "answer": "Yes. Complex values use magnitude ordering for the sorted output, and character or string arrays produce results in their native container types (char arrays and string arrays respectively)."
+        },
+        {
+            "question": "How does `unique` treat NaN values?",
+            "answer": "All NaN values are considered equal. Sorted outputs place NaNs at the end; stable outputs keep their original relative order."
+        },
+        {
+            "question": "Are GPU arrays supported?",
+            "answer": "Yes. When a provider lacks a native kernel, RunMat gathers GPU arrays to host memory and executes the host implementation, guaranteeing MATLAB-compatible output."
+        },
+        {
+            "question": "Does `unique` preserve array shape?",
+            "answer": "Scalar outputs remain scalars. Otherwise, values are returned as column vectors (for element mode) or matrices with the same number of columns as the input (for `'rows'`)."
+        },
+        {
+            "question": "What happens with empty inputs?",
+            "answer": "Empty inputs (including empty matrices) return empty outputs with matching dimensions, and index outputs are empty column vectors."
+        },
+        {
+            "question": "Is `unique` stable?",
+            "answer": "Sorting is stable where applicable; ties preserve their relative order. You can also request `'stable'` explicitly."
+        }
+    ],
+    "links": [
+        {
+            "label": "sort",
+            "url": "./sort"
+        },
+        {
+            "label": "sortrows",
+            "url": "./sortrows"
+        },
+        {
+            "label": "argsort",
+            "url": "./argsort"
+        },
+        {
+            "label": "intersect",
+            "url": "./intersect"
+        },
+        {
+            "label": "ismember",
+            "url": "./ismember"
+        },
+        {
+            "label": "issorted",
+            "url": "./issorted"
+        },
+        {
+            "label": "setdiff",
+            "url": "./setdiff"
+        },
+        {
+            "label": "union",
+            "url": "./union"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/array/sorting_sets/unique.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/array/sorting_sets/unique.rs"
+    },
+    "gpu_behavior": [
+        "`unique` is registered as a residency sink. When the provider exposes the custom `unique` hook, the runtime can execute the operation entirely on the device and keep results resident. If the active provider does not implement that hook, RunMat gathers the data to host memory, performs the CPU implementation, and returns host-resident outputs so subsequent MATLAB code observes the same values and ordering."
+    ],
+    "key": "unique",
+    "slug": "unique",
+    "categoryPath": [
+        "array",
+        "sorting_sets"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=unique.js.map

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

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

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

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

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

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

package/dist/generated/builtins/upper.js

@@ -0,0 +1,179 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "upper",
+    "category": "strings/transform",
+    "keywords": [
+        "upper",
+        "uppercase",
+        "convert to uppercase",
+        "string case",
+        "character arrays"
+    ],
+    "summary": "Convert strings, character arrays, and cell arrays of character vectors to uppercase.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/upper.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs on the CPU; GPU-resident inputs are gathered before conversion to keep MATLAB parity."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::strings::transform::upper::tests",
+        "integration": "builtins::strings::transform::upper::tests::upper_cell_array_mixed_content"
+    },
+    "description": "`upper(text)` converts every alphabetic character in `text` to uppercase. It accepts string scalars, string arrays, character arrays, and cell arrays of character vectors, mirroring MATLAB behaviour. Non-alphabetic characters are returned unchanged.",
+    "behaviors": [
+        "String inputs stay as strings. String arrays preserve their size, orientation, and missing values.",
+        "Character arrays are processed row by row. The result remains a rectangular char array; if any row grows after uppercasing (for example `'ß' → \"SS\"`), the array widens and shorter rows are padded with spaces.",
+        "Cell arrays must contain string scalars or character vectors. The result is a cell array of the same size with each element converted to uppercase; other types raise MATLAB-compatible errors.",
+        "Missing string scalars (`string(missing)`) remain `<missing>` so downstream code behaves like MATLAB.",
+        "Inputs that are numeric, logical, structs, or GPU tensors raise MATLAB-compatible type errors."
+    ],
+    "examples": [
+        {
+            "description": "Convert a string scalar to uppercase",
+            "input": "txt = \"RunMat\";\nresult = upper(txt)",
+            "output": "result = \"RUNMAT\""
+        },
+        {
+            "description": "Uppercase each element of a string array",
+            "input": "labels = [\"north\" \"South\"; \"East\" \"west\"];\nuppered = upper(labels)",
+            "output": "uppered = 2×2 string\n    \"NORTH\"    \"SOUTH\"\n    \"EAST\"     \"WEST\""
+        },
+        {
+            "description": "Uppercase character array rows while preserving shape",
+            "input": "animals = char(\"cat\", \"doge\");\nresult = upper(animals)",
+            "output": "result =\n\n  2×4 char array\n\n    'CAT '\n    'DOGE'"
+        },
+        {
+            "description": "Uppercase a cell array of character vectors",
+            "input": "C = {'hello', 'World'};\nout = upper(C)",
+            "output": "out = 1×2 cell array\n    {'HELLO'}    {'WORLD'}"
+        },
+        {
+            "description": "Keep missing strings as missing",
+            "input": "vals = [\"data\", string(missing), \"gpu\"];\nconverted = upper(vals)",
+            "output": "converted = 1×3 string\n    \"DATA\"    <missing>    \"GPU\""
+        },
+        {
+            "description": "Handle text stored on a GPU input",
+            "input": "codes = gpuArray(uint16('runmat'));\ntxt = char(gather(codes));\nresult = upper(txt)",
+            "output": "result = 'RUNMAT'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `upper` change non-alphabetic characters?",
+            "answer": "No. Digits, punctuation, whitespace, and symbols remain untouched. Only alphabetic code points that have distinct uppercase forms are converted."
+        },
+        {
+            "question": "What happens to character array dimensions?",
+            "answer": "RunMat uppercases each row independently and pads with spaces when an uppercase mapping increases the row length. This mirrors MATLAB’s behaviour so the result always has rectangular dimensions."
+        },
+        {
+            "question": "Can I pass numeric arrays to `upper`?",
+            "answer": "No. Passing numeric, logical, or struct inputs raises a MATLAB-compatible error. Convert the data to a string or character array first (for example with `string` or `char`)."
+        },
+        {
+            "question": "How are missing strings handled?",
+            "answer": "Missing string scalars remain `<missing>` and are returned unchanged. This matches MATLAB’s handling of missing values in text processing functions."
+        },
+        {
+            "question": "Will `upper` ever execute on the GPU?",
+            "answer": "Not today. The builtin gathers GPU-resident data automatically and performs the conversion on the CPU so the results match MATLAB exactly. Providers may add device-side kernels in the future, but behaviour will remain compatible."
+        }
+    ],
+    "links": [
+        {
+            "label": "lower",
+            "url": "./lower"
+        },
+        {
+            "label": "string",
+            "url": "./string"
+        },
+        {
+            "label": "char",
+            "url": "./char"
+        },
+        {
+            "label": "regexprep",
+            "url": "./regexprep"
+        },
+        {
+            "label": "strcmpi",
+            "url": "./strcmpi"
+        },
+        {
+            "label": "erase",
+            "url": "./erase"
+        },
+        {
+            "label": "eraseBetween",
+            "url": "./erasebetween"
+        },
+        {
+            "label": "extractBetween",
+            "url": "./extractbetween"
+        },
+        {
+            "label": "join",
+            "url": "./join"
+        },
+        {
+            "label": "pad",
+            "url": "./pad"
+        },
+        {
+            "label": "replace",
+            "url": "./replace"
+        },
+        {
+            "label": "split",
+            "url": "./split"
+        },
+        {
+            "label": "strcat",
+            "url": "./strcat"
+        },
+        {
+            "label": "strip",
+            "url": "./strip"
+        },
+        {
+            "label": "strrep",
+            "url": "./strrep"
+        },
+        {
+            "label": "strtrim",
+            "url": "./strtrim"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/strings/transform/upper.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/transform/upper.rs"
+    },
+    "gpu_residency": "RunMat keeps text data in host memory, so you typically work with ordinary string and character arrays. When text originates from GPU computations (for example, numeric code points produced by kernels), gather those values to the host and convert them to text before calling `upper`.",
+    "gpu_behavior": [
+        "`upper` executes on the CPU. Text values currently reside in host memory, so providers do not offer device kernels for this builtin. When you pass a container that still holds GPU handles (for example, a struct whose string fields were gathered lazily), RunMat gathers those handles before performing the conversion. If you store characters as numeric code points on the GPU, gather and convert them to text before calling `upper`."
+    ],
+    "key": "upper",
+    "slug": "upper",
+    "categoryPath": [
+        "strings",
+        "transform"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=upper.js.map

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

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

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

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

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

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