ios_base 类

此类描述了不依赖模板参数的输入和输出流通用的存储和成员函数。 （类模板 basic_ios 描述了什么是通用对象以及什么依赖于模板参数。）

ios_base 类的对象存储格式设置信息，其中包括：

• fmtflags 类型的对象中的格式标志。

• iostate 类型的对象中的异常掩码。

• int 类型的对象中的字段宽度。

• int 类型的对象中的显示精度。

• locale 类型对象中的 locale 对象。

• 两个可扩展数组，其中包含 long 和 void 类型的指针。

ios_base 类的对象还将流状态信息存储在 iostate 类型的对象和回调堆栈中。

成员

构造函数

名称	描述
ios_base	构造 ios_base 对象。

Typedef

名称	描述
event_callback	描述传递给 register_call 的函数。
fmtflags	用于指定输出外观的常数。
iostate	定义描述流状态的常数。
openmode	介绍如何与流进行交互。
seekdir	指定偏移操作的起始点。

枚举

名称	描述
event	指定事件类型。

常量

名称	描述
adjustfield	定义为 internal | left | right 的位掩码。
app	指定先查找到流末尾，再进行每个插入。
ate	指定当首次创建其控制的对象时查找到流末尾。
badbit	记录流缓冲区的完整性损失。
basefield	定义为 dec | hex | oct 的位掩码。
beg	指定相对于序列的开头进行查找。
binary	指定文件应读取为二进制流，而不是文本流。
boolalpha	指定以名称（如 true 和false）而不是以数字值插入或提取 bool 类型的对象。
cur	指定相对于序列中的当前位置进行查找。
dec	指定以十进制格式插入或提取整数值。
end	指定相对于序列的末尾进行查找。
eofbit	从流中提取时，记录文件尾。
failbit	记录一个从流中提取有效字段失败的操作。
fixed	指定以定点格式（无指数域）插入浮点值。
floatfield	定义为 fixed | scientific 的位掩码
goodbit	清除所有状态位。
hex	指定以十六进制格式插入或提取整数值。
in	指定从流中提取。
internal	通过在生成的数字字段内的某一点插入填充字符，填充字段宽度。
left	指定左对齐。
oct	指定以八进制格式插入或提取整数值。
out	指定插入到流。
right	指定右对齐。
scientific	指定以科学记数格式（具有一个指数域）插入浮点值。
showbase	指定插入一个显示已生成整数字段的基的前缀。
showpoint	指定在生成的浮点字段中无条件插入一个小数点。
showpos	指定在生成的非负数字段中插入一个加号。
skipws	指定在进行某些提取之前，先跳过前导空格。
trunc	指定在创建其控制的对象后，删除现有文件的内容。
unitbuf	将导致输出在每次插入后进行刷新。
uppercase	指定在某些插入操作中插入小写字母的大写等效项。

函数

名称	描述
failure	成员类用作 basic_ios 模板类中的 clear 成员函数引发的所有异常的基类。
flags	设置或返回当前的标志设置。
getloc	返回存储的 locale 对象。
imbue	更改区域设置。
Init	在构造时创建标准 iostream 对象。
iword	分配将存储为 iword 的值。
precision	指定浮点数中显示的位数。
pword	分配将存储为 pword 的值。
register_callback	指定一个回调函数。
setf	设置指定标志。
sync_with_stdio	确保 iostream 和 C 运行时库操作按照它们在源代码中出现的顺序发生。
unsetf	将导致指定的标志处于关闭状态。
width	设置输出流的长度。
xalloc	指定变量应为流的一部分。

运算符

名称	描述
operator=	ios_base 对象的赋值运算符。

要求

标头<ios>：

命名空间：std

event

指定事件类型。

enum event {
    erase_event,
    imbue_event,
    copyfmt_event};

备注

此类型是枚举的类型，该类型描述的对象可将作为参数使用的回调事件存储到使用 register_callback 注册的函数中。 非重复的事件值为：

• copyfmt_event，用来在复制异常掩码之前标识发生在 copyfmt 调用末尾附近的回调。

• erase_event，用来标识发生在 copyfmt 调用开始处或 *this 的析构函数调用开始处的回调。

• imbue_event，用来在函数返回前标识发生在 imbue 调用末尾处的回调。

示例

有关示例，请参见 register_callback。

event_callback

描述传递给 register_call 的函数。

typedef void (__cdecl *event_callback)(
    event _E,
    ios_base& _Base,
    int _I);

参数

_E
event。

_Base
其中调用了事件的流。

_I
用户定义的数字。

注解

此类型描述可使用 register_callback 注册的函数的指针。 此类函数不得引发任何异常。

示例

有关使用 event_callback 的示例，请参阅 register_call。

failure

根据 iostreams 库中的函数，类 failure 将引发的所有对象类型的基类定义为异常，以在流缓冲操作期间报告错误。

namespace std {
    class failure : public system_error {
    public:
        explicit failure(
            const string& _Message,
            const error_code& _Code = io_errc::stream);

        explicit failure(
            const char* str,
            const error_code& _Code = io_errc::stream);
    };
}

备注

what() 返回的值是 _Message 的一个副本，可能基于 _Code 通过测试进行了扩充。 如果未指定 _Code，则默认值为 make_error_code(io_errc::stream)。

示例

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

int main ( )
{
    using namespace std;
    fstream file;
    file.exceptions(ios::failbit);
    try
    {
        file.open( "rm.txt", ios_base::in );
        // Opens nonexistent file for reading
    }
    catch( ios_base::failure f )
    {
        cout << "Caught an exception: " << f.what() << endl;
    }
}

Caught an exception: ios_base::failbit set

flags

设置或返回当前的标志设置。

fmtflags flags() const;
fmtflags flags(fmtflags fmtfl);

参数

fmtfl
新的 fmtflags 设置。

返回值

先前或当前的 fmtflags 设置。

注解

有关标志的列表，请参阅ios_base::fmtflags。

第一个成员函数返回存储的格式标志。 第二个成员函数将 fmtfl 存储在格式标志中，并返回其先前的存储值。

示例

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

int main ( )
{
    using namespace std;
    cout << cout.flags( ) << endl;
    cout.flags( ios::dec | ios::boolalpha );
    cout << cout.flags( );
}

513
16896

fmtflags

用于指定输出外观的常数。

class ios_base {
public:
   typedef implementation-defined-bitmask-type fmtflags;
   static const fmtflags boolalpha;
   static const fmtflags dec;
   static const fmtflags fixed;
   static const fmtflags hex;
   static const fmtflags internal;
   static const fmtflags left;
   static const fmtflags oct;
   static const fmtflags right;
   static const fmtflags scientific;
   static const fmtflags showbase;
   static const fmtflags showpoint;
   static const fmtflags showpos;
   static const fmtflags skipws;
   static const fmtflags unitbuf;
   static const fmtflags uppercase;
   static const fmtflags adjustfield;
   static const fmtflags basefield;
   static const fmtflags floatfield;
   // ...
};

备注

支持 ios 中的操控器。

该类型是一个位掩码类型，它描述可存储格式标志的对象。 非重复的标志值（元素）为：

• dec，用于以十进制格式插入或提取整数值。

• hex，用于以十六进制格式插入或提取整数值。

• oct，用于以八进制格式插入或提取整数值。

• showbase，用于插入一个显示已生成整型域的基的前缀。

• internal，用于通过在生成的数字字段内的某一点插入填充字符，来根据需要填充字段宽度。 （有关设置字段宽度的信息，请参阅 setw）。

• left，用于通过在已生成字段的末尾插入填充字符（左对齐），来根据需要填充字段宽度。

• right，用于通过在已生成字段的开头插入填充字符（右对齐），来根据需要填充字段宽度。

• boolalpha，用于将类型 bool 的对象作为名称（如 true 和 false）而不是数值进行插入或提取。

• fixed，用于以固定点格式（不带指数字段）插入浮点值。

• scientific，用于以科学记数格式（不带指数域）插入浮点值。

• showpoint，用于在生成的浮点字段中无条件地插入十进制点。

• showpos，用于在生成的非负数字段中插入一个加号。

• skipws，用于在某些提取前跳过前导空格。

• unitbuf，用于在每次插入后刷新输出。

• uppercase，用于在某些插入中插入小写字母的大写等效项。

另外，还有些有用的值如下所示：

• adjustfield，定义为 internal | left | right 的位掩码

• basefield，定义为 dec | hex | oct

• floatfield，定义为 fixed | scientific

有关修改这些格式标志的函数的示例，请参阅 <iomanip>。

getloc

返回存储的 locale 对象。

locale getloc() const;

返回值

存储的 locale 对象。

示例

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

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

C

imbue

更改区域设置。

locale imbue(const locale& _Loc);

参数

_Loc
新的区域设置。

返回值

先前的区域设置。

备注

此成员函数将 _Loc 存储在 locale 对象中，然后报告回调事件和 imbue_event。 它返回先前的存储值。

示例

请参阅 basic_ios::imbue 了解示例。

Init

在构造时创建标准 iostream 对象。

class Init { };

备注

此嵌套类描述一个对象，该对象的构造可确保即使在执行任意静态对象的构造函数前也可正确构造标准 iostream 对象。

ios_base

构造 ios_base 对象。

ios_base();

备注

此（受保护）构造函数不会执行任何操作。 稍后对 basic_ios::init 的调用必须先初始化此对象，然后才可被安全销毁。 因此，ios_base 类唯一安全的用途是作为 basic_ios 类模板的基类。

iostate

描述流状态的常量的类型。

class ios_base {
public:
   typedef implementation-defined-bitmask-type iostate;
   static const iostate badbit;
   static const iostate eofbit;
   static const iostate failbit;
   static const iostate goodbit;
   // ...
};

备注

该类型是一个位掩码类型，它描述可存储流状态信息的对象。 非重复的标志值（元素）为：

• badbit（用于记录流缓冲区的完整性损失）。
• eofbit（用于在从流提取时记录文件尾）。
• failbit（用于记录一个从流中提取有效字段失败的操作）。

此外，goodbit 是一个很有用的值，其中未设置之前提及的任何位（goodbit 保证为 0）。

iword

分配将存储为 iword 的值。

long& iword(int idx);

参数

idx
要存储为 iword 的值的索引。

注解

此成员函数返回具有类型 long 指针的元素的可扩展数组的 idx 元素引用。 所有元素均有效存在，且起初会存储值 0。 下次调用此对象的 iword 后、对象由对 basic_ios::copyfmt 的调用更改后或者对象被销毁后，该返回引用将无效。

如果 idx 为负或唯一存储对该元素不可用，则此函数会调用 setstate(badbit) 并返回一个可能并不唯一的引用。

若要获取唯一索引以用于类型 ios_base 的所有对象，请调用 xalloc。

示例

有关如何使用 iword 的示例，请参阅 xalloc。

openmode

介绍如何与流进行交互。

class ios_base {
public:
   typedef implementation-defined-bitmask-type openmode;
   static const openmode  in;
   static const openmode  out;
   static const openmode  ate;
   static const openmode  app;
   static const openmode  trunc;
   static const openmode  binary;
   // ...
};

备注

多个 iostream 对象的打开模式。 标志值为：

常量	效果
app	在每次写入之前搜寻到流的末尾
ate	打开后立即搜寻到流的末尾
binary	在二进制模式下打开。 （有关二进制模式的说明，请参阅 fopen。）
in	打开以读取
out	打开以写入
trunc	打开后删除文件内容

示例

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

int main ( )
{
    using namespace std;
    fstream file;
    file.open( "rm.txt", ios_base::out | ios_base::trunc );

    file << "testing";
}

operator=

ios_base 对象的赋值运算符。

ios_base& operator=(const ios_base& right);

参数

right
一个 ios_base 类型的对象。

返回值

向其赋值的对象。

备注

此运算符复制存储的格式信息，从而创建任何可扩展数组的新副本。 然后返回 *this。 回调堆栈不会被复制。

此运算符仅由派生自 ios_base 的类使用。

precision

指定浮点数中显示的位数。

streamsize precision() const;
streamsize precision(streamsize _Prec);

参数

_Prec
要显示的有效位的数目或固定表示法中小数点后的位数。

返回值

第一个成员函数返回存储的显示精度。 第二个成员函数将 _Prec 存储在显示精度中，并返回其先前的存储值。

注解

浮点数以具有 fixed 的固定表示法显示。

示例

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

int main( )
{
    using namespace std;
    float i = 31.31234F;

    cout.precision( 3 );
    cout << i << endl;          // display three significant digits
    cout << fixed << i << endl; // display three digits after decimal
                                // point
}

31.3
31.312

pword

分配将存储为 pword 的值。

void *& pword(int index);

参数

index
要存储为 pword 的值的索引。

注解

此成员函数返回具有类型 void 指针的元素的可扩展数组的 index 元素引用。 所有元素均有效存在，且起初会存储空指针。 下次调用此对象的 pword 后、对象由对 basic_ios::copyfmt 的调用更改后或者对象被销毁后，该返回引用将无效。

如果 index 为负或唯一存储对该元素不可用，则此函数会调用 setstate(badbit) 并返回一个可能并不唯一的引用。

若要获取唯一索引以用于类型 ios_base 的所有对象，请调用 xalloc。

示例

有关使用 pword 的示例，请参阅 xalloc。

register_callback

指定一个回调函数。

void register_callback(
    event_callback pfn, int idx);

参数

pfn
回调函数的指针。

idx
用户定义的数字。

备注

此成员函数将对 {pfn, idx} 推送到存储的回调堆栈回调堆栈。 报告回调事件 ev 时，表达式 (*pfn)(ev, *this, idx) 会按注册的相反顺序调用函数。

示例

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

using namespace std;

void callback1( ios_base::event e, ios_base& stream, int arg )
{
    cout << "in callback1" << endl;
    switch ( e )
    {
    case ios_base::erase_event:
        cout << "an erase event" << endl;
        break;
    case ios_base::imbue_event:
        cout << "an imbue event" << endl;
        break;
    case ios_base::copyfmt_event:
        cout << "an copyfmt event" << endl;
        break;
    };
}

void callback2( ios_base::event e, ios_base& stream, int arg )
{
    cout << "in callback2" << endl;
    switch ( e )
    {
    case ios_base::erase_event:
        cout << "an erase event" << endl;
        break;
    case ios_base::imbue_event:
        cout << "an imbue event" << endl;
        break;
    case ios_base::copyfmt_event:
        cout << "an copyfmt event" << endl;
        break;
    };
}

int main( )
{
    // Make sure the imbue will not throw an exception
    // assert( setlocale( LC_ALL, "german" )!=NULL );

    cout.register_callback( callback1, 0 );
    cin.register_callback( callback2, 0 );

    try
    {
        // If no exception because the locale's not found,
        // generate an imbue_event on callback1
        cout.imbue(locale("german"));
    }
    catch(...)
    {
        cout << "exception" << endl;
    }

    // This will
    // (1) erase_event on callback1
    // (2) copyfmt_event on callback2
    cout.copyfmt(cin);

    // We get two erase events from callback2 at the end because
    // both cin and cout have callback2 registered when cin and cout
    // are destroyed at the end of program.
}

in callback1
an imbue event
in callback1
an erase event
in callback2
an copyfmt event
in callback2
an erase event
in callback2
an erase event

seekdir

指定偏移操作的起始点。

namespace std {
    class ios_base {
    public:
        typedef implementation-defined-enumerated-type seekdir;
        static const seekdir beg;
        static const seekdir cur;
        static const seekdir end;
        // ...
    };
}

备注

此类型是一个枚举类型，其描述了一个对象，该对象可以存储用作多个 iostream 类的成员函数的参数的搜寻模式。 非重复的标志值为：

• beg，用以相对于序列（数组、流或文件）的开始位置进行查找（更改当前读取或写入位置）。

• cur，相对于序列中的当前位置进行查找。

• end，相对于序列的末尾进行查找。

示例

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

int main ( )
{
    using namespace std;
    fstream file;
    file.open( "rm.txt", ios_base::out | ios_base::trunc );

    file << "testing";
    file.seekp( 0, ios_base::beg );
    file << "a";
    file.seekp( 0, ios_base::end );
    file << "a";
}

setf

设置指定标志。

fmtflags setf(
    fmtflags _Mask
);
fmtflags setf(
    fmtflags _Mask,
    fmtflags _Unset
);

参数

_Mask
要打开的标志。

_Unset
要关闭的标志。

返回值

先前的格式标志

备注

第一个成员函数实际上调用 flags(_Mask | _Flags)（设置选定的位），然后返回先前的格式标志。 第二个成员函数实际上调用 flags(_Mask & fmtfl, flags & ~_Mask)（替换掩码下的选定位），然后返回先前的格式标志。

示例

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

int main( )
{
    using namespace std;
    int i = 10;
    cout << i << endl;

    cout.unsetf( ios_base::dec );
    cout.setf( ios_base::hex );
    cout << i << endl;

    cout.setf( ios_base::dec );
    cout << i << endl;
    cout.setf( ios_base::hex, ios_base::dec );
    cout << i << endl;
}

sync_with_stdio

确保 iostream 和 C 运行时库操作按照它们在源代码中出现的顺序发生。

static bool sync_with_stdio(
   bool _Sync = true
);

参数

_Sync
所有流是否与 stdio 同步。

返回值

此函数的先前设置。

备注

静态成员函数存储一个 stdio 同步标志，最初是 true。 当 true 时，此标志确保对同一文件的操作能够在 C++ 标准库中定义的函数与 iostreams 函数之间正确同步。 否则，不一定能保证同步，但可能会提高性能。 该函数将 _Sync 存储在 stdio 同步标准中并返回其先前存储的值。 只有尚未对标准流执行任何操作之前，才能可靠地调用该函数。

unsetf

关闭指定的标志。

void unsetf(
   fmtflags _Mask
);

参数

_Mask
你要关闭的标志。

备注

成员函数实际上调用 flags(~_Mask & flags)（清除选定位）。

示例

有关 unsetf 用法的示例，请参阅ios_base::setf。

width

设置输出流的长度。

streamsize width( ) const;
streamsize width(
   streamsize _Wide
);

参数

_Wide
所需的输出流大小。

返回值

当前宽度设置。

备注

第一个成员函数返回存储的字段宽度。 第二个成员函数将 _Wide 存储在 width 字段中，并返回其先前的存储值。

示例

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

int main( ) {
    using namespace std;

    cout.width( 20 );
    cout << cout.width( ) << endl;
    cout << cout.width( ) << endl;
}

20
0

xalloc

指定变量是流的一部分。

static int xalloc( );

返回值

静态成员函数返回一个存储的静态值，在每次调用时此值都会递增。

备注

调用成员函数 iword 或 pword 时，你可以将返回值用作唯一索引参数。

示例

// ios_base_xalloc.cpp
// compile with: /EHsc
// Lets you store user-defined information.
// iword, jword, xalloc
#include <iostream>

int main( )
{
    using namespace std;

    static const int i = ios_base::xalloc();
    static const int j = ios_base::xalloc();
    cout.iword( i ) = 11;
    cin.iword( i ) = 13;
    cin.pword( j ) = "testing";
    cout << cout.iword( i ) << endl;
    cout << cin.iword( i ) << endl;
    cout << ( char * )cin.pword( j ) << endl;
}

11
13
testing

另请参阅

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