RunMat
GitHub

View all functions

CategoryStrings: Core

What does the sprintf function do in MATLAB / RunMat?

sprintf(formatSpec, A1, ..., An) formats data into a character row vector. It honours MATLAB's printf-style placeholders, including flags (-, +, space, 0, #), field width, precision, and star (*) width/precision arguments. Arrays are processed column-major and the format string repeats automatically until every element has been consumed.

How does the sprintf function behave in MATLAB / RunMat?

  • formatSpec must be text: a character row vector or string scalar. Cell arrays and multi-row character arrays are rejected.
  • Arguments can be numeric, logical, strings, character arrays, or cell arrays containing supported scalar types. Numeric inputs accept scalar, vector, or matrix shapes; elements are flattened in column-major order.
  • Escape sequences such as \n, \t, \r, \f, \b, \a, \v, octal (\123), and hexadecimal (\x7F) are interpreted before formatting so that sprintf can build multi-line text easily.
  • Width and precision may be literal digits or drawn from the input list using * or .*. Star arguments must be scalar numerics and are consumed in order.
  • Flags match MATLAB behaviour: - left-aligns, + forces a sign, space reserves a leading space for positive numbers, 0 enables zero padding, and # produces alternate forms for octal, hexadecimal, and binary outputs or preserves the decimal point in fixed-point conversions.
  • %% emits a literal percent character without consuming arguments.
  • Complex inputs are formatted as scalar text (a+bi) when used with %s; numeric conversions expect real scalars.
  • Additional arguments beyond those required by the repeating format string raise an error to match MATLAB diagnostics.

sprintf Function GPU Execution Behaviour

sprintf is a residency sink. When inputs include GPU tensors, RunMat gathers them back to host memory via the active acceleration provider before executing the formatter. Formatting itself runs entirely on the CPU, ensuring consistent behaviour regardless of device availability.

Examples of using the sprintf function in MATLAB / RunMat

Formatting A Scalar Value

txt = sprintf('Value: %d', 42);

Expected output:

txt =
    'Value: 42'

Formatting With Precision And Width

txt = sprintf('pi ~= %8.4f', pi);

Expected output:

txt =
    'pi ~=   3.1416'

Combining Strings And Numbers

label = sprintf('Trial %02d: %.1f%% complete', 7, 84.95);

Expected output:

label =
    'Trial 07: 85.0% complete'

Formatting Vector Inputs

data = [10 20 30];
txt = sprintf('%d ', data);

Expected output:

txt =
    '10 20 30 '

Using Star Width/Precision Arguments

txt = sprintf('%*.*f %*.*f', 4, 2, 15.2, 6, 4, 0.001);

Expected output:

txt =
    '15.20  0.0010'

Quoting Text With %s

names = ["Ada", "Grace"];
txt = sprintf('Hello, %s! ', names);

Expected output:

txt =
    'Hello, Ada! Hello, Grace! '

Formatting GPU-Resident Data

G = gpuArray([1.5 2.5 3.5]);
txt = sprintf('%.1f;', G);

Expected output:

txt =
    '1.5;2.5;3.5;'

RunMat gathers G to host memory automatically before formatting so the behaviour matches CPU inputs.

Creating Multi-line Text

message = sprintf('First line\\nSecond line\\t(indented)');

Expected output (showing control characters):

message =
    'First line
Second line	(indented)'

FAQ

What happens if there are not enough input values for the format specifiers?

RunMat raises sprintf: not enough input arguments for format specifier as soon as a placeholder cannot be satisfied. This matches MATLAB's error message.

How are additional values treated when the format string contains fewer specifiers?

The format string repeats until all array elements are consumed. If the format string consumes no arguments (for example, it contains only literal text) and extra values remain, RunMat raises an error because MATLAB would also treat this as a mismatch.

Can I use star (*) width or precision arguments with arrays?

Yes. Each * consumes the next scalar value from the input stream. When you provide arrays for width or precision, elements are read in column-major order the same way data arguments are.

Does sprintf support complex numbers?

Complex values can be formatted with %s, which renders MATLAB's canonical a+bi text. Numeric conversions require real-valued inputs and raise an error for complex scalars.

Are logical values supported?

Yes. Logical inputs are promoted to numeric (1 or 0) before formatting, so you can combine them with integer or floating-point conversions.

Does sprintf allocate string scalars?

No. sprintf always returns a character row vector for MATLAB compatibility. Use string or compose if you need string scalars or string arrays.

Does GPU hardware change formatting behaviour?

No. Formatting occurs on the CPU. When GPU tensors appear in the input list, RunMat gathers them to host memory before substitution so the results match MATLAB exactly.

How do I emit a literal percent sign?

Use %% inside the format specification. The formatter converts %% into a single % without consuming an argument.

How are empty inputs handled?

If all argument arrays are empty, sprintf returns an empty character array (1×0). If the format string itself is empty, the result is also empty.

What happens with multi-row character arrays?

MATLAB requires formatSpec to be a row vector. RunMat follows the same rule: multi-row character arrays raise sprintf: formatSpec must be a character row vector or string scalar.

See Also

compose, string, num2str, strlength