RunMat
GitHub

View all functions

CategoryIo: Filetext

What does the fprintf function do in MATLAB / RunMat?

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.

How does the fprintf function behave in MATLAB / RunMat?

  • 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.

fprintf Function GPU Execution Behaviour

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).

Examples of using the fprintf function in MATLAB / RunMat

Write Formatted Text To A File

[fid, msg] = fopen('report.txt', 'w');
assert(fid ~= -1, msg);
fprintf(fid, 'Total: %d (%.2f%%)\n', 42, 87.5);
fclose(fid);

Expected contents of report.txt:

Total: 42 (87.50%)

Use Standard Output Without An Explicit File Identifier

fprintf('Processing %s ...\n', datestr(now, 0));

Expected console output:

Processing 07-Jan-2025 23:14:55 ...

Write To Standard Error Using The Stream Name

fprintf('stderr', 'Warning: iteration limit reached (%d steps)\n', iter);

Expected console output (sent to stderr):

Warning: iteration limit reached (250 steps)

Format A Matrix In Column-Major Order

A = [1 2 3; 4 5 6];
fprintf('%d %d\n', A);

Expected console output:

1 4
2 5
3 6

Respect File Encoding Constraints

[fid, msg] = fopen('ascii.txt', 'w', 'native', 'ascii');
if fid == -1, error(msg); end
try
    fprintf(fid, 'café\n');
catch err
    disp(err.message);
end
fclose(fid);

Expected console output:

fprintf: character 'é' (U+00E9) cannot be encoded as ASCII

Format GPU-Resident Data Transparently

G = gpuArray([1.2 3.4 5.6]);
[fid, msg] = fopen('gpu.txt', 'w');
assert(fid ~= -1, msg);
fprintf(fid, '%.1f,', G);
fclose(fid);

Expected contents of gpu.txt:

1.2,3.4,5.6,

GPU residency in RunMat (Do I need gpuArray?)

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.

FAQ

Does fprintf return the number of characters or bytes?

It returns the number of bytes written. This may differ from the number of characters when using multi-byte encodings such as UTF-8.

Can I use 'stdout' or 'stderr' instead of numeric identifiers?

Yes. The strings 'stdout' and 'stderr' (any case) map to identifiers 1 and 2 respectively, matching MATLAB.

What happens if the file was opened read-only?

fprintf raises fprintf: file is not open for writing. Ensure the permission string passed to fopen includes 'w', 'a', or '+'.

Which encodings are supported?

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.

How are multi-dimensional arrays handled?

Arguments are flattened in column-major order. The format string repeats until every element has been consumed, just like MATLAB.

Does fprintf flush the stream?

The builtin delegates to Rust's buffered writers. Files are flushed when closed; standard streams inherit the host buffering policy.

What if the format string contains no conversions?

Literal format strings are written once. Supplying additional arguments raises fprintf: formatSpec contains no conversion specifiers but additional arguments were supplied.

Are cell arrays supported?

Yes. Cell arrays containing supported scalar or text values are flattened in column-major order before formatting.

Can I mix numeric and text arguments?

Absolutely. Numeric, logical, and text inputs can be interleaved. Star width/precision arguments use the same flattened stream.

How do I suppress the return value?

Ignore it, just as in MATLAB. Omitting the output argument does not change the write behaviour.

See Also

sprintf, compose, fopen, fclose, fwrite, fileread

Source & Feedback

  • Implementation: crates/runmat-runtime/src/builtins/io/filetext/fprintf.rs
  • Found a behavioural difference? Open an issue with a minimal reproduction.