| title | description | ms.date | f1_keywords | helpviewer_keywords | ms.custom | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ios_base Class | API reference for the Microsoft Visual C++ standard library `ios_base` class | 06/15/2022 |
|
| devdivchpfy22 |
The class describes the storage and member functions common to both input and output streams that don't depend on the template parameters. (The class template basic_ios describes what is common and is dependent on template parameters.)
An object of class ios_base stores formatting information, which consists of:
Format flags in an object of type
fmtflags.An exception mask in an object of type
iostate.A field width in an object of type
int.A display precision in an object of type
int.A
localeobject in an object of typelocale.Two extensible arrays, with elements of type
longandvoidpointer.
An object of class ios_base also stores stream state information, in an object of type iostate, and a callback stack.
| Name | Description |
|---|---|
ios_base | Constructs ios_base objects. |
| Name | Description |
|---|---|
event_callback | Describes a function passed to register_call. |
fmtflags | Constants to specify the appearance of output. |
iostate | Defines constants describing the state of a stream. |
openmode | Describes how to interact with a stream. |
seekdir | Specifies starting point for offset operations. |
| Name | Description |
|---|---|
event | Specifies event types. |
| Name | Description |
|---|---|
adjustfield | A bitmask defined as internal | left | right. |
app | Specifies seeking to the end of a stream before each insertion. |
ate | Specifies seeking to the end of a stream when its controlling object is first created. |
badbit | Records a loss of integrity of the stream buffer. |
basefield | A bitmask defined as dec | hex | oct. |
beg | Specifies seeking relative to the beginning of a sequence. |
binary | Specifies that a file should be read as a binary stream, rather than as a text stream. |
boolalpha | Specifies insertion or extraction of objects of type bool as names (such as true and false) rather than as numeric values. |
cur | Specifies seeking relative to the current position within a sequence. |
dec | Specifies insertion or extraction of integer values in decimal format. |
end | Specifies seeking relative to the end of a sequence. |
eofbit | Records end-of-file while extracting from a stream. |
failbit | Records a failure to extract a valid field from a stream. |
fixed | Specifies insertion of floating-point values in fixed-point format (with no exponent field). |
floatfield | A bitmask defined as fixed | scientific |
goodbit | All state bits clear. |
hex | Specifies insertion or extraction of integer values in hexadecimal format. |
in | Specifies extraction from a stream. |
internal | Pads to a field width by inserting fill characters at a point internal to a generated numeric field. |
left | Specifies left justification. |
oct | Specifies insertion or extraction of integer values in octal format. |
out | Specifies insertion to a stream. |
right | Specifies right justification. |
scientific | Specifies insertion of floating-point values in scientific format (with an exponent field). |
showbase | Specifies insertion of a prefix that reveals the base of a generated integer field. |
showpoint | Specifies unconditional insertion of a decimal point in a generated floating-point field. |
showpos | Specifies insertion of a plus sign in a nonnegative generated numeric field. |
skipws | Specifies skipping leading white space before certain extractions. |
trunc | Specifies deleting contents of an existing file when its controlling object is created. |
unitbuf | Causes output to be flushed after each insertion. |
uppercase | Specifies insertion of uppercase equivalents of lowercase letters in certain insertions. |
| Name | Description |
|---|---|
failure | The member class serves as the base class for all exceptions thrown by the member function clear in class template basic_ios. |
flags | Sets or returns the current flag settings. |
getloc | Returns the stored locale object. |
imbue | Changes the locale. |
Init | Creates the standard iostream objects when constructed. |
iword | Assigns a value to be stored as an iword. |
precision | Specifies the number of digits to display in a floating-point number. |
pword | Assigns a value to be stored as a pword. |
register_callback | Specifies a callback function. |
setf | Sets the specified flags. |
sync_with_stdio | Ensures that iostream and C run-time library operations occur in the order that they appear in source code. |
unsetf | Causes the specified flags to be off. |
width | Sets the length of the output stream. |
xalloc | Specifies that a variable shall be part of the stream. |
| Name | Description |
|---|---|
operator= | The assignment operator for ios_base objects. |
Header:<ios>
Namespace:std
Specifies event types.
enum event { erase_event, imbue_event, copyfmt_event};The type is an enumerated type that describes an object that can store the callback event used as an argument to a function registered with register_callback. The distinct event values are:
copyfmt_event, to identify a callback that occurs near the end of a call tocopyfmt, just before the exception mask is copied.erase_event, to identify a callback that occurs at the beginning of a call tocopyfmt, or at the beginning of a call to the destructor for*this.imbue_event, to identify a callback that occurs at the end of a call toimbue, just before the function returns.
See register_callback for an example.
Describes a function passed to register_call.
typedefvoid (__cdecl *event_callback)( event _E, ios_base& _Base, int _I);_E
The event.
_Base
The stream in which the event was called.
_I
A user-defined number.
The type describes a pointer to a function that can be registered with register_callback. This type of function must not throw an exception.
See register_call for an example that uses event_callback.
The class failure defines the base class for the types of all objects thrown as exceptions, by functions in the iostreams library, to report errors detected during stream buffer operations.
namespacestd { classfailure : publicsystem_error { public:explicitfailure( const string& _Message, const error_code& _Code = io_errc::stream); explicitfailure( constchar* str, const error_code& _Code = io_errc::stream); }; }The value returned by what() is a copy of _Message, possibly augmented with a test based on _Code. If _Code isn't specified, the default value is make_error_code(io_errc::stream).
// ios_base_failure.cpp// compile with: /EHsc #include<iostream> #include<fstream>intmain ( ) { usingnamespacestd; 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 Sets or returns the current flag settings.
fmtflags flags() const; fmtflags flags(fmtflags fmtfl);fmtfl
The new fmtflags setting.
The previous or current fmtflags setting.
See ios_base::fmtflags for a list of the flags.
The first member function returns the stored format flags. The second member function stores fmtfl in the format flags and returns its previous stored value.
// ios_base_flags.cpp// compile with: /EHsc #include<iostream> #include<fstream>intmain ( ) { usingnamespacestd; cout << cout.flags( ) << endl; cout.flags( ios::dec | ios::boolalpha ); cout << cout.flags( ); }513 16896 Constants to specify the appearance of output.
classios_base { public:typedef implementation-defined-bitmask-type fmtflags; staticconst fmtflags boolalpha; staticconst fmtflags dec; staticconst fmtflags fixed; staticconst fmtflags hex; staticconst fmtflags internal; staticconst fmtflags left; staticconst fmtflags oct; staticconst fmtflags right; staticconst fmtflags scientific; staticconst fmtflags showbase; staticconst fmtflags showpoint; staticconst fmtflags showpos; staticconst fmtflags skipws; staticconst fmtflags unitbuf; staticconst fmtflags uppercase; staticconst fmtflags adjustfield; staticconst fmtflags basefield; staticconst fmtflags floatfield; // ... };Supports the manipulators in ios.
The type is a bitmask type that describes an object that can store format flags. The distinct flag values (elements) are:
dec, to insert or extract integer values in decimal format.hex, to insert or extract integer values in hexadecimal format.oct, to insert or extract integer values in octal format.showbase, to insert a prefix that reveals the base of a generated integer field.internal, to pad to a field width as needed by inserting fill characters at a point internal to a generated numeric field. (For information on setting the field width, seesetw).left, to pad to a field width as needed by inserting fill characters at the end of a generated field (left justification).right, to pad to a field width as needed by inserting fill characters at the beginning of a generated field (right justification).boolalpha, to insert or extract objects of typeboolas names (such astrueandfalse) rather than as numeric values.fixed, to insert floating-point values in fixed-point format (with no exponent field).scientific, to insert floating-point values in scientific format (with an exponent field).showpoint, to insert a decimal point unconditionally in a generated floating-point field.showpos, to insert a plus sign in a nonnegative generated numeric field.skipws, to skip leading white space before certain extractions.unitbuf, to flush output after each insertion.uppercase, to insert uppercase equivalents of lowercase letters in certain insertions.
In addition, several useful values are:
adjustfield, a bitmask defined asinternal|left|rightbasefield, defined asdec|hex|octfloatfield, defined asfixed|scientific
For examples of functions that modify these format flags, see <iomanip>.
Returns the stored locale object.
locale getloc() const;The stored locale object.
// ios_base_getlock.cpp// compile with: /EHsc #include<iostream>intmain( ) { usingnamespacestd; cout << cout.getloc( ).name( ).c_str( ) << endl; }C Changes the locale.
locale imbue(const locale& _Loc);_Loc
The new locale setting.
The previous locale.
The member function stores _Loc in the locale object and then reports the callback event and imbue_event. It returns the previous stored value.
See basic_ios::imbue for a sample.
Creates the standard iostream objects when constructed.
classInit { };The nested class describes an object whose construction ensures that the standard iostream objects are properly constructed, even before the execution of a constructor for an arbitrary static object.
Constructs ios_base objects.
ios_base();The (protected) constructor does nothing. A later call to basic_ios::init must initialize the object before it can be safely destroyed. Thus, the only safe use for class ios_base is as a base class for class template basic_ios.
The type of constants that describe the state of a stream.
classios_base { public:typedef implementation-defined-bitmask-type iostate; staticconst iostate badbit; staticconst iostate eofbit; staticconst iostate failbit; staticconst iostate goodbit; // ... };The type is a bitmask type that describes an object that can store stream state information. The distinct flag values (elements) are:
badbit, to record a loss of integrity of the stream buffer.eofbit, to record end-of-file while extracting from a stream.failbit, to record a failure to extract a valid field from a stream.
In addition, a useful value is goodbit, where none of the previously mentioned bits are set (goodbit is guaranteed to be zero).
Assigns a value to be stored as an iword.
long& iword(int idx);idx
The index of the value to store as an iword.
The member function returns a reference to element idx of the extensible array with elements of type long. All elements are effectively present and initially store the value zero. The returned reference is invalid after the next call to iword for the object, after the object is altered by a call to basic_ios::copyfmt, or after the object is destroyed.
If idx is negative or if unique storage is unavailable for the element, the function calls setstate(badbit) and returns a reference that might not be unique.
To obtain a unique index, for use across all objects of type ios_base, call xalloc.
See xalloc for a sample of how to use iword.
Describes how to interact with a stream.
classios_base { public:typedef implementation-defined-bitmask-type openmode; staticconst openmode in; staticconst openmode out; staticconst openmode ate; staticconst openmode app; staticconst openmode trunc; staticconst openmode binary; // ... };The opening mode for several iostream objects. The flag values are:
| Constant | Effect |
|---|---|
app | Seek to the end of the stream before each write |
ate | Seek to the end of the stream immediately after open |
binary | Open in binary mode. (See fopen for a description of binary mode.) |
in | Open for reading |
out | Open for writing |
trunc | Delete the contents of the file after open |
// ios_base_openmode.cpp// compile with: /EHsc #include<iostream> #include<fstream>intmain ( ) { usingnamespacestd; fstream file; file.open( "rm.txt", ios_base::out | ios_base::trunc ); file << "testing"; }The assignment operator for ios_base objects.
ios_base& operator=(const ios_base& right);right
An object of type ios_base.
The object being assigned to.
The operator copies the stored formatting information, making a new copy of any extensible arrays. It then returns *this. The callback stack isn't copied.
This operator is only used by classes derived from ios_base.
Specifies the number of digits to display in a floating-point number.
streamsize precision() const; streamsize precision(streamsize _Prec);_Prec
The number of significant digits to display, or the number of digits after the decimal point in fixed notation.
The first member function returns the stored display precision. The second member function stores _Prec in the display precision and returns its previous stored value.
Floating-point numbers are displayed in fixed notation with fixed.
// ios_base_precision.cpp// compile with: /EHsc #include<iostream>intmain( ) { usingnamespacestd;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 Assigns a value to be stored as a pword.
void *& pword(int index);index
The index of the value to store as a pword.
The member function returns a reference to element index of the extensible array with elements of type void pointer. All elements are effectively present and initially store the null pointer. The returned reference is invalid after the next call to pword for the object, after the object is altered by a call to basic_ios::copyfmt, or after the object is destroyed.
If index is negative, or if unique storage is unavailable for the element, the function calls setstate(badbit) and returns a reference that might not be unique.
To obtain a unique index, for use across all objects of type ios_base, call xalloc.
See xalloc for an example of using pword.
Specifies a callback function.
voidregister_callback( event_callback pfn, int idx);pfn
Pointer to the callback function.
idx
A user-defined number.
The member function pushes the pair {pfn, idx} onto the stored callback stack callback stack. When a callback event ev is reported, the functions are called, in reverse order of registry, by the expression (*pfn)(ev, *this, idx).
// ios_base_register_callback.cpp// compile with: /EHsc #include<iostream> #include<fstream>usingnamespacestd;voidcallback1( 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; }; } voidcallback2( 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; }; } intmain( ) { // 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 Specifies starting point for offset operations.
namespacestd { classios_base { public:typedef implementation-defined-enumerated-type seekdir; staticconst seekdir beg; staticconst seekdir cur; staticconst seekdir end; // ... }; }The type is an enumerated type that describes an object that can store the seek mode used as an argument to the member functions of several iostream classes. The distinct flag values are:
beg, to seek (alter the current read or write position) relative to the beginning of a sequence (array, stream, or file).cur, to seek relative to the current position within a sequence.end, to seek relative to the end of a sequence.
// ios_base_seekdir.cpp// compile with: /EHsc #include<iostream> #include<fstream>intmain ( ) { usingnamespacestd; 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"; }Sets the specified flags.
fmtflags setf( fmtflags _Mask ); fmtflags setf( fmtflags _Mask, fmtflags _Unset );_Mask
The flags to turn on.
_Unset
The flags to turn off.
The previous format flags
The first member function effectively calls flags(_Mask | _Flags) (set selected bits) and then returns the previous format flags. The second member function effectively calls flags(_Mask & fmtfl, flags & ~_Mask) (replace selected bits under a mask) and then returns the previous format flags.
// ios_base_setf.cpp// compile with: /EHsc #include<iostream>intmain( ) { usingnamespacestd;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; }Ensures that iostream and C run-time library operations occur in the order that they appear in source code.
staticboolsync_with_stdio( bool _Sync = true );_Sync
Whether all streams are in sync with stdio.
Previous setting for this function.
The static member function stores a stdio sync flag, which is initially true. When true, this flag ensures that operations on the same file are properly synchronized between the iostreams functions and functions defined in the C++ Standard Library. Otherwise, synchronization may or may not be guaranteed, but performance may be improved. The function stores _Sync in the stdio sync flag and returns its previous stored value. You can call it reliably only before performing any operations on the standard streams.
Turns off the specified flags.
voidunsetf( fmtflags _Mask );_Mask
The flags that you want to turn off.
The member function effectively calls flags(~_Mask & flags) (clear selected bits).
See ios_base::setf for a sample of using unsetf.
Sets the length of the output stream.
streamsize width( ) const; streamsize width( streamsize _Wide );_Wide
The desired size of the output stream.
The current width setting.
The first member function returns the stored field width. The second member function stores _Wide in the field width and returns its previous stored value.
// ios_base_width.cpp// compile with: /EHsc #include<iostream>intmain( ) { usingnamespacestd; cout.width( 20 ); cout << cout.width( ) << endl; cout << cout.width( ) << endl; }20 0 Specifies that a variable is part of the stream.
staticintxalloc( );The static member function returns a stored static value, which it increments on each call.
You can use the return value as a unique index argument when calling the member functions iword or pword.
// ios_base_xalloc.cpp// compile with: /EHsc// Lets you store user-defined information.// iword, jword, xalloc #include<iostream>intmain( ) { usingnamespacestd;staticconstint i = ios_base::xalloc(); staticconstint 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 Thread Safety in the C++ Standard Library
iostream Programming
iostreams Conventions
