RunMat
GitHub

View all functions

CategoryStrings: Core
GPUYes

What does the compose function do in MATLAB / RunMat?

compose(formatSpec, A1, ..., An) substitutes data into MATLAB-compatible % placeholders and returns the result as a string array. It combines sprintf-style formatting with string-array broadcasting so you can generate multiple strings in one call.

How does the compose function behave in MATLAB / RunMat?

  • formatSpec must be text: a string scalar, string array, character vector, character array, or cell array of character vectors.
  • If formatSpec is scalar and any argument array has more than one element, RunMat broadcasts the scalar specification over the array dimensions.
  • When formatSpec is a string or character array with multiple elements, the output has the same shape as the specification. Each element uses the corresponding row or cell during formatting.
  • Arguments can be numeric, logical, string, or text-like cell arrays. Non-text arguments are converted using MATLAB-compatible rules (logical values become 1 or 0, complex numbers use the a + bi form).
  • When you omit additional arguments, compose(formatSpec) simply converts the specification into a string array, preserving the original structure.
  • Errors are raised if argument shapes are incompatible with the specification or if format specifiers are incomplete.

compose Function GPU Execution Behaviour

compose is a residency sink. When inputs include GPU-resident tensors, RunMat gathers the data back to host memory using the active acceleration provider before performing the formatting logic. All formatted strings live in host memory, so acceleration providers do not need compose-specific kernels.

Examples of using the compose function in MATLAB / RunMat

Formatting A Scalar Value Into A Sentence

msg = compose("The answer is %d.", 42);

Expected output:

msg = "The answer is 42."

Broadcasting A Scalar Format Spec Over A Vector

result = compose("Trial %d", 1:4);

Expected output:

result = 1×4 string
    "Trial 1"    "Trial 2"    "Trial 3"    "Trial 4"

Using A String Array Of Formats

spec = ["max: %0.2f", "min: %0.2f"];
values = compose(spec, [3.14159, 0.125]);

Expected output:

values = 1×2 string
    "max: 3.14"    "min: 0.12"

Formatting Each Row Of A Character Array

C = ['Row %02d'; 'Row %02d'; 'Row %02d'];
idx = compose(C, (1:3).');

Expected output:

idx = 3×1 string
    "Row 01"
    "Row 02"
    "Row 03"

Combining Real And Imaginary Parts

Z = [1+2i, 3-4i];
txt = compose("z = %s", Z);

Expected output:

txt = 1×2 string
    "z = 1+2i"    "z = 3-4i"

Using A Cell Array Of Format Specs

specs = {'%0.1f volts', '%0.1f amps'};
readings = compose(specs, {12.6, 3.4});

Expected output:

readings = 2×1 string
    "12.6 volts"
    "3.4 amps"

Formatting GPU-Resident Data

G = gpuArray([10 20 30]);
labels = compose("Value %d", G);

Expected output:

labels = 1×3 string
    "Value 10"    "Value 20"    "Value 30"

RunMat gathers G from the GPU before formatting, so the behaviour matches CPU inputs.

FAQ

What happens if the number of format arguments does not match the placeholders?

RunMat raises compose: format data arguments must be scalars or match formatSpec size. Ensure that each placeholder has a corresponding value or broadcast the specification appropriately.

Can compose handle complex numbers?

Yes. Complex numbers use MATLAB's canonical a + bi formatting, so %s specifiers receive the string form of the complex scalar.

How does compose treat logical inputs?

Logical values are converted to numeric 1 or 0 before formatting so they work with %d, %i, or %f placeholders.

Does compose modify the shape of the output?

No. The output matches the broadcasted size between formatSpec and the input arguments. Scalar specifications broadcast across non-scalar arguments.

What if I pass GPU arrays?

Inputs that reside on the GPU are automatically gathered to host memory before formatting. The resulting string array always lives on the CPU.

How do I emit literal percent signs?

Use %% inside formatSpec just like sprintf. The formatter converts %% into a single %.

Can I mix scalars and arrays in the arguments list?

Yes, as long as non-scalar arguments all share the same number of elements or match the size of formatSpec. Scalars broadcast across the target shape.

What happens when formatSpec is empty?

compose(formatSpec) returns an empty string array with the same shape as formatSpec. When formatSpec and arguments have zero elements, the output is 0×0.

See Also

string, sprintf, strcat, join