命名空间
变体
操作

std::printf, std::fprintf, std::sprintf, std::snprintf

来自 cppreference.cn
< cpp‎ | io‎ | c
 
 
 
C 风格 I/O
类型和对象
函数
文件访问
直接输入/输出
非格式化输入/输出
格式化输入
(C++11起)(C++11起)(C++11起)    
(C++11起)(C++11起)(C++11起)    
格式化输出
printffprintfsprintfsnprintf
(C++11起)
文件定位
错误处理
文件操作
 
定义于头文件 <cstdio>
int printf( const char* format, ... );
(1)
int fprintf( std::FILE* stream, const char* format, ... );
(2)
int sprintf( char* buffer, const char* format, ... );
(3)
int snprintf( char* buffer, std::size_t buf_size, const char* format, ... );
(4) (C++11 起)

从给定位置加载数据,将其转换为字符字符串等效项,并将结果写入各种目标。

1) 将结果写入 stdout
2) 将结果写入文件流 stream
3) 将结果写入字符字符串 buffer
4) 将结果写入字符字符串 buffer。最多写入 buf_size - 1 个字符。除非 buf_size 为零,否则结果字符字符串将以空字符终止。如果 buf_size 为零,则不写入任何内容,buffer 可以是空指针,但是仍会计算并返回返回值(不包括空终止符的写入字节数)。

如果对 sprintfsnprintf 的调用导致重叠对象之间进行复制,则行为是未定义的(例如 sprintf(buf, "%s text", buf);)。

目录

[编辑] 参数

stream - 要写入的输出文件流
buffer - 要写入的字符字符串指针
buf_size - 最多可以写入 buf_size - 1 个字符,再加上空终止符
format - 指向以 null 结尾的多字节字符串的指针,指定如何解释数据
... - 指定要打印的数据的参数。如果在默认参数提升后,任何参数的类型与相应转换说明符所期望的类型(期望类型是提升类型或提升类型的兼容类型)不符,或者参数少于 format 所要求的数量,则行为未定义。如果参数多于 format 所要求的数量,则多余的参数会被评估并忽略

format 字符串由普通字节字符(除了 %)组成,它们被不变地复制到输出流中,以及转换说明符。每个转换说明符具有以下格式:

  • 前导 % 字符。
  • (可选) 一个或多个修改转换行为的标志
  • -: 转换结果在字段内左对齐(默认情况下右对齐)。
  • +: 有符号转换的符号总是前置在转换结果之前(默认情况下,结果只有在为负时才前置减号)。
  • 空格: 如果有符号转换的结果不以符号字符开头,或者为空,则在结果前置空格。如果存在 + 标志,则忽略此标志。
  • #: 执行转换的替代形式。具体效果请参见下表,否则行为未定义。
  • 0: 对于整数和浮点数转换,使用前导零填充字段,而不是空格字符。对于整数,如果明确指定了精度,则忽略此标志。对于使用此标志的其他转换,会导致未定义行为。如果存在 - 标志,则忽略此标志。
  • (可选) 整数值或 *,指定最小字段宽度。如果需要,结果会用空格字符填充(默认),右对齐时在左侧填充,左对齐时在右侧填充。当使用 * 时,宽度由一个额外的 int 类型参数指定,该参数出现在待转换参数之前,如果提供了精度参数,则出现在精度参数之前。如果该参数的值为负,则表示指定了 - 标志和正字段宽度(注意:这是最小宽度:值永远不会被截断)。
  • (可选) . 后跟整数或 *,或两者皆无,指定转换的精度。当使用 * 时,精度由一个额外的 int 类型参数指定,该参数出现在待转换参数之前,但在提供最小字段宽度参数之后(如果已提供)。如果此参数的值为负,则忽略它。如果既未使用数字也未使用 *,则精度视为零。有关精度的具体效果,请参见下表。
  • (可选) 长度修饰符,指定参数的大小(与转换格式说明符结合使用,指定相应参数的类型)。
  • 转换格式说明符。

以下格式说明符可用:

转换
说明符
解释 预期
参数类型
长度修饰符→ hh h l ll j z t L
仅自 C++11 起可用→
% 写入字面量 %。完整的转换说明符必须是 %% 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用 不适用
c

写入单个字符

  • 参数首先转换为 unsigned char
  • 如果使用 l 修饰符,则参数首先转换为字符字符串,如同通过 %ls 使用 wchar_t[2] 参数进行转换。
不适用 不适用
int
std::wint_t
不适用 不适用 不适用 不适用 不适用
s

写入字符字符串

  • 参数必须是指向字符数组初始元素的指针。
  • 精度 指定要写入的最大字节数。如果未指定精度,则写入每个字节直到(但不包括)第一个空终止符。
  • 如果使用 l 说明符,则参数必须是指向 wchar_t 数组初始元素的指针,该数组将转换为 char 数组,如同通过调用 std::wcrtomb 并使用零初始化的转换状态。
不适用 不适用
char*
wchar_t*
不适用 不适用 不适用 不适用 不适用
d
i

有符号整数转换为十进制表示 [-]dddd

  • 精度 指定要出现的最小位数。默认精度为 1
  • 如果转换值和精度都为 0,则转换结果为空字符。
  • 对于 z 修饰符,期望的参数类型是 std::size_t 的有符号版本。
signed char
short
int
long
long long
不适用
o

无符号整数转换为八进制表示 oooo

  • 精度 指定要出现的最小位数。默认精度为 1
  • 如果转换值和精度都为 0,则转换结果为空字符。
  • 替代实现中,如果需要,精度会增加,以写入一个前导零。在这种情况下,如果转换值和精度都为 0,则写入单个 0
unsigned char
unsigned short
unsigned int
unsigned long
unsigned long long
std::ptrdiff_t 的无符号版本
不适用
x
X

无符号整数转换为十六进制表示 hhhh

  • 对于 x 转换,使用字母 abcdef
  • 对于 X 转换,使用字母 ABCDEF
  • 精度 指定要出现的最小位数。默认精度为 1
  • 如果转换值和精度都为 0,则转换结果为空字符。
  • 替代实现中,如果转换值非零,则在结果前添加 0x0X
不适用
u

无符号整数转换为十进制表示 dddd

  • 精度 指定要出现的最小位数。
  • 默认精度为 1
  • 如果转换值和精度都为 0,则转换结果为空字符。
不适用
f
F (C++11起)

浮点数转换为十进制表示法,样式为 [-]ddd.ddd

  • 精度 指定小数点字符后要出现的准确位数。
  • 默认精度为 6
  • 替代实现中,即使后面没有数字,也会写入小数点字符。
  • 关于无穷大和非数字的转换样式,请参见注释
不适用 不适用
double
double (C++11起)
不适用 不适用 不适用 不适用
long double
e
E

浮点数转换为十进制指数表示法。

  • 对于 e 转换,使用样式 [-]d.ddd e±dd
  • 对于 E 转换,使用样式 [-]d.ddd E±dd
  • 指数至少包含两位数字,只有在必要时才使用更多数字。
  • 如果值为 0,则指数也为 0
  • 精度 指定小数点字符后要出现的准确位数。
  • 默认精度为 6
  • 替代实现中,即使后面没有数字,也会写入小数点字符。
  • 关于无穷大和非数字的转换样式,请参见注释
不适用 不适用 不适用 不适用 不适用 不适用
a
A

(C++11)

浮点数转换为十六进制指数表示法。

  • 对于 a 转换,使用样式 [-] 0xh.hhh p±d
  • 对于 A 转换,使用样式 [-] 0Xh.hhh P±d
  • 如果参数是规范化浮点值,则第一个十六进制数字不是 0
  • 如果值为 0,则指数也为 0
  • 精度 指定十六进制小数点字符后要出现的准确位数。
  • 默认精度足以精确表示该值。
  • 替代实现中,即使后面没有数字,也会写入小数点字符。
  • 关于无穷大和非数字的转换样式,请参见注释
不适用 不适用 不适用 不适用 不适用 不适用
g
G

根据值和精度,将浮点数转换为十进制或十进制指数表示法。

  • 对于 g 转换样式,将执行样式 ef 的转换。
  • 对于 G 转换样式,将执行样式 Ef(C++11 前)F(C++11 起) 的转换。
  • P 等于精度(如果非零),如果未指定精度则为 6,如果精度为 0 则为 1。然后,如果使用样式 E 的转换将具有指数 X
    • 如果 P > X ≥ −4,则转换使用样式 fF(C++11 起),精度为 P − 1 − X
    • 否则,转换使用样式 eE,精度为 P − 1
  • 除非请求替代表示,否则会删除尾随零,如果不再有小数部分,也会删除小数点字符。
  • 关于无穷大和非数字的转换样式,请参见注释
不适用 不适用 不适用 不适用 不适用 不适用
n

返回此函数调用目前已写入的字符数

  • 结果被写入到参数指向的值。
  • 说明符不得包含任何标志字段宽度精度
  • 对于 z 修饰符,期望的参数类型是 S*,其中 Sstd::size_t 的有符号版本。
signed char*
short*
int*
long*
long long*
不适用
p

写入一个实现定义的字符序列,定义一个指针

不适用 不适用
void*
不适用 不适用 不适用 不适用 不适用 不适用
备注

浮点转换函数将无穷大转换为 infinfinity。具体使用哪一个由实现定义。

非数字转换为 nannan(char_sequence)。具体使用哪一个由实现定义。

转换 FEGA 输出 INFINFINITYNAN

用于打印 charunsigned charsigned charshortunsigned short 的转换说明符期望 默认参数提升后的提升类型,但在打印其值之前,它将转换为 charunsigned charsigned charshortunsigned short。由于在调用可变参数函数时发生的提升,传递这些类型的值是安全的。

固定宽度字符类型(std::int8_t 等)的正确转换说明符定义在头文件 <cinttypes> 中(尽管 PRIdMAXPRIuMAX 等是 %jd%ju 等的同义词)。

内存写入转换说明符 %n 是格式字符串依赖用户输入时常见的安全漏洞目标。

每个转换说明符的操作之后都有一个序列点;这允许在同一变量中存储多个 %n 结果,或者在极端情况下,在同一次调用中打印被早期 %n 修改的字符串。

如果转换说明符无效,则行为未定义。

[编辑] 返回值

1,2) 成功时写入的字符数,或发生错误时的负值。
3) 成功时写入的字符数(不包括终止空字符),或发生错误时的负值。
4) 如果成功,对于足够大的缓冲区,将写入的字符数(不包括终止空字符),或发生错误时的负值。因此,当且仅当返回值为非负且小于 buf_size 时,(空终止的)输出才被完全写入。

[编辑] 备注

POSIX 指定在错误时设置 errno。它还指定了额外的转换说明符,最值得注意的是支持参数重新排序(n$ 紧接在 % 之后表示第 n 个参数)。

调用 std::snprintf 时,将 buf_size 设置为零,将 buffer 设置为空指针非常有用(当可以接受双次调用开销时),用于确定容纳输出所需的缓冲区大小

auto fmt = "sqrt(2) = %f";
int sz = std::snprintf(nullptr, 0, fmt, std::sqrt(2));
std::vector<char> buf(sz + 1); // note +1 for null terminator
std::sprintf(buf.data(), fmt, std::sqrt(2)); // certain to fit

[编辑] 示例

#include <cinttypes>
#include <cstdint>
#include <cstdio>
#include <limits>
 
int main()
{
    const char* s = "Hello";
    std::printf("Strings:\n"); // same as std::puts("Strings:");
    std::printf("\t[%10s]\n", s);
    std::printf("\t[%-10s]\n", s);
    std::printf("\t[%*s]\n", 10, s);
    std::printf("\t[%-10.*s]\n", 4, s);
    std::printf("\t[%-*.*s]\n", 10, 4, s);
 
    std::printf("Characters:\t%c %%\n", 'A');
 
    std::printf("Integers:\n");
    std::printf("\tDecimal:    \t%i %d %.6i %i %.0i %+i %i\n",
                                  1, 2,   3, 0,   0,  4,-4);
    std::printf("\tHexadecimal:\t%x %x %X %#x\n",
                                  5,10,10,  6);
    std::printf("\tOctal:      \t%o %#o %#o\n",
                                 10, 10,  4);
 
    std::printf("Floating point:\n");
    std::printf("\tRounding:\t%f %.0f %.32f\n", 1.5, 1.5, 1.3);
    std::printf("\tPadding:\t%05.2f %.2f %5.2f\n", 1.5, 1.5, 1.5);
    std::printf("\tScientific:\t%E %e\n", 1.5, 1.5);
    std::printf("\tHexadecimal:\t%a %A\n", 1.5, 1.5);
    std::printf("\tSpecial values:\t0/0=%g 1/0=%g\n", 0.0/0.0, 1.0/0.0);
 
    std::printf("Variable width control:\n");
    std::printf("\tright-justified variable width: '%*c'\n", 5, 'x');
    int r = std::printf("\tleft-justified variable width : '%*c'\n", -5, 'x');
    std::printf("(the last printf printed %d characters)\n", r);
 
    std::printf("Fixed-width types:\n");
    std::uint32_t val = std::numeric_limits<std::uint32_t>::max();
    std::printf("\tLargest 32-bit value is %" PRIu32 " or %#" PRIx32 "\n",
                                                 val,            val);
}

可能的输出

Strings:
	[     Hello]
	[Hello     ]
	[     Hello]
	[Hell      ]
	[Hell      ]
Characters:	A %
Integers:
	Decimal:    	1 2 000003 0  +4 -4
	Hexadecimal:	5 a A 0x6
	Octal:      	12 012 04
Floating point:
	Rounding:	1.500000 2 1.30000000000000004440892098500626
	Padding:	01.50 1.50  1.50
	Scientific:	1.500000E+00 1.500000e+00
	Hexadecimal:	0x1.8p+0 0X1.8P+0
	Special values:	0/0=-nan 1/0=inf
Variable width control:
	right-justified variable width: '    x'
	left-justified variable width : 'x    '
(the last printf printed 41 characters)
Fixed-width types:
	Largest 32-bit value is 4294967295 or 0xffffffff

[编辑] 参见

stdout、文件流或缓冲区打印格式化的宽字符输出
(函数) [编辑]
将格式化输出打印到 stdout、文件流或缓冲区
使用可变参数列表
(函数) [编辑]
将字符字符串写入文件流
(函数) [编辑]
stdin、文件流或缓冲区读取格式化输入
(函数) [编辑]
(C++17)
将整数或浮点值转换为字符序列
(函数) [编辑]
(C++23)
使用参数的格式化表示打印到 stdout 或文件流
(函数模板) [编辑]
(C++23)
std::print 相同,但每次打印都以额外的换行符终止
(函数模板) [编辑]
C 文档 for printf, fprintf, sprintf, snprintf