MATLAB Function Reference

sprintf

Write formatted data to string

Syntax

• [s, errmsg] = sprintf(format, A, ...)
  

Description

[s, errmsg] = sprintf(format, A, ...) formats the data in matrix A (and in any additional matrix arguments) under control of the specified format string and returns it in the MATLAB string variable s. The sprintf function returns an error message string errmsg if an error occurred. errmsg is an empty matrix if no error occurred.

sprintf is the same as fprintf except that it returns the data in a MATLAB string variable rather than writing it to a file.

Format String

The format argument is a string containing C language conversion specifications. A conversion specification controls the notation, alignment, significant digits, field width, and other aspects of output format. The format string can contain escape characters to represent nonprinting characters such as newline characters and tabs.

Conversion specifications begin with the % character and contain these optional and required elements:

• Flags (optional)
• Width and precision fields (optional)
• A subtype specifier (optional)
• Conversion character (required)

You specify these elements in the following order:

Flags

You can control the alignment of the output using any of these optional flags.

Character	Description	Example
A minus sign (-)	Left-justifies the converted argument in its field	%-5.2d
A plus sign (+)	Always prints a sign character (+ or -)	%+5.2d
Zero (0)	Pad with zeros rather than spaces.	%05.2d

Field Width and Precision Specifications

You can control the width and precision of the output by including these options in the format string.

Character	Description	Example
Field width	A digit string specifying the minimum number of digits to be printed.	%6f
Precision	A digit string including a period (.) specifying the number of digits to be printed to the right of the decimal point	%6.2f

Conversion Characters

Conversion characters specify the notation of the output.

Specifier	Description
%c	Single character
%d	Decimal notation (signed)
%e	Exponential notation (using a lowercase e as in 3.1415e+00)
%E	Exponential notation (using an uppercase E as in 3.1415E+00)
%f	Fixed-point notation
%g	The more compact of %e or %f, as defined in [2]. Insignificant zeros do not print.
%G	Same as %g, but using an uppercase E
%o	Octal notation (unsigned)
%s	String of characters
%u	Decimal notation (unsigned)
%x	Hexadecimal notation (using lowercase letters a-f)
%X	Hexadecimal notation (using uppercase letters A-F)

The following tables describe the nonalphanumeric characters found in format specification strings.

Escape Characters

This table lists the escape character sequences you use to specify non-printing characters in a format specification.

Character	Description
\b	Backspace
\f	Form feed
\n	New line
\r	Carriage return
\t	Horizontal tab
\\	Backslash
\'' or '' (two single quotes)	Single quotation mark
%%	Percent character

Remarks

The sprintf function behaves like its ANSI C language namesake with these exceptions and extensions.

• If you use sprintf to convert a MATLAB double into an integer, and the double contains a value that cannot be represented as an integer (for example, it contains a fraction), MATLAB ignores the specified conversion and outputs the value in exponential format. To successfully perform this conversion, use the fix, floor, ceil, or round functions to change the value in the double into a value that can be represented as an integer before passing it to sprintf.
• The following nonstandard subtype specifiers are supported for the conversion characters %o, %u, %x, and %X.
  
  

  b	The underlying C data type is a double rather than an unsigned integer. For example, to print a double-precision value in hexadecimal, use a format like '%bx'.
  t	The underlying C data type is a float rather than an unsigned integer.

• For example, to print a double value in hexadecimal use the format '%bx'.

• The sprintf function is vectorized for nonscalar arguments. The function recycles the format string through the elements of A (columnwise) until all the elements are used up. The function then continues in a similar manner through any additional matrix arguments.
• If %s is used to print part of a nonscalar double argument, the following behavior occurs:
1. Successive values are printed as long as they are integers and in the range of a valid character. The first invalid character terminates the printing for this %s specifier and is used for a later specifier. For example, pi terminates the string below and is printed using %f format.

   •    Str = [65 66 67 pi];
        sprintf('%s %f', Str)
        ans =
        ABC 3.141593
     

2. If the first value to print is not a valid character, then just that value is printed for this %s specifier using an e conversion as a warning to the user. For example, pi is formatted by %s below in exponential notation, and 65, though representing a valid character, is formatted as fixed-point (%f).

   •    Str = [pi 65 66 67];
        sprintf('%s %f %s', Str)
        ans =
        3.141593e+000 65.000000 BC
     

3. One exception is zero, which is a valid character. If zero is found first, %s prints nothing and the value is skipped. If zero is found after at least one valid character, it terminates the printing for this %s specifier and is used for a later specifier.
• sprintf prints negative zero and exponents differently on some platforms, as shown in the following tables.
  
  

  Negative Zero Printed with %e, %E, %f, %g, or %G

  	Display of Negative Zero
  Platform	%e or %E	%f	%g or %G
  PC	0.000000e+000	0.000000	0
  Others	-0.000000e+00	-0.000000	-0

  
  
  

  Exponents Printed with %e, %E, %g, or %G

  Platform	Minimum Digits in Exponent	Example
  PC	3	1.23e+004
  UNIX	2	1.23e+04

You can resolve this difference in exponents by postprocessing the results of sprintf. For example, to make the PC output look like that of UNIX, use

• a = sprintf('%e', 12345.678);
  if ispc, a = strrep(a, 'e+0', 'e+');   end
  

Examples

Command	Result
sprintf('%0.5g',(1+sqrt(5))/2)	1.618
sprintf('%0.5g',1/eps)	4.5036e+15
sprintf('%15.5f',1/eps)	4503599627370496.00000
sprintf('%d',round(pi))	3
sprintf('%s','hello')	hello
sprintf('The array is %dx%d.',2,3)	The array is 2x3
sprintf('\n')	Line termination character on all platforms

See Also

int2str, num2str, sscanf

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.

sprank

spy

© 1994-2005 The MathWorks, Inc.