Format data into multiple strings
collapse all in page
Syntax
str = compose(formatSpec,A)
str = compose(formatSpec,A1,...,AN)
str = compose(txt)
Description
str = compose(formatSpec,A)
formats data values from the input array, A
, using formatting operators specified by formatSpec
and returns the resulting text in str
. The compose
function formats values from A
in column order. If formatSpec
is a string array, then so is the output array str
. Otherwise, str
is a cell array of character vectors.
compose
also translates the escape-character sequences in formatSpec
. Escape-character sequences represent nonprinting characters or specify actions such as newlines or tabs.
The compose
function can return multiple pieces of formatted text as a string array or a cell array of character vectors, unlike sprintf
. The sprintf
function returns only a string scalar or a character vector.
If
A
has multiple rows, thencompose
returnsstr
as a string array or cell array with the same number of rows.compose
repeatsformatSpec
in each row ofstr
, with formatted values from the corresponding row ofA
.If the number of columns in
A
exceeds the number of operators informatSpec
, thencompose
repeatsformatSpec
as an additional column ofstr
. The extra columns ofA
contribute formatted values to the new column instr
.If the number of columns in
A
is less than the number of operators informatSpec
, thencompose
does not format values using those operators. Instead,compose
puts unchanged formatting operators instr
. However,compose
translates all escape-character sequences except for\\
and%%
.
example
str = compose(formatSpec,A1,...,AN)
formats data values from multiple input arrays and concatenates all the formatted values. When compose
uses formatting operators from formatSpec
to convert data from an input array, then those formatting operators become unavailable to the following input arrays.
For example, if formatSpec
is "%f %f %d %s"
and A1
has two columns, then the operators "%f %f"
are applied to the values in A1
only. They cannot be applied to A2
or any other input array. compose
applies the remaining operators, "%d %s"
, to A2,...,AN
.
If the number of columns in the last input array, AN
, exceeds the number of remaining operators, then compose
adds an additional column to str
, as described in the previous syntax. If the number of columns in AN
is less than the number of remaining operators, then compose
puts the last unchanged operators in str
.
str = compose(txt)
translates escape-character sequences in txt
.
If
txt
does not contain formatting operators, thencompose
translates all escape-character sequences. It leaves all other characters unchanged.If
txt
contains formatting operators, thencompose
translates all escape-character sequences except for\\
and%%
. It leaves all other characters, including the formatting operators, unchanged.
example
Examples
collapse all
Format Numbers into Strings
Open Live Script
Format pi
to eight decimal places and return it as a string.
A = pi
A = 3.1416
You can create strings using double quotes. Specify formatSpec
as a string.
formatSpec = "%.8f"
formatSpec = "%.8f"
str = "3.14159265"
Create a numeric array that contains values of pi
and e
. Use the %e
and %f
operators with different precisions.
A = [pi exp(1)]
A = 1×2 3.1416 2.7183
formatSpec = "The value of pi is %.2e; the value of e is %.5f.";str = compose(formatSpec,A)
str = "The value of pi is 3.14e+00; the value of e is 2.71828."
Format Columns of Values from Arrays
Open Live Script
Format values taken from numeric arrays. Since the numeric arrays have multiple rows, compose
returns a string array with the same number of rows.
X = [1 2 3 4 5]';Y = X.^2;
You can create strings using double quotes. Specify formatSpec
as a string and return the formatted values as a string array.
formatSpec = "%d.^2 = %d";str = compose(formatSpec,X,Y)
str = 5x1 string "1.^2 = 1" "2.^2 = 4" "3.^2 = 9" "4.^2 = 16" "5.^2 = 25"
Format Values with Extra or Missing Operators
Open Live Script
Format values when the number of columns in the data array is not equal to the number of operators. If A
has more columns, then compose
repeats formatSpec
as an additional column of the output string array.
You can create strings using double quotes. Specify formatSpec
as a string.
formatSpec = "The time is %d:%d";A = [8 15 9 30; 10 20 11 50];str = compose(formatSpec,A)
str = 2x2 string "The time is 8:15" "The time is 9:30" "The time is 10:20" "The time is 11:50"
Format values when A
has fewer columns.
formatSpec = "Check-in time %d:%d; Check-out time %d:%d";A = [12 27; 11 16];str = compose(formatSpec,A)
str = 2x1 string "Check-in time 12:27; Check-out time %d:%d" "Check-in time 11:16; Check-out time %d:%d"
Since A
has only two columns, compose
uses only the first two formatting operators in formatSpec
to format the values. compose
leaves the other formatting operators unchanged.
Escape Characters in String Array
Open Live Script
Create a string array that includes escape-character sequences to specify horizontal tabs. Use the compose
function to translate the \t
escape characters. You can create strings using double quotes.
str = ["Name\tDate of Birth\tLocation";... "Jones\t10/20/2015\tUK";... "Simpson\t09/12/2015\tUSA"];newStr = compose(str)
newStr = 3x1 string "Name->Date of Birth->Location" "Jones->10/20/2015->UK" "Simpson->09/12/2015->USA"
Prevent translation of \n
using another \
character.
str = "Don't escape the second\n\\n escaped-character sequence.";newStr = compose(str)
newStr = "Don't escape the second \n escaped-character sequence."
Input Arguments
collapse all
formatSpec
— Format of output fields
formatting operators
Format of the output fields, specified using formatting operators. formatSpec
also can include ordinary text and special characters.
If formatSpec
includes literal text representing escape characters, such as \n
, then compose
translates the escape characters.
formatSpec
can be an array of format specifiers contained within a character vector in single quotes, or a string scalar.
Formatting Operator
A formatting operator starts with a percent sign, %
, and ends with a conversion character. The conversion character is required. Optionally, you can specify flags, field width, precision, and subtype operators between %
and the conversion character.
Conversion Character
This table shows conversion characters to format numeric and character data as text.
Value Type | Conversion | Details |
---|---|---|
Integer, signed |
| Base 10 |
Integer, unsigned |
| Base 10 |
| Base 8 (octal) | |
| Base 16 (hexadecimal), lowercase letters | |
| Same as | |
Floating-point number |
| Fixed-point notation (Use a precision operator to specify the number of digits after the decimal point.) |
| Exponential notation, such as | |
| Same as | |
| The more compact of | |
| The more compact of | |
Characters or strings |
| Single character |
| Character vector or string array. The type of the output text is the same as the type of |
Optional Operators
The optional flags, field width, precision, and subtype operators further define the format of the output text.
Flags
'–'
Left-justify.
Example:%-5.2f
Example:%-10s
'+'
Always print a sign character (+ or –) for any numeric value.
Example:%+5.2f
Right-justify text.
Example:%+10s
' '
Insert a space before the value.
Example:% 5.2f
'0'
Pad to field width with zeros before the value.
Example:%05.2f
'#'
Modify selected numeric conversions:
For
%o
,%x
, or%X
, print0
,0x
, or0X
prefix.For
%f
,%e
, or%E
, print decimal point even when precision is 0.For
%g
or%G
, do not remove trailing zeros or decimal point.
Example:
%#5.0f
Field Width
Minimum number of characters to print.
Example:
'%5d'
printsintmax
as2147483647
because the value returned byintmax
exceeds the minimum number of characters to print.If the number of characters to print is less than the field width, then the
compose
function pads to the field width with spaces before the value unless otherwise specified by flags.However, the
num2str
function does not pad to the field width with spaces.Precision
Number of digits to print.
For
%f
,%e
, or%E
Number of digits to the right of the decimal point
Example:'%.4f'
printspi
as'3.1416'
For
%g
or%G
Number of significant digits
Example:'%.4g'
printspi
as'3.142'
Example:
'%6.4f'
printspi
as'3.1416'
.Note
If you specify a precision operator for floating-point values that exceeds the precision of the input numeric data type, the results might not match the input values to the precision you specified. The result depends on your computer hardware and operating system.
Subtypes
You can use a subtype operator to print a floating-point value as its octal, decimal, or hexadecimal value. The subtype operator immediately precedes the conversion character. This table shows the conversions that can use subtypes.
Input Value Type
Subtype and Conversion Character
Output Value Type
Floating-point number
%bx
or%bX
%bo
%bu
Double-precision hexadecimal, octal, or decimal value
Example:%bx
printspi
as400921fb54442d18
%tx
or%tX
%to
%tu
Single-precision hexadecimal, octal, or decimal value
Example:%tx
printspi
as40490fdb
Text Before or After Formatting Operators
formatSpec
can also include additional text before a percent sign, %
, or after a conversion character. The text can be:
Ordinary text to print.
Special characters that you cannot enter as ordinary text. This table shows how to represent special characters in
formatSpec
.Special Character
Representation
Single quotation mark
''
Percent character
%%
Backslash
\\
Alarm
\a
Backspace
\b
Form feed
\f
New line
\n
Carriage return
\r
Horizontal tab
\t
Vertical tab
\v
Character whose Unicode® numeric value can be represented by the hexadecimal number,
N
\xN
Example:
compose('\x5A')
returns'Z'
Character whose Unicode numeric value can be represented by the octal number,
N
\N
Example:
compose('\132')
returns'Z'
Notable Behavior of Conversions with Formatting Operators
Numeric conversions print only the real component of complex numbers.
If you specify a conversion that does not fit the data, such as a text conversion for a numeric value, MATLAB® overrides the specified conversion, and uses
%e
.Example:
'%s'
convertspi
to3.141593e+00
.If you apply a text conversion (either
%c
or%s
) to integer values, MATLAB converts values that correspond to valid character codes to characters.Example:
'%s'
converts[65 66 67]
toABC
.
A
— Numeric, character, or string array
scalar | vector | matrix | multidimensional array
Numeric, character, or string array, specified as scalar, vector, matrix, or multidimensional array.
Data Types: single
| double
| int8
| int16
| int32
| int64
| uint8
| uint16
| uint32
| uint64
| logical
| char
| string
txt
— Input text
string array | character vector | cell array of character vectors
Input text, specified as a string array, character vector, or cell array of character vectors. compose
translates any escape-character sequences in txt
. For example, compose
translates \n
into a newline character.
Data Types: string
| char
| cell
Output Arguments
collapse all
str
— Formatted text
string array | cell array of character vectors
Formatted text, returned as a string array or a cell array of character vectors.
Data Types: string
| cell
Extended Capabilities
Tall Arrays
Calculate with arrays that have more rows than fit in memory.
This function supports tall arrays with the limitation:
The format
input must be a non-tall string.
For more information, see Tall Arrays for Out-of-Memory Data.
Thread-Based Environment
Run code in the background using MATLAB® backgroundPool
or accelerate code with Parallel Computing Toolbox™ ThreadPool
.
This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.
Distributed Arrays
Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.
This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).
Version History
Introduced in R2016b
See Also
sprintf | string | sscanf | fprintf | fscanf
Topics
- Create String Arrays
- Formatting Text
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- Deutsch
- English
- Français
- United Kingdom (English)
Contact your local office