basic_streambuf 类

描述一个用于派生流缓冲区的抽象基类，该缓冲区控制元素与特定的流表示形式的来回传输。

语法

template <class Elem, class Tr = char_traits<Elem>>
class basic_streambuf;

参数

Elem
一个 char_type。

Tr
字符 traits_type。

备注

此类模板描述一个用于派生流缓冲区的抽象基类，该缓冲区控制元素与特定的流表示形式的来回传输。 basic_streambuf 类的对象有助于控制具有 Tr 类型（也称为 char_type）的元素的流，该类型的字符特征由 char_traits 类（也称为 traits_type）决定。

从概念上来说，每个流缓冲区控制两个独立的流：一个用于提取（输入），另一个用于插入（输出）。 但是，特定的表示形式可能会导致这些流中的一个或两个不可访问。 通常，它在两个流之间保持有某种关系。 例如，向 basic_stringbuf<Elem, Tr> 对象的输出流插入的内容，就是之后从其输入流中提取的内容。 当定位 basic_filebuf<Elem, Tr> 对象的一个流时，将同时定位其他流。

类模板 basic_streambuf 的公共接口提供对所有流缓冲区通用但又专用的操作。 受保护的接口提供特定流的表示形式完成其工作所需的操作。 受保护的虚拟成员函数允许你为特定的流表示形式定制派生流缓冲区的行为。 此库中的每个派生流缓冲区描述它如何专用化其受保护虚拟成员函数的行为。 本文中描述了基类的默认行为，基类通常不执行任何操作。

剩余的受保护成员函数控制将内容复制到任何存储以及从此类存储中复制内容的操作，这类存储用于缓冲出入流的传输。 例如，输入缓冲区的特征是：

• eback，指向缓冲区开头的指针。

• gptr，指向要读取的下一个元素的指针。

• egptr，超出缓冲区末尾的指针。

同样，输出缓冲区的特征是：

• pbase，指向缓冲区开头的指针。

• pptr，指向要写入的下一个元素的指针。

• epptr，超出缓冲区末尾的指针。

对于任何缓冲区，使用以下协议：

• 如果下一个指针为 null，则不存在缓冲区。 否则，所有三个指针都将指向相同的序列。 可以安全地比较它们的顺序。

• 对于输出缓冲区，如果下一个指针与结束指针相比较小，则可以在下一个指针指定的写入位置处存储元素。

• 对于输入缓冲区，如果下一个指针与结束指针相比较小，则可以在下一个指针指定的读取位置处读取元素。

• 对于输入缓冲区，如果开始指针与下一个指针相比较小，则可以在递减的下一个指针指定的放回位置处放回元素。

为派生自 basic_streambuf<Elem, Tr> 的类编写的任何受保护虚拟成员函数必须共同协作来维护此协议。

basic_streambuf<Elem, Tr> 类的对象将存储前面所述的六个指针。 该对象还会将区域设置对象存储于类型 locale 的对象中，以供派生的流缓冲区使用。

构造函数

构造函数	说明
basic_streambuf	构造 basic_streambuf 类型的对象。

Typedef

类型名称	说明
char_type	将类型名与 Elem 模板参数关联。
int_type	将 basic_streambuf 范围内的类型名称与 Elem模板参数 关联。
off_type	将 basic_streambuf 范围内的类型名称与 Elem模板参数 关联。
pos_type	将 basic_streambuf 范围内的类型名称与 Elem模板参数 关联。
traits_type	将类型名与 Tr 模板参数关联。

成员函数

成员函数	说明
eback	一个受保护的函数，该函数返回指向输入缓冲区开头的指针。
egptr	一个受保护的函数，该函数返回超出输入缓冲区末尾的指针。
epptr	一个受保护的函数，该函数返回超出输出缓冲区末尾的指针。
gbump	一个受保护的函数，该函数将 count 添加到输入缓冲区的下一个指针。
getloc	获取 basic_streambuf 对象的区域设置。
gptr	一个受保护的函数，该函数返回指向输入缓冲区的下一个元素的指针。
imbue	由 pubimbue 调用的受保护虚拟函数。
in_avail	返回可随时从缓冲区读取的元素数目。
overflow	将新字符插入到已满缓冲区时可以调用的受保护虚函数。
pbackfail	一个受保护虚拟成员函数，该函数尝试将元素放回输入流中，随后使它成为当前元素（由下一个指针指向）。
pbase	一个受保护的函数，该函数返回指向输出缓冲区开头的指针。
pbump	一个受保护的函数，该函数将 count 添加到输出缓冲区的下一个指针。
pptr	一个受保护的函数，该函数返回指向输出缓冲区的下一个元素的指针。
pubimbue	设置 basic_streambuf 对象的区域设置。
pubseekoff	调用 seekoff，它是在派生类中进行了重写的受保护虚拟函数。
pubseekpos	调用 seekpos，它是在派生类中进行了重写并且重置了当前指针位置的受保护虚拟函数。
pubsetbuf	调用 setbuf，它是在派生类中进行了重写的受保护虚拟函数。
pubsync	调用 sync，它是在派生类中进行了重写并且更新了与此缓冲区关联的外部流的受保护虚拟函数。
sbumpc	读取并返回当前元素，从而移动流指针。
seekoff	受保护虚拟成员函数尝试更改受控制流的当前位置。
seekpos	受保护虚拟成员函数尝试更改受控制流的当前位置。
setbuf	受保护虚拟成员函数执行特定于每个派生流缓冲区的操作。
setg	一个受保护的函数，该函数将 _Gbeg 存储到开始指针，将 _Gnext 存储到下一个指针，并将 _Gend 存储到输入缓冲区的结束指针。
setp	一个受保护的函数，该函数将 _Pbeg 存储到开始指针，并将 _Pend 存储到输出缓冲区的结束指针。
sgetc	返回当前元素，但不更改流中的位置。
sgetn	返回读取的元素数目。
showmanyc	一个受保护的虚拟成员函数，该函数返回可以从输入流中提取的字符数计数。 它还确保程序不会无限期等待。
snextc	读取当前元素并返回以下元素。
sputbackc	将 char_type 放入流中。
sputc	将一个字符放入流中。
sputn	将一个字符串放入流中。
stossc	越过流中的当前元素。
sungetc	从流中获取字符。
swap	将此对象中的值与所提供 basic_streambuf 对象参数中的值进行交换。
sync	一个受保护的虚拟函数，它尝试将受控流与任何关联的外部流同步。
uflow	一个受保护的虚拟函数，它从输入流中提取当前元素。
underflow	一个受保护的虚拟函数，它从输入流中提取当前元素。
xsgetn	一个受保护的虚拟函数，它从输入流中提取元素。
xsputn	一个受保护的虚拟函数，它将元素插入到输出流中。

运算符

运算符	说明
operator=	从另一个 basic_streambuf 对象为此对象赋值。

要求

标头：<streambuf>

命名空间： std

basic_streambuf::basic_streambuf

构造 basic_streambuf 类型的对象。

basic_streambuf();

basic_streambuf(const basic_streambuf& right);

参数

right
对用于为此 basic_streambuf 对象设置值的 basic_streambuf 对象的左值引用。

备注

第一个受保护构造函数将 null 指针存储在控制输入缓冲区和输出缓冲区的所有指针中。 此外，它还将 locale::classic 存储在区域设置对象中。 有关详细信息，请参见 locale::classic。

第二个受保护构造函数会从 right 复制指针和区域设置。

basic_streambuf::char_type

将类型名与 Elem 模板参数关联。

typedef Elem char_type;

basic_streambuf::eback

一个受保护的函数，该函数返回指向输入缓冲区开头的指针。

char_type *eback() const;

返回值

指向输入缓冲区开头的指针。

basic_streambuf::egptr

一个受保护的函数，该函数返回超出输入缓冲区末尾的指针。

char_type *egptr() const;

返回值

超出输入缓冲区末尾的指针。

basic_streambuf::epptr

一个受保护的函数，该函数返回超出输出缓冲区末尾的指针。

char_type *epptr() const;

返回值

超出输出缓冲区末尾的指针。

basic_streambuf::gbump

一个受保护的函数，该函数将 count 添加到输入缓冲区的下一个指针。

void gbump(int count);

参数

count
让指针前进的量。

basic_streambuf::getloc

获取 basic_streambuf 对象的区域设置。

locale getloc() const;

返回值

存储的区域设置对象。

备注

相关信息，请参阅 ios_base::getloc。

示例

// basic_streambuf_getloc.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   cout << cout.rdbuf( )->getloc( ).name( ).c_str( ) << endl;
}

C

basic_streambuf::gptr

一个受保护的函数，该函数返回指向输入缓冲区的下一个元素的指针。

char_type *gptr() const;

返回值

指向输入缓冲区下一个元素的指针。

basic_streambuf::imbue

由 pubimbue 调用的受保护虚拟函数。

virtual void imbue(const locale& _Loc);

参数

_Loc
对区域设置的引用。

备注

默认行为是不执行任何操作。

basic_streambuf::in_avail

返回可随时从缓冲区读取的元素数目。

streamsize in_avail();

返回值

可随时从缓冲区读取的元素数目。

备注

如果 read position 是变量，则成员函数将返回 egptr - gptr。 否则，将返回 showmanyc。

示例

// basic_streambuf_in_avail.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   char c;
   // cin's buffer is empty, in_avail will return 0
   cout << cin.rdbuf( )->in_avail( ) << endl;
   cin >> c;
   cout << cin.rdbuf( )->in_avail( ) << endl;
}

basic_streambuf::int_type

将 basic_streambuf 作用域内的类型名称与模板参数中的其中一个类型相关联。

typedef typename traits_type::int_type int_type;

basic_streambuf::off_type

将 basic_streambuf 作用域内的类型名称与模板参数中的其中一个类型相关联。

typedef typename traits_type::off_type off_type;

basic_streambuf::operator=

从另一个 basic_streambuf 对象为此对象赋值。

basic_streambuf& operator=(const basic_streambuf& right);

参数

right
对用于为此对象赋值的 basic_streambuf 对象的左值引用。

备注

受保护的成员运算符从 right（控制输入缓冲区和输出缓冲区的指针）进行复制。 它还将 right.getloc() 存储在 locale object 中。 它将返回 *this。

basic_streambuf::overflow

将新字符插入到已满缓冲区时可以调用的受保护虚函数。

virtual int_type overflow(int_type _Meta = traits_type::eof());

参数

_Meta
要插入到缓冲区中的字符或 traits_type::eof。

返回值

如果该函数不能成功，它将返回 traits_type::eof 或引发异常。 否则，它将返回 traits_type::not_eof(_ Meta)。 默认行为是返回 traits_type::eof。

注解

如果 _Meta 不等于 traits_type::eof，则受保护虚拟成员函数将尝试向输出流中插入元素 traits_type::to_char_type(_Meta)。 它可以用多种方法执行此操作：

• 如果 write position 可用，它可将元素存储到写入位置并增加输出缓冲区的下一个指针。

• 它可以通过为输出缓冲区分配新的或额外的存储空间，提供写入位置。

• 可以通过写出到某些外部目标、输出缓冲区的开头和下一个指针之间的某些或所有元素使写入位置可用。

虚拟溢出函数，以及 sync 和 underflow 函数，共同定义了 streambuf 派生的类的特征。 每个派生的类实现下溢的方式可能不同，但是调用流类的接口是相同的。

在 put 区域为满时，overflow 函数最常由公共 streambuf 函数（如 sputc 和 sputn）调用，但其他类（包括流类）可以在任何时候调用 overflow。

该函数使用 pbase 和 pptr 指针之间 put 区域中的字符，然后重新初始化 put 区域。 overflow 函数必须也使用 nCh（如果 nCh 不为 EOF），或者，它可能选择将该字符放入新的 put 区域，以便在下一次调用时使用它。

使用的定义根据派生的类而有所不同。 例如，filebuf 类将其字符写入到文件，而 strstreambuf 类则将字符保留在它的缓冲区中，并且（缓冲区被指定为动态）扩展缓冲区，以响应溢出的调用。 此扩展通过释放旧的缓冲区并将其替换为新的、较大的缓冲区来实现。 根据需要调整指针。

basic_streambuf::pbackfail

一个受保护虚拟成员函数，该函数尝试将元素放回输入流中，随后使它成为当前元素（由下一个指针指向）。

virtual int_type pbackfail(int_type _Meta = traits_type::eof());

参数

_Meta
要插入到缓冲区中的字符或 traits_type::eof。

返回值

如果该函数不能成功，它将返回 traits_type::eof 或引发异常。 否则，将返回其他值。 默认行为是返回 traits_type::eof。

备注

如果 _Meta 等于 traits_type::eof，要推送回的元素在当前元素之前实际上已是流中的一个元素了。 否则，由 traits_type::to_char_type(_Meta) 替换该元素。 该函数可以用多种方法放回元素：

• 如果放回位置可用，它可将元素存储到放回位置并递减输入缓冲区的下一个指针。

• 通过分配输入缓冲区的新的或其他存储使放回位置可用。

• 对于具有常见的输入和输出流的流缓冲区，可以通过写出到某些外部目标、输出缓冲区的开头和下一个指针之间的某些或所有元素使放回位置可用。

basic_streambuf::pbase

一个受保护的函数，该函数返回指向输出缓冲区开头的指针。

char_type *pbase() const;

返回值

指向输出缓冲区开头的指针。

basic_streambuf::pbump

一个受保护的函数，该函数将 count 添加到输出缓冲区的下一个指针。

void pbump(int count);

参数

count
向前移动写入位置的字符数。

basic_streambuf::pos_type

将 basic_streambuf 作用域内的类型名称与模板参数中的其中一个类型相关联。

typedef typename traits_type::pos_type pos_type;

basic_streambuf::pptr

一个受保护的函数，该函数返回指向输出缓冲区的下一个元素的指针。

char_type *pptr() const;

返回值

指向输出缓冲区下一个元素的指针。

basic_streambuf::pubimbue

设置 basic_streambuf 对象的区域设置。

locale pubimbue(const locale& _Loc);

参数

_Loc
对区域设置的引用。

返回值

存储在区域设置对象中的以前的值。

备注

成员函数将 _ Loc 存储在区域设置对象中，并调用 imbue。

示例

有关使用 pubimbue 的示例，请参阅 basic_ios::imbue。

basic_streambuf::pubseekoff

调用 seekoff，它是在派生类中进行了重写的受保护虚拟函数。

pos_type pubseekoff(off_type _Off,
    ios_base::seekdir _Way,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

参数

_Off
要搜寻的相对于 _Way 的位置。

_Way
偏移操作的起点。 请参阅 seekdir，查看可能的值。

_Which
指定指针位置的模式。 默认允许修改读取和写入位置。

返回值

返回新位置或无效的流位置 (seekoff(_ Off, _Way, _Which))。

备注

移动相对于 _Way 的指针。

basic_streambuf::pubseekpos

调用 seekpos，它是在派生类中进行了重写并且重置了当前指针位置的受保护虚拟函数。

pos_type pubseekpos(pos_type _Sp, ios_base::openmode _Which = ios_base::in | ios_base::out);

参数

_Sp
要搜寻的位置。

_Which
指定指针位置的模式。 默认允许修改读取和写入位置。

返回值

新位置或无效的流位置。 若要确定流位置是否有效，请比较返回值和 pos_type(off_type(-1))。

备注

此成员函数返回 seekpos(_ Sp, _Which)。

basic_streambuf::pubsetbuf

调用 setbuf，它是在派生类中进行了重写的受保护虚拟函数。

basic_streambuf<Elem, Tr> *pubsetbuf(
    char_type* _Buffer,
    streamsize count);

参数

_Buffer
指向此实例化的 char_type 的指针。

count
缓冲区的大小。

返回值

返回 setbuf( _Buffer, count)。

basic_streambuf::pubsync

调用 sync，它是在派生类中重写并更新了与此缓冲区相关联的外部流的受保护虚拟函数。

int pubsync();

返回值

返回 sync，如果失败，则返回 -1。

basic_streambuf::sbumpc

读取并返回当前元素，从而移动流指针。

int_type sbumpc();

返回值

当前元素。

备注

如果读取位置可用，则成员函数返回 traits_type::to_int_type(*gptr) 并递增输入缓冲区的下一个指针。 否则，返回 uflow。

示例

// basic_streambuf_sbumpc.cpp
// compile with: /EHsc
#include <iostream>

int main( )
{
   using namespace std;
   int i = 0;
   i = cin.rdbuf( )->sbumpc( );
   cout << i << endl;
}

3

33
51

basic_streambuf::seekoff

一个受保护的虚拟成员函数，它尝试更改受控流的当前位置。

virtual pos_type seekoff(
    off_type _Off,
    ios_base::seekdir _Way,
    ios_base::openmode _Which = ios_base::in | ios_base::out);

参数

_Off
要搜寻的相对于 _Way 的位置。

_Way
偏移操作的起点。 请参阅 seekdir，查看可能的值。

_Which
指定指针位置的模式。 默认允许修改读取和写入位置。

返回值

返回新位置或无效的流位置 (seekoff (_ Off, _Way, _Which))。

备注

确定新的位置，如下所示：

• 如果 _Way == ios_base::beg，新位置是流的开始位置加上 _ Off。

• 如果 _Way == ios_base::cur，新位置是当前流位置加上 _Off。

• 如果 _Way == ios_base::end，新的位置是当前流末尾加上 _Off。

通常情况下，如果 which & ios_base::in 为非零值，则输入流受影响；如果 which & ios_base::out 为非零值，则输出流受影响。 但是，此参数的实际用法因派生的流缓冲区而有所不同。

如果该函数成功改变了一个或多个流位置，它将返回结果流位置或其中一个结果流位置。 否则，返回一个无效的流位置。 默认行为是返回无效的流位置。

basic_streambuf::seekpos

一个受保护的虚拟成员函数，它尝试更改受控流的当前位置。

virtual pos_type seekpos(pos_type _Sp, ios_base::openmode _Which = ios_base::in | ios_base::out);

参数

_Sp
要搜寻的位置。

_Which
指定指针位置的模式。 默认允许修改读取和写入位置。

返回值

新位置，或无效的流位置。 若要确定流位置是否有效，请比较返回值和 pos_type(off_type(-1))。

备注

新的位置是 _ Sp。

通常情况下，如果 which & ios_base::in 为非零值，则输入流受影响；如果 which & ios_base::out 为非零值，则输出流受影响。 但是，此参数的实际用法因派生的流缓冲区而有所不同。

如果该函数成功改变了一个或多个流位置，它将返回结果流位置或其中一个结果流位置。 否则，返回一个无效的流位置 (-1)。 默认行为是返回无效的流位置。

basic_streambuf::setbuf

受保护虚拟成员函数，执行特定于每个派生流缓冲区的操作。

virtual basic_streambuf<Elem, Tr> *setbuf(
    char_type* _Buffer,
    streamsize count);

参数

_Buffer
指向缓冲区的指针。

count
缓冲区的大小。

返回值

默认行为是返回 this。

注解

请参阅 basic_filebuf。 setbuf 提供一个内存区域，以供 streambuf 对象使用。 在派生类中定义的缓冲区的使用方式。

basic_streambuf::setg

一个受保护函数，用于将 _Gbeg 存储到开始指针，将 _Gnext 存储到下一个指针，并将 _Gend 存储到输入缓冲区的结束指针。

void setg(char_type* _Gbeg,
    char_type* _Gnext,
    char_type* _Gend);

参数

_Gbeg
指向缓冲区开头的指针。

_Gnext
指向缓冲区中间某处的指针。

_Gend
指向缓冲区末尾的指针。

basic_streambuf::setp

一个受保护的函数，该函数将 _Pbeg 存储到开始指针，并将 _Pend 存储到输出缓冲区的结束指针。

void setp(char_type* _Pbeg, char_type* _Pend);

参数

_Pbeg
指向缓冲区开头的指针。

_Pend
指向缓冲区末尾的指针。

basic_streambuf::sgetc

返回当前元素，但不更改流中的位置。

int_type sgetc();

返回值

当前元素。

备注

如果读取位置可用，则成员函数返回 traits_type::to_int_type( *gptr)。 否则，返回 underflow。

示例

// basic_streambuf_sgetc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;
   ifstream myfile( "basic_streambuf_sgetc.txt", ios::in );

   char i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
   i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
}

basic_streambuf::sgetn

最多从输入缓冲区提取 count 个字符，并将其存储在提供的缓冲区 ptr 中

此方法可能并不安全，因为它依赖于调用方检查所传递的值是否正确。

streamsize sgetn(
    char_type* ptr,
    streamsize count);

参数

ptr
要包含提取字符的缓冲区。

count
要读取的元素数目。

返回值

要读取的元素数目。 有关详细信息，请参阅 streamsize。

注解

此成员函数返回 xsgetn( ptr, count)。

示例

// basic_streambuf_sgetn.cpp
// compile with: /EHsc /W3
#include <iostream>
#include <fstream>

int main()
{
    using namespace std;

    ifstream myfile("basic_streambuf_sgetn.txt", ios::in);
    char a[10];

    // Extract 3 characters from myfile and store them in a.
    streamsize i = myfile.rdbuf()->sgetn(&a[0], 3);  // C4996
    a[i] = myfile.widen('\0');

    // Display the size and contents of the buffer passed to sgetn.
    cout << i << " " << a << endl;

    // Display the contents of the original input buffer.
    cout << myfile.rdbuf() << endl;
}

basic_streambuf::showmanyc

一个受保护虚拟成员函数，该函数返回可以从输入流中提取并确保该程序不会无限期等待的字符数计数。

virtual streamsize showmanyc();

返回值

默认行为是返回零。

basic_streambuf::snextc

读取当前元素并返回以下元素。

int_type snextc();

返回值

流中的下一个元素。

注解

成员函数调用 sbumpc，如果该函数返回 traits_type::eof，则返回 traits_type::eof。 否则，返回 sgetc。

示例

// basic_streambuf_snextc.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
   using namespace std;
   int i = 0;
   i = cin.rdbuf( )->snextc( );
   // cout << ( int )char_traits<char>::eof << endl;
   cout << i << endl;
}

aa

aa97

basic_streambuf::sputbackc

将 char_type 放入流中。

int_type sputbackc(char_type _Ch);

参数

_Ch
字符。

返回值

返回字符或失败。

备注

如果放回位置可用，且 _Ch 与存储在该位置的字符相等，则成员函数递减输入缓冲区的下一个指针，并返回 traits_type::to_int_type( _Ch)。 否则，它将返回 pbackfail( _Ch)。

示例

// basic_streambuf_sputbackc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
    using namespace std;

    ifstream myfile("basic_streambuf_sputbackc.txt",
        ios::in);

    int i = myfile.rdbuf()->sbumpc();
    cout << (char)i << endl;
    int j = myfile.rdbuf()->sputbackc('z');
    if (j == 'z')
    {
        cout << "it worked" << endl;
    }
    i = myfile.rdbuf()->sgetc();
    cout << (char)i << endl;
}

basic_streambuf::sputc

将一个字符放入流中。

int_type sputc(char_type _Ch);

参数

_Ch
字符。

返回值

如果成功，则返回字符。

注解

如果 write position 可用，则成员函数在写入位置存储 _Ch，递增输出缓冲区的下一个指针，并返回 traits_type::to_int_type( _Ch)。 否则，返回 overflow( _Ch)。

示例

// basic_streambuf_sputc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;

   int i = cout.rdbuf( )->sputc( 'a' );
   cout << endl << ( char )i << endl;
}

a
a

basic_streambuf::sputn

将一个字符串放入流中。

streamsize sputn(const char_type* ptr, streamsize count);

参数

ptr
字符串。

count
字符数。

返回值

插入流的字符数。

备注

此成员函数返回 xsgetn( ptr, count)。 有关详细信息，请参阅此成员的“备注”部分。

示例

// basic_streambuf_sputn.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main()
{
    using namespace std;

    streamsize i = cout.rdbuf()->sputn("test", 4);
    cout << endl << i << endl;
}

test
4

basic_streambuf::stossc

越过流中的当前元素。

void stossc();

备注

成员函数调用 sbumpc。 提供该成员函数不需要实现。

示例

// basic_streambuf_stossc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;
   ifstream myfile( "basic_streambuf_stossc.txt", ios::in );

   myfile.rdbuf( )->stossc( );
   char i = myfile.rdbuf( )->sgetc( );
   cout << i << endl;
}

basic_streambuf::sungetc

从流中获取字符。

int_type sungetc();

返回值

返回字符或失败。

备注

如果放回位置可用，则成员函数递减输入缓冲区的下一个指针并返回 traits_type::to_int_type( *gptr)。 但是，并不总是能够确定读取的最后一个字符，使得可以在当前缓冲区的状态中将其捕获。 如果这为 true，则函数返回 pbackfail。 若要避免这种情况，请跟踪字符，以放回并调用 sputbackc(ch)；如果没有在流的开始位置对其调用或尝试放回多个字符，则此调用不会失败。

示例

// basic_streambuf_sungetc.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>

int main( )
{
   using namespace std;

   ifstream myfile( "basic_streambuf_sungetc.txt", ios::in );

   // Read and increment
   int i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;

   // Read and increment
   i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;

   // Decrement, read, and do not increment
   i = myfile.rdbuf( )->sungetc( );
   cout << ( char )i << endl;

   i = myfile.rdbuf( )->sungetc( );
   cout << ( char )i << endl;

   i = myfile.rdbuf( )->sbumpc( );
   cout << ( char )i << endl;
}

basic_streambuf::swap

将此对象中的值与提供的 basic_streambuf 对象中的值进行交换。

void swap(basic_streambuf& right);

参数

right
对用于交换值的 basic_streambuf 对象的左值引用。

备注

受保护的成员函数可与 right（控制 input buffer 和 output buffer 的所有指针）进行交换。 它还将 right.getloc() 与 locale 对象进行交换。

basic_streambuf::sync

一个受保护的虚拟函数，它尝试将受控流与任何关联的外部流同步。

virtual int sync();

返回值

如果该函数不成功，它将返回 -1。 默认行为是返回零。

备注

sync 涉及写出输出缓冲区的开头和下一个指针间的任意元素。 它不涉及放回输入缓冲区的下一个和结束指针之间的任何元素。

basic_streambuf::traits_type

将类型名与 Tr 模板参数关联。

typedef Tr traits_type;

basic_streambuf::uflow

一个受保护的虚拟函数，它从输入流中提取当前元素。

virtual int_type uflow();

返回值

当前元素。

注解

受保护虚拟成员函数尝试从输入流提取当前元素 ch，提升当前流位置，并返回元素作为 traits_type::to_int_type( ch)。 它可以用多种方法执行此操作：

• 如果读取位置可用，它采用 ch 作为存储在读取位置中的元素，并提升输入缓冲区的下一个指针。

• 它可以从某些外部源直接读取元素，并将其传输为值 ch。

• 对于具有常见的输入和输出流的流缓冲区，可以通过写出到某些外部目标、输出缓冲区的开头和下一个指针之间的某些或所有元素使读取位置可用。 或者，可以为输入缓冲区分配新的或其他存储。 然后，该函数从某些外部源的一个或多个元素中进行读取。

如果该函数不能成功，它将返回 traits_type::eof 或引发异常。 否则，它返回输入流中的当前元素 ch，按上文所述进行转换，并提升输入缓冲区的下一个指针。 默认行为是调用 underflow，并且，如果该函数返回 traits_type::eof，则返回 traits_type::eof。 否则，它返回输入流中的当前元素 ch，按上文所述进行转换，并为输入缓冲区提升下一个指针。

basic_streambuf::underflow

受保护虚函数从输入流中提取当前元素。

virtual int_type underflow();

返回值

当前元素。

注解

受保护虚拟成员函数从输入流提取当前元素 ch，而不会提升当前流位置，并将其返回为 traits_type::to_int_type( ch)。 它可以用多种方法执行此操作：

• 如果读取位置可用，则 ch 为存储在读取位置的元素。 有关详细信息，请参阅 basic_streambuf 类的备注部分。

• 通过为输入缓冲区分配新的或其他存储，然后从某些外部源中读取一个或多个元素使读取位置可用。 有关详细信息，请参阅 basic_streambuf 类的备注部分。

如果该函数不能成功，它将返回 traits_type::eof() 或引发异常。 否则，它返回输入流中的当前元素，并根据前文所述进行转换。 默认行为是返回 traits_type::eof()。

虚拟 underflow 函数，以及 sync 和 overflow 函数，共同定义 streambuf 派生的类的特征。 每个派生的类实现 underflow 的方式可能不同，但是调用流类的接口是相同的。

在 get 区域为空时，underflow 函数最常由公共 streambuf 函数调用，如 sgetc 和 sgetn，但其他类（包括流类）可以在任何时候调用 underflow。

underflow 函数为 get 区域提供来自输入源的字符。 如果 get 区域包含字符，则 underflow 返回第一个字符。 如果 get 区域为空，则填充 get 区域并返回下一个字符（即留在 get 区域中的字符）。 如果没有更多可用的字符，则 underflow 返回 EOF 并将 get 区域留空。

在 strstreambuf 类中，underflow 调整 egptr 指针，以访问由调用 overflow 动态分配的存储。

basic_streambuf::xsgetn

一个受保护虚拟函数，它从输入流中提取元素。

此方法可能并不安全，因为它依赖于调用方检查所传递的值是否正确。

virtual streamsize xsgetn(
    char_type* ptr,
    streamsize count);

参数

ptr
要包含提取字符的缓冲区。

count
要提取的元素数。

返回值

已提取的元素数。

备注

此受保护虚拟成员函数最多将从输入流提取 count 个元素，这与从以 ptr 开头的数组重复调用 sbumpc 并存储元素类似。 它返回已提取的元素数。

basic_streambuf::xsputn

受保护虚拟函数，它将元素插入到输出流中。

virtual streamsize xsputn(const char_type* ptr, streamsize count);

参数

ptr
指向要插入的元素的指针。

count
要插入的元素数。

返回值

插入到流的元素数。

备注

此受保护虚拟成员函数最多将 count 个元素插入输出流，这与从以 ptr 开头的数组重复调用 sputc 类似。 当所有 count 个字符已被写入或如果调用 sputc( count) 将返回 traits::eof() 时，输出流的字符插入立即停止。 它返回已插入的元素数。

另请参阅

C++ 标准库中的线程安全
iostream 编程
iostreams 约定