runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/floor.js

@@ -0,0 +1,187 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "floor",
+    "category": "math/rounding",
+    "keywords": [
+        "floor",
+        "rounding",
+        "digits",
+        "significant digits",
+        "gpu",
+        "like"
+    ],
+    "summary": "Round scalars, vectors, matrices, or N-D tensors toward negative infinity or to specified digits.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Falls back to the host implementation when the active provider lacks unary_floor."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::rounding::floor::tests",
+        "integration": "builtins::math::rounding::floor::tests::floor_gpu_provider_roundtrip"
+    },
+    "description": "`floor(X)` rounds each element of `X` toward negative infinity, returning the greatest integer less than or equal to the input. Optional arguments match MATLAB's extended syntax for rounding to fixed decimal places, significant digits, and prototype-based residency.",
+    "behaviors": [
+        "Works on scalars, vectors, matrices, and higher-dimensional tensors with MATLAB broadcasting semantics.",
+        "`floor(X, N)` rounds toward negative infinity with `N` decimal digits (positive `N`) or powers of ten (negative `N`).",
+        "`floor(X, N, 'significant')` rounds to `N` significant digits; `N` must be a positive integer.",
+        "Logical inputs are promoted to doubles (`false → 0`, `true → 1`) before flooring.",
+        "Character arrays are interpreted numerically (their Unicode code points) and return dense double tensors.",
+        "Complex inputs are floored component-wise: `floor(a + bi) = floor(a) + i·floor(b)`.",
+        "Non-finite values (`NaN`, `Inf`, `-Inf`) propagate unchanged.",
+        "Empty arrays return empty arrays of the appropriate shape.",
+        "Appending `'like', prototype` forces the result to match the residency of `prototype` (CPU or GPU). Currently prototypes must be numeric."
+    ],
+    "examples": [
+        {
+            "description": "Flooring positive and negative scalars",
+            "input": "x = [-2.7, -0.3, 0, 0.8, 3.9];\ny = floor(x)",
+            "output": "y = [-3, -1, 0, 0, 3]"
+        },
+        {
+            "description": "Flooring every element of a matrix",
+            "input": "A = [1.2 4.7; -3.4 5.0];\nB = floor(A)",
+            "output": "B = [1 4; -4 5]"
+        },
+        {
+            "description": "Flooring fractions stored in a tensor",
+            "input": "t = reshape([-1.8, -0.2, 0.4, 1.9, 2.1, 3.6], [3, 2]);\nfloored = floor(t)",
+            "output": "floored =\n    [-2  1;\n     -1  2;\n      0  3]"
+        },
+        {
+            "description": "Flooring values to a fixed number of decimal places",
+            "input": "temps = [21.456 19.995 22.501];\nfloored = floor(temps, 2)",
+            "output": "floored = [21.45 19.99 22.50]"
+        },
+        {
+            "description": "Flooring to significant digits",
+            "input": "measurements = [0.001234 12.3456 98765];\nsig2 = floor(measurements, 2, 'significant')",
+            "output": "sig2 = [0.0012 12.0 98000]"
+        },
+        {
+            "description": "Flooring complex numbers component-wise",
+            "input": "z = [1.7 + 2.1i, -0.2 - 3.9i];\nresult = floor(z)",
+            "output": "result = [1 + 2i, -1 - 4i]"
+        },
+        {
+            "description": "Keeping GPU data on device when the provider supports `unary_floor`",
+            "input": "G = gpuArray([1.8 -0.2 0.0; -1.1 2.5 -3.4]);\nfloored = floor(G);\nH = gather(floored)",
+            "output": "H =\n    [ 1 -1  0;\n     -2  2 -4]"
+        },
+        {
+            "description": "Forcing GPU residency with a `'like'` prototype",
+            "input": "A = [1.8 -0.2; 2.7 3.4];\nproto = gpuArray(0);\nG = floor(A, 'like', proto);   % Result remains on the GPU\nresult = gather(G)",
+            "output": "result =\n    [ 1 -1;\n      2  3]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `floor` always round toward negative infinity?",
+            "answer": "Yes—positive values round down toward zero, while negative values round to the more negative integer (e.g., `floor(-0.1) = -1`)."
+        },
+        {
+            "question": "How are complex numbers handled?",
+            "answer": "The real and imaginary parts are floored independently, matching MATLAB's component-wise definition."
+        },
+        {
+            "question": "Can I round to decimal digits or significant digits?",
+            "answer": "Yes. Use `floor(X, N)` for decimal digits or `floor(X, N, 'significant')` for significant digits. Negative `N` values round to powers of ten."
+        },
+        {
+            "question": "What happens with logical arrays?",
+            "answer": "Logical values promote to doubles (`0` or `1`) before flooring, so the outputs remain 0 or 1."
+        },
+        {
+            "question": "Can I pass character arrays to `floor`?",
+            "answer": "Yes. Character data is treated as its numeric code points, producing a double tensor of the same size."
+        },
+        {
+            "question": "Do `NaN` and `Inf` values change?",
+            "answer": "No. Non-finite inputs propagate unchanged."
+        },
+        {
+            "question": "Will GPU execution change floating-point results?",
+            "answer": "No. Providers implement IEEE-compliant flooring; when a provider lacks `unary_floor`, RunMat falls back to the CPU to preserve MATLAB-compatible behaviour."
+        },
+        {
+            "question": "Does `'like'` work with `floor`?",
+            "answer": "Yes. Append `'like', prototype` to request output that matches the prototype's residency. Currently prototypes must be numeric (scalars or dense tensors, host or GPU)."
+        },
+        {
+            "question": "Can fusion keep `floor` on the GPU?",
+            "answer": "Yes. `floor` participates in elementwise fusion, so fused graphs can stay resident on the device when supported."
+        },
+        {
+            "question": "What does floor do in MATLAB?",
+            "answer": "`floor(X)` rounds each element of `X` toward negative infinity. For example, `floor(2.7)` returns `2` and `floor(-2.3)` returns `-3`."
+        },
+        {
+            "question": "What is the difference between floor and fix in MATLAB?",
+            "answer": "`floor` rounds toward negative infinity, while `fix` rounds toward zero. For positive numbers the result is the same, but for negative numbers they differ: `floor(-2.7)` returns `-3`, while `fix(-2.7)` returns `-2`."
+        },
+        {
+            "question": "Does floor work with GPU arrays in RunMat?",
+            "answer": "Yes. RunMat automatically accelerates `floor` on the GPU with elementwise fusion support. Supported precisions include `f32` and `f64` with MATLAB-compatible broadcasting."
+        }
+    ],
+    "links": [
+        {
+            "label": "ceil",
+            "url": "./ceil"
+        },
+        {
+            "label": "round",
+            "url": "./round"
+        },
+        {
+            "label": "fix",
+            "url": "./fix"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "mod",
+            "url": "./mod"
+        },
+        {
+            "label": "rem",
+            "url": "./rem"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/rounding/floor.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/rounding/floor.rs"
+    },
+    "gpu_residency": "```matlab:runnable\nA = [1.8 -0.2; 2.7 3.4];\nproto = gpuArray(0);\nG = floor(A, 'like', proto);   % Result remains on the GPU\nresult = gather(G);\n```\n\nExpected output:\n\n```matlab\nresult =\n    [ 1 -1;\n      2  3]\n```",
+    "gpu_behavior": [
+        "When tensors already reside on the GPU, RunMat consults the active acceleration provider. If the provider implements the `unary_floor` hook, `floor(X)` executes entirely on the device and keeps tensors resident. When decimal or significant-digit rounding is requested—or when the provider lacks `unary_floor`—RunMat gathers the tensor to host memory, applies the CPU implementation, and honours any `'like'` GPU prototype by uploading the result back to the device. This keeps semantics consistent even when specialised kernels are unavailable."
+    ],
+    "key": "floor",
+    "slug": "floor",
+    "categoryPath": [
+        "math",
+        "rounding"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=floor.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fopen.js

@@ -0,0 +1,176 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fopen",
+    "category": "io/filetext",
+    "keywords": [
+        "fopen",
+        "file",
+        "io",
+        "permission",
+        "encoding",
+        "machine format"
+    ],
+    "summary": "Open a file and obtain a MATLAB-compatible file identifier.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/fopen.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the host CPU. Inputs residing on the GPU are gathered automatically; file handles always live on the host."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 4,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::fopen::tests",
+        "integration": "builtins::io::filetext::fopen::tests::fopen_list_all_includes_handles"
+    },
+    "description": "`fopen` opens a file and returns a numeric file identifier (`fid`) that other I/O functions use. It mirrors MATLAB's permissions (`'r'`, `'w'`, `'a'`, `'+`, `'b'`, `'t'`), respects machine-format specifiers, and records the text encoding used for subsequent reads and writes.",
+    "behaviors": [
+        "`fid = fopen(filename)` opens an existing file for reading. The call fails (returning `fid = -1`) when the file cannot be opened.",
+        "`fid = fopen(filename, permission)` opens a file using the requested permission string (`'r'`, `'w'`, `'a'`, `'r+'`, `'w+'`, `'a+'`, plus optional `'b'`/`'t'`). Permissions map to the same semantics as MATLAB: `'w'` truncates, `'a'` appends, and `'+'` enables reading and writing.",
+        "`fid = fopen(filename, permission, machinefmt, encoding)` records the requested machine format (`'native'`, `'ieee-le'`, `'ieee-be'`) and text encoding (defaults to UTF-8 in text mode, `binary` otherwise) for later inspection.",
+        "`[fid, message] = fopen(...)` returns an empty character vector on success and the operating-system error message on failure.",
+        "`[filename, permission, machinefmt, encodingOut] = fopen(fid)` queries an existing file identifier.",
+        "`[fid_list, names, machinefmts, encodings] = fopen('all')` lists every open file (including standard input/output/error) and returns cell arrays containing metadata for each entry.",
+        "`[fid_list, names] = fopen('all', machinefmt)` filters the listing to files whose recorded machine format (for example `'ieee-be'` or `'native'`) matches the requested value.",
+        "RunMat gathers GPU-resident filename arguments before opening files; the resulting handles always live on the host. Providers do not implement GPU kernels for file I/O."
+    ],
+    "examples": [
+        {
+            "description": "Open a File for Reading",
+            "input": "[fid, message] = fopen('data/input.txt', 'r');\nif fid == -1\n    error('Failed to open file: %s', message);\nend"
+        },
+        {
+            "description": "Write Text to a New File",
+            "input": "[fid, message] = fopen('logs/session.log', 'w');\nif fid == -1\n    error('Failed to create log file: %s', message);\nend\nfprintf(fid, 'Session started\\n');\nfclose(fid)"
+        },
+        {
+            "description": "Append Binary Data",
+            "input": "[fid, message] = fopen('signals.bin', 'ab+');\nif fid == -1\n    error('Failed to open binary log: %s', message);\nend\nfwrite(fid, rand(1, 1024), 'double');\nfclose(fid)"
+        },
+        {
+            "description": "Query File Metadata",
+            "input": "fid = fopen('config.json');\n[filename, permission, machinefmt, encoding] = fopen(fid);\ndisp(filename);\ndisp(permission);\nfclose(fid)"
+        },
+        {
+            "description": "List All Open Files",
+            "input": "[fid_list, names] = fopen('all');\ndisp(fid_list);\ndisp(names)"
+        },
+        {
+            "description": "Handle Missing Files Gracefully",
+            "input": "[fid, message] = fopen('does_not_exist.txt', 'r');\nif fid == -1\n    fprintf('Failed to open file: %s\\n', message);\nend"
+        },
+        {
+            "description": "Specify Machine Format and Encoding",
+            "input": "[fid, message, machinefmt, encoding] = fopen('report.txt', 'w', 'ieee-le', 'latin1');\nif fid == -1\n    error('Failed to open report: %s', message);\nend\nfprintf(fid, 'olá mundo');\nfclose(fid)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What values can I use for the permission argument?",
+            "answer": "Use the same strings MATLAB accepts: `'r'`, `'w'`, `'a'`, optionally combined with `'+'` and `'b'`/`'t'`. For example, `'r+'` opens an existing file for reading and writing, `'wb'` opens a binary file for writing (truncating any existing content), and `'ab+'` appends to a binary file while permitting reads."
+        },
+        {
+            "question": "How do I close a file after opening it?",
+            "answer": "Call `fclose(fid)` with the file identifier returned by `fopen`. RunMat tracks open handles in a registry so that `fclose`, `fread`, and `fwrite` can reuse the same identifier."
+        },
+        {
+            "question": "What happens if `fopen` fails?",
+            "answer": "`fopen` returns `fid = -1` and the second output argument contains the OS error message. The third and fourth outputs are empty character vectors when opening fails."
+        },
+        {
+            "question": "Which encoding does RunMat use by default?",
+            "answer": "Text-mode files default to UTF-8 unless you specify the `encoding` argument. Binary permissions (`'...b'`) implicitly use the pseudo-encoding `binary`."
+        },
+        {
+            "question": "Does `fopen('all')` include standard input and output?",
+            "answer": "Yes. The returned identifier list always contains `0` (standard input), `1` (standard output), and `2` (standard error), followed by any user-opened files."
+        },
+        {
+            "question": "Are machine formats honoured during reads and writes?",
+            "answer": "RunMat records the requested machine format so that `fread`/`fwrite` can apply byte-order conversions. Hosts default to `'native'`, while passing `'ieee-le'` or `'ieee-be'` forces little or big-endian interpretation respectively."
+        },
+        {
+            "question": "Can I open the same file multiple times?",
+            "answer": "Yes. Each successful call to `fopen` registers a new handle with its own identifier, even if the path string matches an existing entry."
+        },
+        {
+            "question": "Does `fopen` support network paths or UNC shares?",
+            "answer": "RunMat relies on the operating system for path resolution, so UNC paths and mounted network shares are supported as long as the OS can open them."
+        },
+        {
+            "question": "What does fopen do in MATLAB?",
+            "answer": "`fopen` opens a file and returns a file identifier (fid) used by subsequent I/O functions like `fread`, `fwrite`, `fprintf`, and `fclose`. If the file cannot be opened, it returns `-1`."
+        },
+        {
+            "question": "How do I read a text file line by line in MATLAB?",
+            "answer": "Open the file with `fid = fopen('file.txt', 'r')`, then loop with `fgets(fid)` until `feof(fid)` returns true, and finally close with `fclose(fid)`. RunMat supports this same pattern."
+        },
+        {
+            "question": "What file modes does fopen support?",
+            "answer": "`fopen` supports `'r'` (read), `'w'` (write, creates or overwrites), `'a'` (append), `'r+'` (read and write), `'w+'` (read and write, truncates), and `'a+'` (read and append)."
+        }
+    ],
+    "links": [
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "fprintf",
+            "url": "./fprintf"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/io/filetext/fopen.rs",
+        "url": "crates/runmat-runtime/src/builtins/io/filetext/fopen.rs"
+    },
+    "gpu_behavior": [
+        "`fopen` always executes on the CPU. When a filename argument resides on a GPU array, RunMat gathers it to host memory before opening the file. File identifiers and their associated metadata are managed by a host-side registry that other builtins (such as `fclose`, `fread`, and `fwrite`) consult."
+    ],
+    "key": "fopen",
+    "slug": "fopen",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fopen.js.map

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

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

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

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

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

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

package/dist/generated/builtins/fprintf.js

@@ -0,0 +1,181 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "fprintf",
+    "category": "io/filetext",
+    "keywords": [
+        "fprintf",
+        "format",
+        "printf",
+        "write file",
+        "stdout",
+        "stderr",
+        "encoding"
+    ],
+    "summary": "Write formatted text to files or standard output/error using MATLAB-compatible semantics.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/fprintf.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Formatting and I/O execute on the CPU. GPU tensors are gathered automatically before substitution."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 3,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::filetext::fprintf::tests",
+        "integration": [
+            "builtins::io::filetext::fprintf::tests::fprintf_matrix_column_major",
+            "builtins::io::filetext::fprintf::tests::fprintf_ascii_encoding_errors",
+            "builtins::io::filetext::fprintf::tests::fprintf_gpu_gathers_values"
+        ]
+    },
+    "description": "`fprintf` formats data according to a printf-style template and writes the result to a file, standard output (`stdout`), or standard error (`stderr`). The builtin mirrors MATLAB behaviour, including repetition of the format string, column-major traversal of matrix inputs, support for the special stream names `'stdout'`/`'stderr'`, and the same set of numeric and text conversions available to `sprintf`.",
+    "behaviors": [
+        "`fprintf(formatSpec, A, ...)` writes to standard output. The format repeats automatically until every element from the argument list has been consumed, traversing arrays in column-major order.",
+        "`fprintf(fid, formatSpec, A, ...)` writes to a file identifier returned by `fopen`. Identifiers `1`/`\"stdout\"` and `2`/`\"stderr\"` refer to the process streams. Identifiers must be finite, non-negative integers.",
+        "The return value is the number of bytes written as a double scalar. Omitting the output argument discards it without affecting the write.",
+        "Text arguments (character vectors, string scalars, string arrays, cell arrays of text) are expanded in column-major order, matching MATLAB's behaviour.",
+        "Numeric arrays (double, integer, logical, or gpuArray) are flattened column-first and substituted element-by-element into the format string. Star (`*`) width and precision arguments are also drawn from the flattened stream.",
+        "The text encoding recorded by `fopen` is honoured. ASCII and Latin-1 encodings raise descriptive errors when characters cannot be represented. Binary/RAW encodings treat the output as UTF-8, mirroring MATLAB's default on modern systems.",
+        "Arguments that reside on the GPU are gathered to the host before formatting. Formatting itself is always executed on the CPU."
+    ],
+    "examples": [
+        {
+            "description": "Write Formatted Text To A File",
+            "input": "[fid, msg] = fopen('report.txt', 'w');\nassert(fid ~= -1, msg);\nfprintf(fid, 'Total: %d (%.2f%%)\\n', 42, 87.5);\nfclose(fid)"
+        },
+        {
+            "description": "Use Standard Output Without An Explicit File Identifier",
+            "input": "n = 42;\nfprintf('Processed %d items\\n', n)"
+        },
+        {
+            "description": "Write To Standard Error Using The Stream Name",
+            "input": "iter = 100;\nfprintf('stderr', 'Warning: iteration limit reached (%d steps)\\n', iter)"
+        },
+        {
+            "description": "Format A Matrix In Column-Major Order",
+            "input": "A = [1 2 3; 4 5 6];\nfprintf('%d %d\\n', A)"
+        },
+        {
+            "description": "Respect File Encoding Constraints",
+            "input": "[fid, msg] = fopen('ascii.txt', 'w', 'native', 'ascii');\nif fid == -1, error(msg); end\ntry\n    fprintf(fid, 'café\\n');\ncatch err\n    disp(err.message);\nend\nfclose(fid)"
+        },
+        {
+            "description": "Format GPU-Resident Data Transparently",
+            "input": "G = gpuArray([1.2 3.4 5.6]);\n[fid, msg] = fopen('gpu.txt', 'w');\nassert(fid ~= -1, msg);\nfprintf(fid, '%.1f,', G);\nfclose(fid)"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `fprintf` return the number of characters or bytes?",
+            "answer": "It returns the number of bytes written. This may differ from the number of characters when using multi-byte encodings such as UTF-8."
+        },
+        {
+            "question": "Can I use `'stdout'` or `'stderr'` instead of numeric identifiers?",
+            "answer": "Yes. The strings `'stdout'` and `'stderr'` (any case) map to identifiers `1` and `2` respectively, matching MATLAB."
+        },
+        {
+            "question": "What happens if the file was opened read-only?",
+            "answer": "`fprintf` raises `fprintf: file is not open for writing`. Ensure the permission string passed to `fopen` includes `'w'`, `'a'`, or `'+'`."
+        },
+        {
+            "question": "Which encodings are supported?",
+            "answer": "`fprintf` honours the encoding recorded by `fopen`. UTF-8 (default), ASCII, and Latin-1 are supported explicitly. Other labels fall back to UTF-8 behaviour."
+        },
+        {
+            "question": "How are multi-dimensional arrays handled?",
+            "answer": "Arguments are flattened in column-major order. The format string repeats until every element has been consumed, just like MATLAB."
+        },
+        {
+            "question": "Does `fprintf` flush the stream?",
+            "answer": "The builtin delegates to Rust's buffered writers. Files are flushed when closed; standard streams inherit the host buffering policy."
+        },
+        {
+            "question": "What if the format string contains no conversions?",
+            "answer": "Literal format strings are written once. Supplying additional arguments raises `fprintf: formatSpec contains no conversion specifiers but additional arguments were supplied`."
+        },
+        {
+            "question": "Are cell arrays supported?",
+            "answer": "Yes. Cell arrays containing supported scalar or text values are flattened in column-major order before formatting."
+        },
+        {
+            "question": "Can I mix numeric and text arguments?",
+            "answer": "Absolutely. Numeric, logical, and text inputs can be interleaved. Star width/precision arguments use the same flattened stream."
+        },
+        {
+            "question": "How do I suppress the return value?",
+            "answer": "Ignore it, just as in MATLAB. Omitting the output argument does not change the write behaviour."
+        }
+    ],
+    "links": [
+        {
+            "label": "sprintf",
+            "url": "./sprintf"
+        },
+        {
+            "label": "compose",
+            "url": "./compose"
+        },
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "fclose",
+            "url": "./fclose"
+        },
+        {
+            "label": "fwrite",
+            "url": "./fwrite"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "feof",
+            "url": "./feof"
+        },
+        {
+            "label": "fgets",
+            "url": "./fgets"
+        },
+        {
+            "label": "filewrite",
+            "url": "./filewrite"
+        },
+        {
+            "label": "fread",
+            "url": "./fread"
+        },
+        {
+            "label": "frewind",
+            "url": "./frewind"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/io/filetext/fprintf.rs",
+        "url": "crates/runmat-runtime/src/builtins/io/filetext/fprintf.rs"
+    },
+    "gpu_residency": "You can pass `gpuArray` inputs directly—`fprintf` gathers them back to host memory before formatting. No provider-specific hooks are required and outputs always reside on the CPU. This mirrors MATLAB, where explicit `gather` calls are unnecessary when writing to files or console streams.",
+    "gpu_behavior": [
+        "`fprintf` is a residency sink. Any argument containing `gpuArray` data is gathered via the active acceleration provider before formatting. No GPU kernels are launched. When no provider is registered, the builtin raises the same descriptive error used by other sinks (`gather: no acceleration provider registered`)."
+    ],
+    "key": "fprintf",
+    "slug": "fprintf",
+    "categoryPath": [
+        "io",
+        "filetext"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=fprintf.js.map

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

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

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

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

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

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