`compose` — Format values into string arrays using printf-style placeholders in MATLAB and RunMat.

compose(formatSpec, A1, ..., An) substitutes data into % placeholders. A string format specification returns a string array and a character format specification returns a cell array of character vectors. Integer arguments are read from exact native storage, including int64 and uint64 values above flintmax.

Syntax

S = compose(formatSpec)
S = compose(formatSpec, A...)

Inputs

Name	Type	Required	Default	Description
`formatSpec`	`Any`	Yes	—	Format text or array returned in the corresponding string or cellstr family when no data arguments are supplied.
`formatSpec`	`Any`	Yes	—	Format template text.
`A...`	`Any`	Variadic	—	Values substituted into formatSpec placeholders.

Returns

Name	Type	Description
`S`	`Any`	Formatted string array or cell array of character vectors, selected by formatSpec.

Errors

Identifier	When	Message
`RunMat:compose:InvalidFormatSpec`	formatSpec is not valid text input for compose formatting.	`compose: invalid formatSpec`
`RunMat:compose:ArgumentMismatch`	Data arguments are not scalar or broadcast-compatible with formatSpec.	`compose: format data arguments must be scalars or match formatSpec size`
`RunMat:compose:InternalError`	Internal string-array construction failed.	`compose: internal error`
`RunMat:compose:InvalidData`	A data argument is outside compose's documented numeric, logical, character, or string domain.	`compose: unsupported data argument`

How `compose` works

formatSpec must be a string or character format for substitution. A cell array of character vectors is supported only by unary compose(formatSpec), which converts it to cellstr output.
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 character data. Cell-array data arguments are rejected because they are outside the documented domain. All eight integer classes are formatted directly from native values, so %d and %i preserve exact decimal text above flintmax.
Resident arguments are a RunMat-only extension because MATLAB does not document GPU-array support for compose. RunMat mode gathers them through the owning provider before formatting and returns host text in the class selected by formatSpec.
When you omit additional arguments, string formatSpec returns a string array, while character and cellstr formatSpec return a cell array of character vectors.
General nonscalar row-wise formatting geometry remains a known gap: scalar expansion and equal-element-count forms are covered, but every higher-dimensional MATLAB format cycling case has not yet been modeled.
Errors are raised if argument shapes are incompatible with the specification or if format specifiers are incomplete.

Does RunMat run `compose` on the GPU?

compose is a residency sink. In RunMat mode, resident tensors gather through their owning provider before formatting. All formatted text lives in host memory, so providers do not need compose-specific kernels.

Examples

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"

Using A Character Format Vector

idx = compose('Row %02d', (1:3).')

Expected output:

idx = 3×1 cell
    {'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"

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"

Using `compose` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how compose changes the result.

Run a small compose example, explain the result, then change one input and compare the output.

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?⌄

In RunMat mode, resident inputs are gathered before formatting and the text result lives on the host. Compatibility mode rejects this explicitly classified extension.

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?⌄

An empty string formatSpec returns an empty string array. Empty character or cellstr formatSpec returns empty cellstr-compatible output with the corresponding shape.

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how compose is executed, line by line, in Rust.

View the source for compose in Rust on GitHub
Learn how the RunMat runtime works
Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

`compose` — Format values into string arrays using printf-style placeholders in MATLAB and RunMat.

Syntax

S = compose(formatSpec)
S = compose(formatSpec, A...)

Inputs

Name	Type	Required	Default	Description
`formatSpec`	`Any`	Yes	—	Format text or array returned in the corresponding string or cellstr family when no data arguments are supplied.
`formatSpec`	`Any`	Yes	—	Format template text.
`A...`	`Any`	Variadic	—	Values substituted into formatSpec placeholders.

Returns

Name	Type	Description
`S`	`Any`	Formatted string array or cell array of character vectors, selected by formatSpec.

Errors

Identifier	When	Message
`RunMat:compose:InvalidFormatSpec`	formatSpec is not valid text input for compose formatting.	`compose: invalid formatSpec`
`RunMat:compose:ArgumentMismatch`	Data arguments are not scalar or broadcast-compatible with formatSpec.	`compose: format data arguments must be scalars or match formatSpec size`
`RunMat:compose:InternalError`	Internal string-array construction failed.	`compose: internal error`
`RunMat:compose:InvalidData`	A data argument is outside compose's documented numeric, logical, character, or string domain.	`compose: unsupported data argument`

How `compose` works

formatSpec must be a string or character format for substitution. A cell array of character vectors is supported only by unary compose(formatSpec), which converts it to cellstr output.
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 character data. Cell-array data arguments are rejected because they are outside the documented domain. All eight integer classes are formatted directly from native values, so %d and %i preserve exact decimal text above flintmax.
Resident arguments are a RunMat-only extension because MATLAB does not document GPU-array support for compose. RunMat mode gathers them through the owning provider before formatting and returns host text in the class selected by formatSpec.
When you omit additional arguments, string formatSpec returns a string array, while character and cellstr formatSpec return a cell array of character vectors.
General nonscalar row-wise formatting geometry remains a known gap: scalar expansion and equal-element-count forms are covered, but every higher-dimensional MATLAB format cycling case has not yet been modeled.
Errors are raised if argument shapes are incompatible with the specification or if format specifiers are incomplete.

Does RunMat run `compose` on the GPU?

Examples

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"

Using A Character Format Vector

idx = compose('Row %02d', (1:3).')

Expected output:

idx = 3×1 cell
    {'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"

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"

Using `compose` with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how compose changes the result.

Run a small compose example, explain the result, then change one input and compare the output.

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?⌄

In RunMat mode, resident inputs are gathered before formatting and the text result lives on the host. Compatibility mode rejects this explicitly classified extension.

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?⌄

An empty string formatSpec returns an empty string array. Empty character or cellstr formatSpec returns empty cellstr-compatible output with the corresponding shape.

Core

Text Analytics

Transform

Search

contains · endsWith · matches · startsWith · strfind

Pattern

digitsPattern · lettersPattern · pattern · regexpPattern · textBoundary · wildcardPattern

Regex

regexp · regexpi · regexprep

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how compose is executed, line by line, in Rust.

View the source for compose in Rust on GitHub
Learn how the RunMat runtime works
Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing

compose — Format values into string arrays using printf-style placeholders in MATLAB and RunMat.

Syntax

Inputs

Returns

Errors

How compose works

Does RunMat run compose on the GPU?

Examples

Formatting A Scalar Value Into A Sentence

Broadcasting A Scalar Format Spec Over A Vector

Using A String Array Of Formats

Using A Character Format Vector

Combining Real And Imaginary Parts

Formatting GPU-Resident Data

Using compose with coding agents

FAQ

Related Strings functions

Core

Text Analytics

Transform

Search

Pattern

Regex

Open-source implementation

About RunMat

Download RunMat

compose — Format values into string arrays using printf-style placeholders in MATLAB and RunMat.

Syntax

Inputs

Returns

Errors

How compose works

Does RunMat run compose on the GPU?

Examples

Formatting A Scalar Value Into A Sentence

Broadcasting A Scalar Format Spec Over A Vector

Using A String Array Of Formats

Using A Character Format Vector

Combining Real And Imaginary Parts

Formatting GPU-Resident Data

Using compose with coding agents

FAQ

Related Strings functions

Core

Text Analytics

Transform

Search

Pattern

Regex

Open-source implementation

About RunMat

Download RunMat

`compose` — Format values into string arrays using printf-style placeholders in MATLAB and RunMat.

How `compose` works

Does RunMat run `compose` on the GPU?

Using `compose` with coding agents

`compose` — Format values into string arrays using printf-style placeholders in MATLAB and RunMat.

How `compose` works

Does RunMat run `compose` on the GPU?

Using `compose` with coding agents