compose - Format data into multiple strings - MATLAB (original) (raw)

Format data into multiple strings

Syntax

Description

[str](#bu6eywi-str) = compose([formatSpec](#mw%5Fd65b86bf-791c-4d1e-bf9d-c43110c16a96),[A](#bu6eywi-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 informatSpec. 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, unlikesprintf. 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 repeatsformatSpec in each row of str, with formatted values from the corresponding row ofA.
• If the number of columns in A exceeds the number of operators in formatSpec, then compose repeats formatSpec as an additional column ofstr. The extra columns of A contribute formatted values to the new column instr.
• If the number of columns in A is less than the number of operators in formatSpec, 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](#bu6eywi-str) = compose([formatSpec](#mw%5Fd65b86bf-791c-4d1e-bf9d-c43110c16a96),A1,...,AN) formats data values from multiple input arrays and concatenates all the formatted values. When compose uses formatting operators fromformatSpec 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 instr.

[str](#bu6eywi-str) = compose([txt](#bu6eywi-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 pi to eight decimal places and return it as a string.

You can create strings using double quotes. Specify formatSpec as a string.

str = compose(formatSpec,A)

Create a numeric array that contains values of pi and e. Use the %e and %f operators with different precisions.

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;

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 = 5×1 string "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.

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 = 2×2 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 = 2×1 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.

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 = 3×1 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, thencompose 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.

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.2fRight-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 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' 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 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 informatSpec.

  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	\xNExample: compose('\x5A') returns'Z'
  Character whose Unicode numeric value can be represented by the octal number,N	\NExample: 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 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] 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

Version History

Introduced in R2016b