strstreambuf 类

项目
06/16/2023

描述一种流缓冲区，它对存储在 char 数组对象中的元素和元素序列之间的来回传输进行控制。

语法

class strstreambuf : public streambuf

备注

可在必要时对它进行分配、扩展和释放以适应序列中的更改，具体取决于对象的构造方式。

类 strstreambuf 的对象将模式信息的几个位存储为其 strstreambuf 模式。这些位指示受控序列是否：

已分配且最后需要释放。
是可修改的。
可通过重新分配存储进行扩展。
已被冻结并因此需要在对象被销毁前进行解冻，或者已由不是对象的某个代理释放（若已分配）。

无论这些单独模式位的状态如何，都不能修改或扩展已冻结的受控序列。

此对象还存储指向控制 strstreambuf 分配的两个函数的指针。如果这些指针都是空指针，则对象会自行设计用于分配和释放受控序列存储的方法。

注意

此类已弃用。请考虑改为使用 stringbuf 或 wstringbuf。

构造函数

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

成员函数

成员函数	说明
freeze	导致无法通过流缓冲区操作使用流缓冲区。
overflow	将新字符插入到已满缓冲区时可以调用的受保护虚函数。
pbackfail	一个受保护的虚拟成员函数，该函数尝试将元素放回到输入流，然后使它成为当前元素（由下一个指针指向）。
pcount	返回写入到受控序列的元素计数。
seekoff	一个受保护的虚拟成员函数，它尝试更改受控流的当前位置。
seekpos	一个受保护的虚拟成员函数，它尝试更改受控流的当前位置。
str	调用 freeze，然后将返回指向受控序列开头的指针。
underflow	一个受保护的虚拟函数，用于从输入流中提取当前元素。

要求

标头：<strstream>

命名空间： std

strstreambuf::freeze

导致无法通过流缓冲区操作使用流缓冲区。

void freeze(bool _Freezeit = true);

参数

_Freezeit
bool 指示是否要冻结流。

注解

如果 _Freezeit 为 true，该函数将更改存储的 strstreambuf 模式以冻结受控序列。否则，不能冻结受控序列。

str 意味着 freeze。

注意

在 strstreambuf 析构期间不会释放冻结的缓冲区。释放缓冲区之前，必须解除对它的冻结，避免内存泄漏。

示例

// strstreambuf_freeze.cpp
// compile with: /EHsc

#include <iostream>
#include <strstream>

using namespace std;

void report(strstream &x)
{
    if (!x.good())
        cout << "stream bad" << endl;
    else
        cout << "stream good" << endl;
}

int main()
{
    strstream x;

    x << "test1";
    cout << "before freeze: ";
    report(x);

    // Calling str freezes stream.
    cout.write(x.rdbuf()->str(), 5) << endl;
    cout << "after freeze: ";
    report(x);

    // Stream is bad now, wrote on frozen stream
    x << "test1.5";
    cout << "after write to frozen stream: ";
    report(x);

    // Unfreeze stream, but it is still bad
    x.rdbuf()->freeze(false);
    cout << "after unfreezing stream: ";
    report(x);

    // Clear stream
    x.clear();
    cout << "after clearing stream: ";
    report(x);

    x << "test3";
    cout.write(x.rdbuf()->str(), 10) << endl;

    // Clean up.  Failure to unfreeze stream will cause a
    // memory leak.
    x.rdbuf()->freeze(false);
}

before freeze: stream good
test1
after freeze: stream good
after write to frozen stream: stream bad
after unfreezing stream: stream bad
after clearing stream: stream good
test1test3

strstreambuf::overflow

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

virtual int overflow(int _Meta = EOF);

参数

_Meta
要插入到缓冲区的字符或 EOF。

返回值

如果该函数不成功，它将返回 EOF。否则，如果 _Meta == EOF，它将返回不是 EOF 的其他值。否则，返回 _Meta。

备注

如果 _Meta != EOF，受保护的虚拟成员函数会尝试将元素 (char)_Meta 插入到输出缓冲区。它可以用多种方法执行此操作：

如果写入位置可用，它可将元素存储到写入位置并增加输出缓冲区的下一个指针。
如果存储的 strstreambuf 模式指出受控的序列可修改、可扩展且未被冻结，则该函数通过向输出缓冲区分配新的序列，生成写入位置。以这种方式扩展输出缓冲区还会扩展任何关联的输入缓冲区。

strstreambuf::pbackfail

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

virtual int pbackfail(int _Meta = EOF);

参数

_Meta
要插入到缓冲区的字符或 EOF。

返回值

如果该函数不成功，它将返回 EOF。否则，如果 _Meta == EOF，它将返回不是 EOF 的其他值。否则，返回 _Meta。

备注

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

如果 _Meta == EOF，要推送回的元素在当前元素之前实际上已是流中的一个元素了。否则，该元素被替换为 ch = (char)_Meta。该函数可以用多种方法放回元素：

如果放回的位置可用，且存储在该位置的元素等于 ch，则它可以递减输入缓冲区中的下一个指针。
如果放回的位置可用且 strstreambuf 模式指出受控的序列是可修改的，则该函数可以将 ch 存储到放回位置并递减输入缓冲区中的下一个指针。

strstreambuf::pcount

返回写入到受控序列的元素计数。

streamsize pcount() const;

返回值

写入到受控序列的元素计数。

备注

具体而言，如果 pptr 是空指针，该函数将返回零。否则，返回 pptr - pbase。

示例

// strstreambuf_pcount.cpp
// compile with: /EHsc
#include <iostream>
#include <strstream>
using namespace std;

int main( )
{
   strstream x;
   x << "test1";
   cout << x.rdbuf( )->pcount( ) << endl;
   x << "test2";
   cout << x.rdbuf( )->pcount( ) << endl;
}

strstreambuf::seekoff

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

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

参数

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

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

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

返回值

如果此函数成功更改任何一个流位置或两个流位置，则返回结果流位置。否则，如果失败将返回一个无效的流位置。

注解

受保护虚拟成员函数尝试更改受控流的当前位置。对于 strstreambuf 类的对象，流位置仅包含流偏移量。如果偏移量为零，将指定受控序列的第一个元素。

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

如果 _Way == ios_base::beg，则新位置是流的开始位置加上 _Off。
如果 _Way == ios_base::cur，则新位置是当前流位置加上 _Off。
如果 _Way == ios_base::end，则新位置是流末尾位置加上 _Off。

如果 _Which & ios_base::in 为非零值且存在输入缓冲区，则该函数将更改输入缓冲区中的下一个读取位置。如果 _Which & ios_base::out 也为非零值 _Way != ios_base::cur 且存在输出缓冲区，则该函数还将设置下一个写入位置以便匹配下一个读取位置。

否则，如果 _Which & ios_base::out 为非零值且存在输出缓冲区，则该函数将更改输出缓冲区中的下一个写入位置。否则，定位操作将失败。若要成功执行定位操作，则结果流的位置必须位于受控序列内。

strstreambuf::seekpos

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

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

参数

_Sp
要搜寻的位置。

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

返回值

如果此函数成功更改任何一个流位置或两个流位置，则返回结果流位置。否则，如果失败将返回一个无效的流位置。若要确定流位置是否有效，请比较返回值和 pos_type(off_type(-1))。

备注

受保护虚拟成员函数尝试更改受控流的当前位置。对于 strstreambuf 类的对象，流位置仅包含流偏移量。如果偏移量为零，将指定受控序列的第一个元素。新位置由 _Sp 确定。

如果 _Which 和ios_base::in 为非零值且存在输入缓冲区，则该函数将更改输入缓冲区中的下一个读取位置。如果 _Which 和 ios_base::out 为非零值且存在输出缓冲区，则该函数还将设置下一个写入位置以便匹配下一个读取位置。否则，如果 _Which 和 ios_base::out 为非零值且存在输出缓冲区，则该函数将更改输出缓冲区中的下一个写入位置。否则，定位操作将失败。若要成功执行定位操作，则结果流的位置必须位于受控序列内。

strstreambuf::str

调用 freeze，然后将返回指向受控序列开头的指针。

char *str();

返回值

指向受控序列的开头的指针。

注解

不存在终止的空元素，除非显式插入一个。

示例

有关使用 str 的示例，请参阅 strstreambuf::freeze。

strstreambuf::strstreambuf

构造 strstreambuf 类型的对象。

explicit strstreambuf(streamsize count = 0);

strstreambuf(void (* alloc_func)(size_t),
    void (* free_func)(void*));

strstreambuf(char* getptr,
    streamsize count,
    char* putptr = 0);

strstreambuf(signed char* getptr,
    streamsize count,
    signed char* putptr = 0);

strstreambuf(unsigned char* getptr,
    streamsize count,
    unsigned char* putptr = 0);

strstreambuf(const char* getptr,
    streamsize count);

strstreambuf(const signed char* getptr,
    streamsize count);

strstreambuf(const unsigned char* getptr,
    streamsize count);

参数

alloc_func
用以分配缓冲区内存的函数。

count
确定 getptr 指向的缓冲区长度。如果 getptr 不是参数（第一个构造函数格式），则为建议的缓冲区分配大小。

_Freefunc
用来释放缓冲区内存的函数。

getptr
用于输入的缓冲区。

putptr
用于输出的缓冲区。

注解

第一个构造函数将空指针存储在所有控制输入缓冲区、输出缓冲区和 strstreambuf 分配的指针中。该函数可设置存储的 strstreambuf 模式，使受控序列可修改和可扩展。它还会接受 count 作为建议的初始分配大小。

第二个构造函数与第一个类似，只不过它将 alloc_func 存储为用于调用来分配存储的函数的指针，将 free_func 存储为用于调用来释放该存储的函数的指针。

这三个构造函数为：

strstreambuf(char *getptr,
    streamsize count,
    char *putptr = 0);

strstreambuf(signed char *getptr,
    streamsize count,
    signed char *putptr = 0);

strstreambuf(unsigned char *getptr,
    streamsize count,
    unsigned char *putptr = 0);

同样与第一个构造函数类似，只不过 getptr 指定用来存储受控序列的数组对象。（因此，它不能为空指针。）数组中 N 元素的数量按以下方式确定：

如果 (count> 0)，则 N 为 count。
如果 (count == 0)，则 N 为 strlen((const char *) getptr )。
如果 (count< 0)，则 N 为 INT_MAX。

如果 putptr 是空指针，该函数通过执行指令建立输入缓冲区：

setg(getptr,
    getptr,
    getptr + N);

否则，它将通过执行以下指令建立输入和输出缓冲区：

setg(getptr,
    getptr,
    putptr);

setp(putptr,
    getptr + N);

在此情况下，putptr 必须在 [ getptr, getptr + N] 区间内。

最后，这三个构造函数为：

strstreambuf(const char *getptr,
    streamsize count);

strstreambuf(const signed char *getptr,
    streamsize count);

strstreambuf(const unsigned char *getptr,
    streamsize count);

所有构造函数的行为都与以下项相同：

streambuf((char *)getptr, count);

只不过存储模式使受控序列既不可修改也不可扩展。

strstreambuf::underflow

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

virtual int underflow();

返回值

如果该函数不成功，它将返回 EOF。否则，它返回输入流中的当前元素，并根据上文所述进行转换。

备注

受保护的虚拟成员函数尝试从输入缓冲区提取当前元素 ch，然后提出当前流位置，并返回元素作为 (int)(unsigned char)ch。它只能以一种方式进行此操作：如果读取位置可用，它采用 ch 作为存储在读取位置中的元素，并提出输入缓冲区的下一个指针。

另请参阅

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

通过