compose

Format data into multiple strings

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, 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.

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

Format Numbers into Strings

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 = 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."

Format Columns of Values from Arrays

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

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

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

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	%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 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, 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: 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' 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.

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

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