sprintf

将数据格式化为字符串或字符向量

语法

str = sprintf(formatSpec,A1,...,An)

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

str = sprintf(literalText)

说明

str = sprintf(formatSpec,A1,...,An) 使用 formatSpec 指定的格式化操作符格式化数组 A1,...,An 中的数据，并在 str 中返回结果文本。sprintf 函数按列顺序格式化 A1,...,An 中的值。如果 formatSpec 是字符串，则输出 str 也是字符串。否则，str 是字符向量。

要以字符串数组或字符向量元胞数组形式返回多个格式化文本段，请使用 compose 函数。

示例

如果操作失败，[str,errmsg] = sprintf(formatSpec,A1,...,An) 将以字符向量形式返回一条错误消息。否则，errmsg 为空。

str = sprintf(literalText) 转换 literalText 中的转义字符序列，例如 \n 和 \t。它会原样返回所有其他字符。如果 literalText 包含格式化操作符（例如 %f），则 str 将丢弃该字符以及之后的所有字符。

示例

全部折叠

浮点格式

打开实时脚本

使用 %e、%f 和 %g 设定符设置浮点数的格式。

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'

字面文本和数组输入

打开实时脚本

将字面文本与数组值组合在一起来创建字符向量。

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

str = 
'The array is 2x3.'

将格式化文本指定为字符串数组

打开实时脚本

要以字符串形式返回格式化文本，请在调用 sprintf 函数时将 formatSpec 指定为字符串而不是字符向量。

转换数据并以字符串的形式返回结果。

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

转换输入字符串。包含文本的输入数组可以是字符向量或字符串。

A1 = 2;
A2 = 35;
A3 = "p.m.";
str = sprintf(formatSpec,A1,A2,A3)

str = 
"The current time is: 2:35 p.m."

带有浮点输入的整数格式

打开实时脚本

将双精度值显式转换为整数。

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

str = 
'3'

指定输出值的字段宽度

打开实时脚本

指定输出值的最小宽度。

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

str = 
'0000000000000000000123456'

%025d 格式设定符中的 0 标志请求在输出中使用前导零。

使用位置标识符 (n$) 对输入重新排序

打开实时脚本

使用 n$ 位置标识符将输入值重新排序。

A1 = 'X';
A2 = 'Y';
A3 = 'Z';
formatSpec = ' %3$s %2$s %1$s';
str = sprintf(formatSpec,A1,A2,A3)

str = 
' Z Y X'

根据元胞数组中的值创建字符向量

打开实时脚本

C = { 1,   2,   3 ;
     'AA','BB','CC'};

str = sprintf(' %d %s',C{:})

str = 
' 1 AA 2 BB 3 CC'

语法 C{:} 创建一个逗号分隔的数组列表，该列表以列顺序包含 C 中每个元胞的内容。例如，C{1}==1 和 C{2}=='AA'。

输入参数

全部折叠

`formatSpec` — 输出字段的格式
格式化操作符

输出字段的格式，使用格式化操作符指定。formatSpec 还可以包括普通文本和特殊字符。

如果 formatSpec 包括表示转义字符的字面文本，如 \n，则 sprintf 将转换转义字符。

formatSpec 可以是用单引号引起来的字符向量，也可以是字符串标量。

格式化操作符

格式化操作符以百分号 % 开头，以转换字符结尾。转换字符是必需的。您也可以在 % 和转换字符之间指定标识符、标志、字段宽度、精度和子类型操作符。（操作符之间的空格无效，在这里显示空格只是为了便于阅读。）

Schematic of formatting operator characters.

转换字符

此表显示了要将数值和字符数据格式化为文本的转换字符。

值类型	转换	详细信息
有符号整数	`%d` 或 `%i`	以 10 为基数
无符号整数	`%u`	以 10 为基数
	`%o`	以 8 为基数（八进制）
	`%x`	以 16 为基数（十六进制），小写字母 `a`–`f`
	`%X`	与 `%x` 相同，大写字母 `A`–`F`
浮点数	`%f`	定点记数法（使用精度操作符指定小数点后的位数。）
	`%e`	指数记数法，例如 `3.141593e+00`（使用精度操作符指定小数点后的位数）。
	`%E`	与 `%e` 相同，但为大写，例如 `3.141593E+00`（使用精度操作符指定小数点后的位数）。
	`%g`	更紧凑的 `%e` 或 `%f`，不带尾随零（使用精度操作符指定有效数字位数。）
	`%G`	更紧凑的 `%E` 或 `%f`，不带尾随零（使用精度操作符指定有效数字位数。）
字符或字符串	`%c`	单个字符
字符或字符串	`%s`	字符向量或字符串数组。输出文本的类型与 `formatSpec` 的类型相同。

可选运算符

可选标识符、标志、字段宽度、精度和子类型操作符进一步定义了输出文本的格式。

标识符
处理函数输入参量的顺序。使用语法 n$，其中 n 代表函数调用中其他输入参量的位置。
示例：('%3$s %2$s %1$s %2$s','A','B','C') 将输入参量 'A'、'B'、'C' 输出为：C B A B。
注意：如果输入参量为数组，则不能使用标识符指定该输入参量中的特定数组元素。

标志

`'–'`	左对齐。示例：`%-5.2f` 示例：`%-10s`
`'+'`	始终为任何数值输出符号字符（+ 或 –）。示例：`%+5.2f` 右对齐文本。示例：`%+10s`
`' '`	在值之前插入空格。示例：`% 5.2f`
`'0'`	在值之前补零以填充字段宽度。例如：`%05.2f`
`'#'`	修改选定的数值转换：对于 `%o`、`%x` 或 `%X`，将输出 `0`、`0x` 或 `0X` 前缀。对于 `%f`、`%e` 或 `%E`，即使精度为零也将输出小数点。对于 `%g` 或 `%G`，不删除尾随零或小数点。示例：`%#5.0f`

字段宽度
要输出的最低字符数。字段宽度操作符可以是数字，也可以是指向输入参量的星号 (*)。
当您将 * 指定为字段宽度操作符时，其他输入参量必须指定打印宽度和要打印的值。宽度和值可以是参量对组，也可以是数值数组中的对组。使用 * 作为字段宽度操作符时，您可以打印具有不同宽度的不同值。
示例：输入参量 ('%12d',intmax) 等效于 ('%*d',12,intmax)。
示例：输入参量 ('%*d',[2 10 5 100]) 返回 '10 100'，其中两个空格分配给 10，五个空格分配给 100。您也可以将字段宽度和值指定为多个参量，如 ('%*d',2,10,5,100) 中所示。
除非标志另行指定，否则该函数使用空格填充值之前的字段宽度。
精度
对于 %f、%e 或 %E
小数点右侧的位数
示例：'%.4f' 将 pi 输出为 '3.1416'
对于 %g 或 %G
有效位数
示例：'%.4g' 将 pi 输出为 '3.142'
精度操作符可以是数字，也可以是指向参量的星号 (*)。
当您将 * 指定为字段精度操作符时，其他输入参量必须指定打印精度和要打印的值。精度和值可以是参量对组，也可以是数值数组中的对组。使用 * 作为精度操作符时，您可以打印具有不同精度的不同值。
将 *.* 指定为字段宽度和精度操作符时，必须以三元组形式指定字段宽度、精度和值。
示例：输入参量 ('%.4f',pi) 等效于 ('%.*f',4,pi)。
示例：输入参量 ('%6.4f',pi) 等效于 ('%*.*f',6,4,pi)。
示例：输入参量 ('%*.*f',6,4,pi,9,6,exp(1)) 返回 '3.1416 2.718282'，其中以 9 和 6 分别作为 exp(1) 输出的字段宽度和精度。
注意
如果您为浮点值指定的精度操作符所表示的精度超出输入数值数据类型的精度，则在指定精度内，结果与输入值可能不匹配。结果取决于您的计算机硬件和操作系统。

子类型

可以使用子类型操作符将浮点值显示为八进制、十进制或十六进制值。子类型操作符紧邻转换字符之前。此表显示了可使用子类型的转换。

输入值类型	子类型和转换字符	输出值类型
浮点数	`%bx` 或 `%bX` `%bo` `%bu`	双精度十六进制、八进制或十进制值例如：`%bx` 将 `pi` 输出为 `400921fb54442d18`
浮点数	`%tx` 或 `%tX` `%to` `%tu`	单精度十六进制、八进制或十进制值例如：`%tx` 将 `pi` 输出为 `40490fdb`

格式化操作符前或后的文本

formatSpec 还可以在百分号 % 前添加其他文本，或者在转换字符后添加其他文本。文本可以为：

要打印的普通文本。

您无法作为普通文本输入的特殊字符。此表显示了如何在 formatSpec 中表示特殊字符。

特殊字符	表示形式
单引号	`''`
百分比字符	`%%`
反斜杠	`\\`
警报	`\a`
退格符	`\b`
换页符	`\f`
换行符	`\n`
回车符	`\r`
水平制表符	`\t`
垂直制表符	`\v`
其 Unicode^® 数值可以通过十六进制数 `N` 表示的字符	`\xN` 示例：`sprintf('\x5A')` 返回 `'Z'`
其 Unicode 数值可以通过八进制数 `N` 表示的字符	`\N` 示例：`sprintf('\132')` 返回 `'Z'`

使用格式化操作符进行转换时要注意的行为

如果指定不适合数据的转换（例如数值的文本转换），MATLAB^® 将改写指定的转换并使用 %e。
示例：'%s' 将 pi 转换为 3.141593e+00。
如果对整数值应用文本转换（%c 或 %s），MATLAB 会将对应于有效字符代码的值转换为字符。
示例：'%s' 将 [65 66 67] 转换为 ABC。

`A1,...,An` — 数值、字符或字符串数组
数组

数值、字符或字符串数组。

`literalText` — 不带格式化操作符的输入文本
字符向量 | 字符串标量

不带格式化操作符的输入文本，指定为字符向量或字符串标量。sprintf 转换 literalText 中的任何转义字符序列。

数据类型: char | string

输出参量

全部折叠

`str` — 格式化文本
字符向量 | 字符串标量

格式化文本，以字符向量或字符串标量的形式返回。输出的类型与 formatSpec 的类型匹配。

`errmsg` — 错误消息
字符向量

运算失败时以字符向量形式返回的错误消息。否则，errmsg 为空。

提示

sprintf 函数类似于 fprintf，但 fprintf 输出到文件或输出到命令行窗口。
读取函数 sscanf 和 fscanf 的格式设定符不同于写入函数 sprintf 和 fprintf 的格式。读取函数不支持精度字段。宽度字段在写入函数中指定最小值，但在读取函数中指定最大值。
如果您指定了无效的格式化操作符或特殊字符，则 sprintf 会输出所有文本，直到出现无效的操作符或字符，并丢弃其余部分。
示例：如果 formatSpec 是 'value = %z'，则 sprintf 将输出 'value ='，因为 %z 不是格式化操作符。
示例：如果 formatSpec 是 'character \x99999 = %s'，则 sprintf 将输出 'character'，因为 \x99999 不是有效的特殊字符。

参考

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

扩展功能

全部展开

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

用法说明和限制：

参数 formatSpec 必须是常量。
在 formatSpec 中，十六进制数必须在 [0 7F] 范围内，八进制数必须在 [0 177] 范围内。
如果所有输入数组都是常量，则代码生成器会在代码生成时在 MATLAB 中计算 sprintf 调用。在这种情况下，对 sprintf 的代码生成限制不适用，生成的代码中 sprintf 的行为与在 MATLAB 中的行为相同。
如果外部调用不可行，则代码生成器为 sprintf 生成 C 代码。当外部调用被禁用或在 parfor 循环内调用 sprintf 时，不能进行外部调用。
在以下情况下，生成的代码中 sprintf 的行为与 C 编译器的行为一致，而不是与 MATLAB 的行为一致：
- 格式设定符具有一个对应的 C 格式设定符，例如 %e 或 %E。
- sprintf 调用在 parfor 循环内。
- 外部调用被禁用。
不支持以下选项和功能：
- 用于对输入值进行重新排序的 n$ 位置标识符。
- 打印数组。
- 使用子类型将浮点数打印为八进制、十进制或十六进制值。
当您使用格式设定符 %s 调用 sprintf 时，不能在输入字符向量的中间放置空字符。要写入空字符，请使用 sprintf(fid, '%c', char(0))。
输入参量的类型必须与其格式类型匹配。例如，如果 n 是双精度，则代码生成不允许使用以下代码：
```
str = sprintf('%d',n)
```
要进行代码生成，请先将 n 转换为有符号整数类型，如 int8。
```
str = sprintf('%d',int8(n))
```
当您使用整数格式设定符调用 sprintf 时，整数参量的类型必须能够被目标硬件表示为本机 C 类型。例如，如果您调用 sprintf('%d', int64(n))，目标硬件必须具有支持 64 位整数的本机 C 类型。
必须启用动态内存分配。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

此函数完全支持基于线程的环境。有关详细信息，请参阅在基于线程的环境中运行 MATLAB 函数。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

sprintf 函数支持 GPU 数组输入，但有以下用法说明和限制：

此函数接受 GPU 数组，但不在 GPU 上运行。

有关详细信息，请参阅在 GPU 上运行 MATLAB 函数 (Parallel Computing Toolbox)。

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

用法说明和限制：

此函数在分布式数组上运行，但在客户端 MATLAB 中执行。

有关详细信息，请参阅使用分布式数组运行 MATLAB 函数 (Parallel Computing Toolbox)。

版本历史记录

在 R2006a 之前推出

另请参阅

主题

格式化文本

对于 `%f`、`%e` 或 `%E`	小数点右侧的位数示例：`'%.4f'` 将 `pi` 输出为 `'3.1416'`
对于 `%g` 或 `%G`	有效位数示例：`'%.4g'` 将 `pi` 输出为 `'3.142'`

sprintf

语法

说明

示例

浮点格式

字面文本和数组输入

将格式化文本指定为字符串数组

带有浮点输入的整数格式

指定输出值的字段宽度

使用位置标识符 (n$) 对输入重新排序

根据元胞数组中的值创建字符向量

输入参数

formatSpec — 输出字段的格式 格式化操作符

A1,...,An — 数值、字符或字符串数组 数组

literalText — 不带格式化操作符的输入文本 字符向量 | 字符串标量

输出参量

str — 格式化文本 字符向量 | 字符串标量

errmsg — 错误消息 字符向量

提示

参考

扩展功能

C/C++ 代码生成 使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

基于线程的环境 使用 MATLAB® backgroundPool 在后台运行代码或使用 Parallel Computing Toolbox™ ThreadPool 加快代码运行速度。

GPU 数组 通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

分布式数组 使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。

版本历史记录

另请参阅

主题

`formatSpec` — 输出字段的格式
格式化操作符

`A1,...,An` — 数值、字符或字符串数组
数组

`literalText` — 不带格式化操作符的输入文本
字符向量 | 字符串标量

`str` — 格式化文本
字符向量 | 字符串标量

`errmsg` — 错误消息
字符向量

C/C++ 代码生成
使用 MATLAB® Coder™ 生成 C 代码和 C++ 代码。

基于线程的环境
使用 MATLAB® `backgroundPool` 在后台运行代码或使用 Parallel Computing Toolbox™ `ThreadPool` 加快代码运行速度。

GPU 数组
通过使用 Parallel Computing Toolbox™ 在图形处理单元 (GPU) 上运行来加快代码执行。

分布式数组
使用 Parallel Computing Toolbox™ 在集群的组合内存中对大型数组进行分区。