Documentation

sprintf

Format data into string

Syntax

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

Description

example

str = sprintf(formatSpec,A1,...,An) formats the data in arrays A1,...,An according to formatSpec in column order, and returns the results to string str.

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

Examples

collapse all

Floating-Point Formats

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

A = 1/eps;
str_e = sprintf('%0.5e',A)
str_f = sprintf('%0.5f',A)
str_g = sprintf('%0.5g',A)
str_e =

4.50360e+15


str_f =

4503599627370496.00000


str_g =

4.5036e+15

Literal Text and Array Inputs

Combine literal text with array values to create a string.

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

The array is 2x3.

Integer Format with Floating-Point Inputs

Explicitly convert double-precision values to integers.

str = sprintf('%d',round(pi))
str =

3

Specify Field Width of a Printed Value

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.

Reorder Inputs Using Position Identifier (n$)

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

Create a String from Values in Cell Array

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

formatSpec — Format of output fieldsstring containing formatting operators

Format of the output fields, specified as a string containing formatting operators. formatSpec also can include ordinary text and special 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 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 strings.

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

String of characters

Optional Operators

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

  • Identifier

    Order for processing values from the input list. Use the syntax n$, where n represents the position of the value in the input list.

    Example: '%3$s %2$s %1$s %2$s' prints inputs 'A', 'B', 'C' as follows: C B A B.

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

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

    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 in the input list.

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

      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

    Certain conversion characters can support a subtype. 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

    Integer

    %ld or %li
    %lo
    %lu
    %lx or %lX

    64-bit value

    Integer

    %hd or %hi
    %ho
    %hu
    %hx or %hX

    16-bit value

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 ASCII code is the hexadecimal number, N

    \xN

    Character whose ASCII code is the octal number, N

    \N

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

A1,...,An — Numeric or character arraysscalar | vector | matrix | multidimensional array

Numeric or character arrays, specified as a scalar, vector, matrix, or multidimensional array.

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

Output Arguments

collapse all

str — Formatted textstring

Formatted text, returned as a string.

errmsg — Error messagestring

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

More About

collapse all

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.

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.

See Also

| | | | |

Introduced before R2006a

Was this topic helpful?