sprintf

Format data into string or character vector

collapse all in page

Syntax

str = sprintf(formatSpec,A1,...,An)
[str,errmsg] = sprintf(formatSpec,A1,...,An)
str = sprintf(literalText)

Description

str = sprintf(formatSpec,A1,...,An) formats the data in arrays A1,...,An using the formatting operators specified by formatSpec and returns the resulting text in str. The sprintf function formats the values in A1,...,An in column order. If formatSpec is a string, then so is the output str. Otherwise, str is a character vector.

To return multiple pieces of formatted text as a string array or a cell array of character vectors, use the compose function.

example

[str,errmsg] = sprintf(formatSpec,A1,...,An) returns an error message as a character vector when the operation is unsuccessful. Otherwise, errmsg is empty.

str = sprintf(literalText) translates escape-character sequences in literalText, such as \n and \t. It returns all other characters unaltered. If literalText contain a formatting operator (such as %f), then str discards it and all characters after.

Examples

collapse all

Open Live Script

Format a floating-point number using %e, %f, and %g specifiers. 

A = 1/eps;
str_e = sprintf('%0.5e',A)
str_e = 
'4.50360e+15'

str_f = sprintf('%0.5f',A)
str_f = 
'4503599627370496.00000'

str_g = sprintf('%0.5g',A)
str_g = 
'4.5036e+15'
Open Live Script

Combine literal text with array values to create a character vector. 

formatSpec = 'The array is %dx%d.';
A1 = 2;
A2 = 3;
str = sprintf(formatSpec,A1,A2)
str = 
'The array is 2x3.'
Open Live Script

To return formatted text as a string, specify formatSpec as a string instead of a character vector when you call the sprintf function.

Convert data and return the result as a string.

formatSpec = "The current time is: %d:%d %s";
A1 = 11;
A2 = 20;
A3 = 'a.m.';
str = sprintf(formatSpec,A1,A2,A3)
str = 
"The current time is: 11:20 a.m."

Convert input string. Input arrays that contain text either can be character vectors or strings.

A1 = 2;
A2 = 35;
A3 = "p.m.";
str = sprintf(formatSpec,A1,A2,A3)
str = 
"The current time is: 2:35 p.m."
Open Live Script

Explicitly convert double-precision values to integers. 

str = sprintf('%d',round(pi))
str = 
'3'
Open Live Script

Specify the minimum width of the printed value. 

str = sprintf('%025d',123456)
str = 
'0000000000000000000123456'

The 0 flag in the %025d format specifier requests leading zeros in the output.

Open Live Script

Reorder the input values using the n$ position identifier. 

A1 = 'X';
A2 = 'Y';
A3 = 'Z';
formatSpec = ' %3$s %2$s %1$s';
str = sprintf(formatSpec,A1,A2,A3)
str = 
' Z Y X'
Open Live Script
C = { 1,   2,   3 ;
     'AA','BB','CC'};

str = sprintf(' %d %s',C{:})
str = 
' 1 AA 2 BB 3 CC'

The syntax C{:} creates a comma-separated list of arrays that contain the contents of each cell from C in column order. For example, C{1}==1 and C{2}=='AA'.

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 sprintf translates the escape characters.

formatSpec can be 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 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).

Schematic of formatting operator characters.

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

    Order for processing the function input arguments. Use the syntax n$, where n represents the positions of the other input arguments in the function call.

    Example: ('%3$s %2$s %1$s %2$s','A','B','C') prints input arguments 'A', 'B', 'C' as follows: C B A B.

    Note: If an input argument is an array, you cannot use identifiers to specify particular array elements from that input argument.

  • 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. The field width operator can be a number, or an asterisk (*) to refer to an input argument.

    When you specify * as the field width operator, the other input arguments must provide both a width and a value to be printed. Widths and values can be pairs of arguments or pairs within a numeric array. With * as the field width operator, you can print different values with different widths.

    Example: The input arguments ('%12d',intmax) are equivalent to ('%*d',12,intmax).

    Example: The input arguments ('%*d',[2 10 5 100]) return '10 100', with two spaces allocated for 10 and five spaces for 100. As an alternative, you also can specify the field widths and values as multiple arguments, as in ('%*d',2,10,5,100).

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

  • Precision

    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'

    The precision operator can be a number, or an asterisk (*) to refer to an argument.

    When you specify * as the field precision operator, the other input arguments must provide both a precision and a value to be printed. Precisions and values can be pairs of arguments, or pairs within a numeric array. With * as the precision operator, you can print different values to different precisions.

    When you specify *.* as field width and precision operators, you must specify field widths, precisions, and values as triplets.

    Example: The input arguments ('%.4f',pi) are equivalent to ('%.*f',4,pi).

    Example: The input arguments ('%6.4f',pi) are equivalent to ('%*.*f',6,4,pi).

    Example: The input arguments ('%*.*f',6,4,pi,9,6,exp(1)) return '3.1416 2.718282', with 9 and 6 as the field width and precision for the output of exp(1).

    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

  • 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 arrays.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string

Input text without formatting operators, specified as a character vector or string scalar. sprintf translates any escape-character sequences in literalText.

Data Types: char | string

Output Arguments

collapse all

Formatted text, returned as a character vector or a string scalar. The type of output matches the type of formatSpec.

Error message, returned as a character vector, when the operation is unsuccessful. Otherwise, errmsg is empty.

Tips

  • The sprintf function is similar to fprintf, but fprintf prints to a file or to the Command Window.

  • Format specifiers for the reading functions sscanf and fscanf differ from the formats for the writing functions sprintf and fprintf. The reading functions do not support a precision field. The width field specifies a minimum for writing, but a maximum for reading.

  • If you specify an invalid formatting operator or special character, then sprintf prints all text up to the invalid operator or character and discards the rest.

    Example: If formatSpec is 'value = %z', then sprintf prints 'value =' because %z is not a formatting operator.

    Example: If formatSpec is 'character \x99999 = %s', then sprintf prints 'character' because \x99999 is not a valid special character.

References

[1] Kernighan, B. W., and D. M. Ritchie, The C Programming Language, Second Edition, Prentice-Hall, Inc., 1988.

[2] ANSI specification X3.159-1989: “Programming Language C,” ANSI, 1430 Broadway, New York, NY 10018.

Extended Capabilities

expand all

Version History

Introduced before R2006a

See Also

| | | | | | |

Topics