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
formatSpec- Type
Any- Required
- Yes
- Description
- Format text or array returned in the corresponding string or cellstr family when no data arguments are supplied.
formatSpec- Type
Any- Required
- Yes
- Description
- Format template text.
A...- Type
Any- Required
- Variadic
- Description
- Values substituted into formatSpec placeholders.
Returns
S- Type
Any- Description
- Formatted string array or cell array of character vectors, selected by formatSpec.
Errors
RunMat:compose:InvalidFormatSpec- When
- formatSpec is not valid text input for compose formatting.
- Message
compose: invalid formatSpec
RunMat:compose:ArgumentMismatch- When
- Data arguments are not scalar or broadcast-compatible with formatSpec.
- Message
compose: format data arguments must be scalars or match formatSpec size
RunMat:compose:InternalError- When
- Internal string-array construction failed.
- Message
compose: internal error
Behavior
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.
Execution and placement
Formatting runs on the CPU. Resident inputs are a mode-gated RunMat extension and gather through the owning provider before substitution. A string format specification returns a host string array, while a character format specification returns a host cell array of character vectors.
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.
Related Strings functions
Core
blanks · char · convertCharsToStrings · convertContainedStringsToChars · convertStringsToChars · genvarname · int2str · isletter · isspace · isStringScalar · isstrprop · mat2str · native2unicode · newline · num2str · sprintf · sscanf · str2double · str2num · strcmp · strcmpi · string · string.empty · strings · strlength · strncmp · strncmpi · strtok · unicode2native
Text Analytics
addDependencyDetails · addEntityDetails · addLemmaDetails · addPartOfSpeechDetails · addSentenceDetails · addTypeDetails · bagOfNgrams · bagOfWords · cosineSimilarity · doc2sequence · encode · extractFileText · extractHTMLText · fastTextWordEmbedding · findElement · getAttribute · htmlTree · ind2word · isVocabularyWord · normalizeWords · readWordEmbedding · removeLongWords · removeShortWords · removeStopWords · removeWords · stopWords · tokenDetails · tokenizedDocument · trainWordEmbedding · vaderSentimentScores · vec2word · word2ind · word2vec · wordEncoding · writeWordEmbedding
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · join · lower · pad · replace · replaceBetween · reverse · split · splitlines · strcat · strip · strjoin · strjust · strrep · strsplit · strtrim · upper
Search
contains · endsWith · matches · startsWith · strfind
Pattern
digitsPattern · lettersPattern · pattern · regexpPattern · textBoundary · wildcardPattern
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.