strstreambuf 类

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

语法

class strstreambuf : public streambuf

备注

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

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

  • 已分配且最后需要释放。

  • 是可修改的。

  • 可通过重新分配存储进行扩展。

  • 已被冻结并因此需要在对象被销毁前进行解冻,或者已由不是对象的某个代理释放(若已分配)。

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

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

注意

此类已弃用。 请考虑改为使用 stringbufwstringbuf

构造函数

构造函数 说明
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 为非零值且存在输入缓冲区,则该函数将更改输入缓冲区中的下一个读取位置。 如果 _Whichios_base::out 为非零值且存在输出缓冲区,则该函数还将设置下一个写入位置以便匹配下一个读取位置。 否则,如果 _Whichios_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 约定