c++11 标准模板（STL）（std::basic

模板（STL）（std::basic"/>

c++11 标准模板（STL）（std::basic

定义于头文件 <streambuf>

template<     class CharT,     class Traits = std::char_traits<CharT> > class basic_streambuf;

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

1) 受控制字符序列，又称为缓冲区，它可含有为输入操作缓冲的输入序列（又称为获取区），和/或为输出操作缓冲的输出序列（又称为放置区）。

2) 关联字符序列，又称作源（对于输入）或池（对于输出）。它可以是通过 OS API 访问的实体（文件、 TCP 接头、串行端口、其他字符设备），或者可以是能转译成字符源或池的对象（ std::vector 、数组、字符串字面量）。

I/O 流对象 std::basic_istream 及 std::basic_ostream ，还有所有导出自它们的对象（ std::ofstream 、 std::stringstream 等），都完全以 std::basic_streambuf 实现。

受保护成员函数

获取区

若已知，则获得关联输入序列中可用于输入的字符数

std::basic_streambuf<CharT,Traits>::showmanyc

protected: virtual std::streamsize showmanyc();

 估计关联字符序列中可用于输入的字符数。保证直至释出那么多字符时， underflow() 不返回 Traits::eof() 或抛出异常。

参数

（无）

返回值

关联字符序列中确定可用的字符数，或若 showmanyc 能确定不阻塞则无字符可用则为 -1 。若 showmanyc 返回 -1 ，则 underflow() 和 uflow() 肯定会返回 Traits::eof 或抛出。

基类版本返回 ​0​ ，这表示“不缺地你给关联序列中是否有字符可用”。

注意

此函数的名称表示“流：多少字符？”，故它读作“ S how many C ”，而不是“ show many C ”。

从关联输入序列读取字符到获取区

std::basic_streambuf<CharT,Traits>::underflow

virtual int_type underflow();

 通过更新指向输入区的指针（若需要），和从输入序列读取更多数据（若可用），确保输入区中至少一个字符可用。成功时返回该字符的值（以 int_type 转换为 Traits::to_int_type(c) ），失败时返回 Traits::eof() 。

函数可以更新 gptr 、 egptr 和 eback 指针，以定义新加载的数据位置（若存在）。失败时，函数确保 gptr() == nullptr 或 gptr() == egptr 。

函数的基类版本不做任何事。导出类可覆写此函数以允许在耗尽情况下更新获取区。

参数

（无）

返回值

成功时为调用后获取指针所指向的字符的值。否则为 Traits::eof() 。

函数的基类版本返回 traits::eof() 。

注意

std::streambuf 的公开函数仅若 gptr() == nullptr 或 gptr() >= egptr() 才调用此函数。

调用示例

#include <iostream>
#include <sstream>class null_filter_buf : public std::streambuf
{std::streambuf* src;char ch; // 单字节缓冲区
protected:int underflow(){while ((ch = src->sbumpc()) == '\0') ; // 跳过零setg(&ch, &ch, &ch + 1); // 使得一个读取位置可用return ch; // 可返回 EOF}
public:null_filter_buf(std::streambuf* buf) : src(buf){setg(&ch, &ch + 1, &ch + 1); // 缓冲区被初始填充}
};void filtered_read(std::istream& in)
{std::streambuf* orig = in.rdbuf();null_filter_buf buf(orig);in.rdbuf(&buf);for (char c; in.get(c);){std::cout << c;}in.rdbuf(orig);
}int main()
{char a[] = "This i\0s \0an e\0\0\0xample";std::istringstream in(std::string(std::begin(a), std::end(a)));filtered_read(in);
}

从输入序列读取字符到获取区，并令下一位置指针前进

std::basic_streambuf<CharT,Traits>::uflow

virtual int_type uflow();

通过更新指向输入区的指针（若需要），确保输入区中至少一个字符可用。成功时返回字符的值，并令获取指针的值前进一个字符。失败时返回 traits::eof() 。

函数可以更新 gptr 、 egptr 和 eback 指针，以定义新加载的数据位置（若存在）。失败时，函数确保 gptr() == nullptr 或 gptr() == egptr 。

函数的基类版本调用 underflow() 并自增 gptr() 。

参数

（无）

返回值

成功时为获取指针前进一之前所指向的字符的值，否则为 traits::eof() 。

函数的基类版本返回 underflow() 所返回的值。

注意

std::streambuf 的公开函数仅若 gptr() == nullptr 或 gptr() >= egptr() 才调用此函数。

要求不使用获取区且不设置 basic_streambuf 中获取区指针的定制 streambuf 类覆写此函数。

从输入序列读取多个字符

std::basic_streambuf<CharT,Traits>::sgetn, 
std::basic_streambuf<CharT,Traits>::xsgetn

std::streamsize sgetn( char_type* s, std::streamsize count );	(1)
protected: virtual std::streamsize xsgetn( char_type* s, std::streamsize count );	(2)

1) 调用最终派生类的 xsgetn(s, count) 。

2) 从输入序列读取 count 个字符，并存储它们到 s 所指向的字符数组。如同用以连续调用 sbumpc() 读取字符。即若少于 count 个字符立即可用，则函数调用 uflow() 以提供更多字符，直至返回 Traits::eof() 。

容许派生自 std::basic_streambuf 的类提供此函数的更高效实现。

参数

s	-	指向 char_type 数组起始的指针
count	-	要写入的最大字符数

返回值

成功读取的字符数。若它小于 count ，则输入序列已抵达结尾。

注意

关于“更高效实现”的规则容许大量无中间缓冲的 I/O ：这是一些 iostream 的实现中 std::ifstream::read 简单地传递指针给 POSIX read() 系统调用的原因。

返回指向获取区起始、当前字符和末尾的指针

std::basic_streambuf<CharT,Traits>::eback, gptr, egptr

char_type* eback() const;	(1)
char_type* gptr() const;	(2)
char_type* egptr() const;	(3)

返回定义获取区的指针。

1) 返回指向获取区起始的指针。

2) 返回指向获取区中当前字符的指针（获取指针）。

3) 返回获取区结尾后一位置的指针。

参数

（无）

返回值

1) 指向获取区起始的指针。

2) 指向获取区中当前字符的指针（获取指针）。

3) 获取区结尾后一位置的指针。

注意

名称 "gptr" 和 "egptr" 指代获取区，而名称 "eback" 指代回放区的结尾：从 gptr 往回步进，能放回字符到 eback 为止。

令输出序列中的下一位置指针前进

std::basic_streambuf<CharT,Traits>::gbump

void gbump( int count );

跳过获取区中的 count 个字符。通过令获取指针前进 count 个字符。不为下溢做检查。

参数

count

-

要跳过的字符数

返回值

（无）

注意

因为此函数接收 int ，故它无法操纵大于 std::numeric_limits<int>::max() 字符的缓冲区（ LWG 255 ）。

重定位输出序列的起始、下一位置和终止指针

std::basic_streambuf<CharT,Traits>::setg

void setg( char_type* gbeg, char_type* gcurr, char_type* gend );

设置定义获取区的指针值。特别是调用后 eback() == gbeg ， gptr() == gcurr ， egptr() == gend 。

参数

gbeg	-	指向获取区新起始的指针
gcurr	-	指向获取区中新的当前字符的指针（获取指针）
gend	-	指向获取区新结尾的指针

返回值

（无）