定义于头文件 <fstream>
template< class CharT, |
std::basic_filebuf
是关联字符序列为文件的 std::basic_streambuf 。输入序列和输出序列都关联到同一文件,并为两种操作维护连接文件位置。
函数 underflow() 和 overflow()/sync() 进行文件和缓冲区的获取放置区之间的实际 I/O 。 CharT
不是 char 时,多数实现在文件存储多字节字符,并用 std::codecvt 平面进行宽/多字节字符转换。
亦为常用字符类型定义二个特化:
类型 | 定义 |
filebuf | basic_filebuf<char> |
wfilebuf | basic_filebuf<wchar_t> |
公开成员函数
打开文件并配置它为关联字符序列
std::basic_filebuf<CharT,Traits>::open
std::basic_filebuf<CharT, Traits>* open( const char* s, | (1) | |
std::basic_filebuf<CharT, Traits>* open( const std::string& str, | (2) | (C++11 起) |
std::basic_filebuf<CharT, Traits>* open( const std::filesystem::path& p, | (3) | (C++17 起) |
std::basic_filebuf<CharT, Traits>* open( const std::filesystem::path::value_type* s, | (4) | (C++17 起) |
打开拥有给定名称( s 、 p.c_str() (C++17 起) 或 str.c_str() ,取决于重载)的文件。
仅若 std::filesystem::path::value_type 非 char 才提供重载 (4) 。 | (C++17 起) |
如同通过以按下列方式确定的第二参数 (mode
) 调用 std::fopen 打开文件:
mode | openmode & ~ate | 若文件已存在的动作 | 若文件不存在的动作 |
---|---|---|---|
"r" | in | 从头读取 | 打开失败 |
"w" | out, out|trunc | 销毁内容 | 创建新文件 |
"a" | app, out|app | 后附到文件 | 创建新文件 |
"r+" | out|in | 从头读取 | 错误 |
"w+" | out|in|trunc | 销毁内容 | 创建新文件 |
"a+" | out|in|app, in|app | 写入到结尾 | 创建新文件 |
"rb" | binary|in | 从头读取 | 打开失败 |
"wb" | binary|out, binary|out|trunc | 销毁内容 | 创建新文件 |
"ab" | binary|app, binary|out|app | 写入结尾 | 创建新文件 |
"r+b" | binary|out|in | 从头读取 | 错误 |
"w+b" | binary|out|in|trunc | 销毁内容 | 创建新文件 |
"a+b" | binary|out|in|app, binary|in|app | 写入到结尾 | 创建新文件 |
若 openmode
不是列出的模式之一,则 open()
失败。
若打开操作成功且 openmode & std::ios_base::ate != 0 (设置了 ate
位),则重寻位文件位置到文件尾,如同用调用 std::fseek(file, 0, SEEK_END) ,其中 file
是调用 fopen
返回的指针。若寻位失败,则调用 close() 并返回空指针以指示失败。
若关联文件已打开,则立即返回空指针。
参数
s, str, p | - | 要打开的文件名; s 必须指向空终止字符串 |
openmode | - | 文件打开模式, std::ios_base 模式的二进制或 |
返回值
成功时为 this ,失败时为空指针。
注意
常由 std::basic_fstream 的构造函数或 open()
成员函数调用 open()
。
冲入放置区缓冲区并关闭关联的文件
std::basic_filebuf<CharT,Traits>::close
std::basic_filebuf<CharT, Traits>* close(); |
若放置区存在(即为写入打开文件),则首先调用 overflow(Traits::eof()) 写入所有未决输出到文件,包含任何反迁移序列。
若在 underflow() 、 overflow() 、 seekpos() 和 seekoff() 之中最近调用的函数是 overflow() ,则可能多次调用 std::codecvt::unshift() 以确定按照感染的本地环境的反迁移序列,并将该序列以 overflow(Traits::eof()) 写入文件。
然后,如同用 std::fclose() 关闭文件,不考虑任何之前调用成功或失败。
若作出的任何函数调用,包含对 std::fclose() 的调用失败,则返回空指针。若作出的任何函数调用抛出异常,则捕捉该异常并在调用 std::fclose() 后重抛。若该文件已关闭,则立即返回空指针。
任何情况下,都更新 is_open() 所访问的私有成员变量。
参数
(无)
返回值
成功时为 this ,失败时为空指针。
注意
close()
典型地通过 std::basic_filebuf 的析构函数调用(继而典型地为 std::basic_fstream 的析构函数所调用)。