c++11 standard template (STL) (std::basic_streambuf) (1)

Defined in the header file <streambuf>

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

 Class basic_streambufControls the input and output of character sequences. It contains and provides access to the following:

1) Controlled character sequences , also known as buffers , can contain input sequences buffered for input operations (also known as acquisition areas ), and/or output sequences buffered for output operations (also known as drop areas ).

2) A sequence of associated characters , also known as a source (for input) or a pool (for output). It can be an entity accessed through the OS API (file, TCP connector, serial port, other character device), or it can be an object that can be translated into a character source or pool (std::vector, array, string literal) .

The I/O stream objects std::basic_istream and std::basic_ostream, and all objects derived from them (std::ofstream, std::stringstream, etc.), are fully implemented in std::basic_streambuf .

A controlled character sequence CharTis an array of which at all times represents a subsequence, or "window" into the associated character sequence. Its state is described by three pointers:

1) The starting pointer always points to the lowest element of the buffer

2) The next position pointer , pointing to the next candidate element for reading or writing

3) Termination pointer , pointing to a position after the end of the buffer.

basic_streambufObjects can support input (in which case the area described by the start, next, and end pointers is called the get area ), output ( the put area ), or both. In the last case, six pointers are tracked, which may all point to elements of the same array, or to elements of two separate arrays.

If the next location pointer in the put area is less than the end pointer, then the write location is available. The next location pointer can be dereferenced and assigned.

If the next location pointer in the fetch area is less than the end pointer, the read location is available. The next location pointer can be dereferenced and read.

If the next position pointer in the acquisition area is greater than the start pointer, the playback position is available, and the next position pointer can be decremented and assigned to put the character back into the acquisition area.

The character representation and encoding in the controlled sequence may differ from the character representation in the associated sequence, in which case the conversion is typically done with the std::codecvt locale. A common example is accessing UTF-8 (or other multibyte encoding) files via std::wfstream objects: controlled character sequences consist of wchar_t characters, but associated sequences consist of bytes.

std::basic_streambufA typical implementation of the base class holds only six CharT*pointers and a copy of the std::locale as data members. Alternatively, an implementation may keep a cached locale plane, whenever it is invalidated imbue()when . Concrete buffer classes such as std::basic_filebuf or std::basic_stringbuf are derived from std::basic_streambuf.

The standard library provides two convenience typedefs

defined in the header file<streambuf>
type	definition
streambuf	basic_streambuf<char>
wstreambuf	basic_streambuf<wchar_t>

 

member type

member type	definition
char_type	CharT
traits_type	Traits ; if Traits::char_typenot CharTthe program is ill-formed.
int_type	Traits::int_type
pos_type	Traits::pos_type
off_type	Traits::off_type

member function

(destructor) [virtual]	Destruct basic_streambuf object (virtual public member function)
local environment
pubimbue	Call imbue() (public member function)
getloc	Get a copy of the relevant locale (public member function)
locate
pubsetbuf	call setbuf() (public member function)
pubseekoff	Call seekoff() (public member function)
pubseekpos	Call seekpos() (public member function)
pubsync	Call sync() (public member function)
access area
in_avail	Gets the number of characters immediately available in the fetch area (public member function)
snextc	令输入序列前进，读取一个字符而不再次前进 (公开成员函数)
sbumpc	从输入序列读取一个字符并令序列前进 (公开成员函数)
stossc (C++98 中弃用)(C++17 中移除)	令输入序列前进，如同通过调用 sbumpc() 并舍弃结果 (公开成员函数)
sgetc	从输入序列读取一个字符，而不令序列前进 (公开成员函数)
sgetn	调用 xsgetn() (公开成员函数)
放置区
sputc	写一个字符到放置区域，并令 next 指针前进 (公开成员函数)
sputn	调用 xsputn() (公开成员函数)
回放
sputbackc	在输入序列中放回一个字符 (公开成员函数)
sungetc	回移一位输出序列中的下一位置指针 (公开成员函数)
受保护成员函数
(构造函数)	构造 basic_streambuf 对象 (受保护成员函数)
operator= (C++11)	替换 basic_streambuf 对象 (受保护成员函数)
swap (C++11)	交换二个 basic_streambuf 对象 (受保护成员函数)
本地环境
imbue [虚]	更改关联的本地环境 (虚受保护成员函数)
寻位
setbuf [虚]	若容许则以用户定义数组替换缓冲区 (虚受保护成员函数)
seekoff [虚]	用相对寻址重定位输入序列、输出序列或两者中的下一位置指针 (虚受保护成员函数)
seekpos [虚]	用绝对寻址重定位输入序列、输出序列或两者中的下一位置指针 (虚受保护成员函数)
sync [虚]	将缓冲与关联的字符序列同步 (虚受保护成员函数)
获取区
showmanyc [虚]	若已知，则获得关联输入序列中可用于输入的字符数 (虚受保护成员函数)
underflow [虚]	从关联输入序列读取字符到获取区 (虚受保护成员函数)
uflow [虚]	从输入序列读取字符到获取区，并令下一位置指针前进 (虚受保护成员函数)
xsgetn [虚]	从输入序列读取多个字符 (虚受保护成员函数)
ebackgptregptr	返回指向获取区起始、当前字符和末尾的指针 (受保护成员函数)
gbump	令输出序列中的下一位置指针前进 (受保护成员函数)
setg	重定位输出序列的起始、下一位置和终止指针 (受保护成员函数)
放置区
xsputn [虚]	将多个字符写到输出序列 (虚受保护成员函数)
overflow [虚]	从放置区写入字符到关联的输出序列 (虚受保护成员函数)
pbasepptrepptr	返回指向放置区的起始、当前字符和末尾的指针 (受保护成员函数)
pbump	令输出序列中的下一位置指针前进 (受保护成员函数)
setp	重定位输出序列的起始、下一位置和终止指针 (受保护成员函数)
回放
pbackfail [虚]	将字符放回输入序列，可能修改输入序列 (虚受保护成员函数)