compose

Format data into multiple strings

collapse all in page

Syntax

str = compose(formatSpec,A)
str = compose(formatSpec,A1,...,AN)
str = compose(txt)

Description

example

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, then compose returns str as a string array or cell array with the same number of rows. compose repeats formatSpec in each row of str, with formatted values from the corresponding row of A.

  • If the number of columns in A exceeds the number of operators in formatSpec, then compose repeats formatSpec as an additional column of str. The extra columns of A contribute formatted values to the new column in str.

  • If the number of columns in A is less than the number of operators in formatSpec, then compose does not format values using those operators. Instead, compose puts unchanged formatting operators in str. However, compose translates all escape-character sequences except for \\ and %%.

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.

example

str = compose(txt) translates escape-character sequences in txt.

  • If txt does not contain formatting operators, then compose translates all escape-character sequences. It leaves all other characters unchanged.

  • If txt contains formatting operators, then compose translates all escape-character sequences except for \\ and %%. It leaves all other characters, including the formatting operators, unchanged.

Examples

collapse all

Open Live Script

Format pi to eight decimal places and return it as a string.

A = pi
A = 3.1416

Starting in R2017a, you can create strings using double quotes. Specify formatSpec as a string.

formatSpec = "%.8f"
formatSpec = 
"%.8f"

str = compose(formatSpec,A)
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."
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;

Starting in R2017a, 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"
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.

Starting in R2017a, 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.

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. Starting in R2017a, 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

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 a character vector in single quotes, or, starting in R2016b, 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 identifier, flags, field width, precision, and subtype operators between % and the conversion character. (Spaces are invalid between operators and are shown here only for readability).

Conversion Character

This table shows conversion characters to format numeric and character data as text.

Value TypeConversionDetails

Integer, signed

%d or %i

Base 10

Integer, unsigned

%u

Base 10

%o

Base 8 (octal)

%x

Base 16 (hexadecimal), lowercase letters a–f

%X

Same as %x, uppercase letters A–F

Floating-point number

%f

Fixed-point notation (Use a precision operator to specify the number of digits after the decimal point.)

%e

Exponential notation, such as 3.141593e+00 (Use a precision operator to specify the number of digits after the decimal point.)

%E

Same as %e, but uppercase, such as 3.141593E+00 (Use a precision operator to specify the number of digits after the decimal point.)

%g

The more compact of %e or %f, with no trailing zeros (Use a precision operator to specify the number of significant digits.)

%G

The more compact of %E or %f, with no trailing zeros (Use a precision operator to specify the number of significant digits.)

Characters or strings

%c

Single character

%s

Character vector or string array. The type of the output text is the same as the type of formatSpec.

Optional Operators

The optional identifier, flags, field width, precision, and subtype operators further define the format of the output text.

  • Identifier

    Note: Unlike the sprintf function, compose does not support identifiers.

  • 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, print 0, 0x, or 0X 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' prints intmax as 2147483647 because the value returned by intmax 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' prints pi as '3.1416'

    For %g or %G

    Number of significant digits
    Example: '%.4g' prints pi as '3.142'

    Example: '%6.4f' prints pi 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 prints pi as 400921fb54442d18

    %tx or %tX
    %to
    %tu

    Single-precision hexadecimal, octal, or decimal value
    Example: %tx prints pi as 40490fdb

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: sprintf('\x5A') returns 'Z'

    Character whose Unicode numeric value can be represented by the octal number, N

    \N

    Example: sprintf('\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' converts pi to 3.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] to ABC.

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

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

Formatted text, returned as a string array or a cell array of character vectors.

Data Types: string | cell

Extended Capabilities

See Also

| | | |

Topics

Introduced in R2016b

MATLAB Documentation

Support