Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

compose

Convert data into formatted string array

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

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 instead of the string function. 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 = 

    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 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 instead of the string function. 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 array
    "1.^2 = 1"
    "2.^2 = 4"
    "3.^2 = 9"
    "4.^2 = 16"
    "5.^2 = 25"

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 instead of the string function. 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 array
    "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 array
    "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.

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 instead of the string function.

str = ["Name\tDate of Birth\tLocation";...
       "Jones\t10/20/2015\tUK";...
       "Simpson\t09/12/2015\tUSA"];
newStr = compose(str)
newStr = 3x1 string array
    "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

Formatting operators, specified as a string array, character vector, or cell array of character vectors containing formatting operators. If formatSpec includes literal text representing escape characters, such as \n, then compose translates the escape characters.

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. (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 af

%X

Same as %x, uppercase letters AF

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

%c

Single character

%s

Character vector

Optional Operators

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

  • Flags

    '–'

    Left-justify.
    Example: %-5.2f

    '+'

    Always print a sign character (+ or –) for any value.
    Example: %+5.2f

    ' '

    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: compose('%12d',intmax) returns " 2147483647".

    The function pads to field width with spaces before the value unless otherwise specified by flags.

  • 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: compose('%6.4f',pi) returns "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

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 character 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 string conversion (%s) to integer values, MATLAB converts values that correspond to valid character codes to characters.

    Example: '%s' converts [65 66 67] to "ABC".

Data Types: string | char | cell

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

Introduced in R2016b

Was this topic helpful?