std::basic_streambuf

来自cppreference.com
< cpp‎ | io
 
 
 
 
在标头 <streambuf> 定义
template<

    class CharT,
    class Traits = std::char_traits<CharT>

> class basic_streambuf;

basic_streambuf 控制字符序列的输入与输出。它包含下列内容并提供到它们的访问:

  1. 受控制字符序列,又称为缓冲区,它可含有为输入操作缓冲的输入序列(又称为获取区),和/或为输出操作缓冲的输出序列(又称为放置区)。
  2. 关联字符序列,又称作(对于输入)或(对于输出)。它可以是通过操作系统 API 访问的实体(文件、TCP 接头、串行端口、其他字符设备),或者可以是能转译成字符源或池的对象(std::vector数组字符串字面量)。

输入/输出流对象 std::basic_istreamstd::basic_ostream,还有所有派生自它们的对象(std::ofstreamstd::stringstream 等),都完全以 std::basic_streambuf 实现。

受控制字符序列是 CharT 的数组,它在所有时候都表示子序列,或对着关联字符序列的“窗”。它的状态以三个指针描述:

  1. 起始指针 ,始终指向缓冲的最低元素
  2. 下一位置指针 ,指向读或写的下个候选元素
  3. 终止指针 ,指向缓冲区尾后一个位置。

basic_streambuf 对象可支持输入(此时起始、下一位置和终止指针所描述的区域被称为获取区)、输出(放置区),或同时输入与输出。在最后一种情况下,跟踪六个指针,它们可能全部指向同一数组的元素,或指向两个单独数组的元素。

如果放置区中下一位置指针小于终止指针,那么 写位置 可用。下一位置指针可被解引用和赋值。

如果获取区中下一位置指针小于终止指针,那么 读位置 可用。下一位置指针可被解引用和读取。

如果获取区中下一位置指针大于起始指针,那么 回放位置 可用,而下一位置指针可以被自减并赋值,以将字符放回到获取区。

受控制序列中的字符表示和编码可以异于关联序列中的字符表示,该情况下典型地用 std::codecvt 本地环境进行转换。常见的例子是通过 std::wfstream 对象访问 UTF-8(或其他多字节编码)文件:受控制字符序列由 wchar_t 字符组成,但关联序列由字节组成。

std::basic_streambuf 基类的典型实现只保有六个 CharT* 指针和一个 std::locale 副本作为数据成员。另外,实现可以保持缓存的本地环境平面,凡在调用 imbue() 时使它失效。具体的缓冲类,如 std::basic_filebufstd::basic_stringbuf 派生自 std::basic_streambuf

std-streambuf.svg

提供数个对于常用字符类型的 typedef:

在标头 <streambuf> 定义
类型 定义
std::streambuf std::basic_streambuf<char>
std::wstreambuf std::basic_streambuf<wchar_t>

成员类型

成员类型 定义
char_type CharT
traits_type TraitsTraits::char_type 不是 CharT 时程序非良构。
int_type Traits::int_type
pos_type Traits::pos_type
off_type Traits::off_type

成员函数

析构 basic_streambuf 对象
(虚公开成员函数)
本地环境
调用 imbue()
(公开成员函数)
获得相关本地环境的副本
(公开成员函数)
寻位
调用 setbuf()
(公开成员函数)
调用 seekoff()
(公开成员函数)
调用 seekpos()
(公开成员函数)
调用 sync()
(公开成员函数)
获取区
获得获取区中立即可用的字符数
(公开成员函数)
令输入序列前进,读取一个字符而不再次前进
(公开成员函数)
(C++17 中移除)
从输入序列读取一个字符并令序列前进
(公开成员函数)
从输入序列读取一个字符,而不令序列前进
(公开成员函数)
调用 xsgetn()
(公开成员函数)
放置区
写一个字符到放置区域,并令 next 指针前进
(公开成员函数)
调用 xsputn()
(公开成员函数)
回放
在输入序列中放回一个字符
(公开成员函数)
回移一位输出序列中的下一位置指针
(公开成员函数)

受保护成员函数

构造 basic_streambuf 对象
(受保护成员函数)
(C++11)
替换 basic_streambuf 对象
(受保护成员函数)
(C++11)
交换两个 basic_streambuf 对象
(受保护成员函数)
本地环境
[虚]
更改关联的本地环境
(虚受保护成员函数)
寻位
[虚]
(在允许时)以用户定义数组替换缓冲区
(虚受保护成员函数)
用相对寻址重定位输入序列、输出序列或两者中的下一位置指针
(虚受保护成员函数)
用绝对寻址重定位输入序列、输出序列或两者中的下一位置指针
(虚受保护成员函数)
[虚]
将缓冲与关联的字符序列同步
(虚受保护成员函数)
获取区
获得关联输入序列中可用于输入的字符数(如果已知)
(虚受保护成员函数)
从关联输入序列读取字符到获取区
(虚受保护成员函数)
[虚]
从输入序列读取字符到获取区,并令下一位置指针前进
(虚受保护成员函数)
[虚]
从输入序列读取多个字符
(虚受保护成员函数)
返回指向获取区起始、当前字符和末尾的指针
(受保护成员函数)
令输出序列中的下一位置指针前进
(受保护成员函数)
重定位输出序列的起始、下一位置和终止指针
(受保护成员函数)
放置区
[虚]
将多个字符写到输出序列
(虚受保护成员函数)
从放置区写入字符到关联的输出序列
(虚受保护成员函数)
返回指向放置区的起始、当前字符和末尾的指针
(受保护成员函数)
令输出序列中的下一位置指针前进
(受保护成员函数)
重定位输出序列的起始、下一位置和终止指针
(受保护成员函数)
回放
将字符放回输入序列,可能修改输入序列
(虚受保护成员函数)

参阅

对象类型,足以保有控制 C 输入/输出流所需的全部信息
(typedef)