basic_ios Class
The class template describes the storage and member functions common to both input streams (of class template basic_istream) and output streams (of class template basic_ostream) that depend on the template parameters. (The class ios_base describes what is common and not dependent on template parameters.) An object of class basic_ios<class Elem, class Traits> helps control a stream with elements of type Elem, whose character traits are determined by the class Traits.
template <class Elem, class Traits>
class basic_ios : public ios_base
Elem
A character type.
Traits
A type providing information about the character type, defaults to char_traits < Elem >.
An object of class basic_ios<class Elem, class Traits> stores:
A tie pointer to an object of type
basic_istream<Elem, Traits>.A stream buffer pointer to an object of type
basic_streambuf<Elem, Traits >.Stream state information in a base object of type
ios_base.A fill character in an object of type
char_type.
For more information, see basic_istream and basic_streambuf.
| Constructor | Description |
|---|---|
basic_ios |
Constructs the basic_ios class. |
| Type name | Description |
|---|---|
char_type |
A synonym for the template parameter Elem. |
int_type |
A synonym for Traits::int_type. |
off_type |
A synonym for Traits::off_type. |
pos_type |
A synonym for Traits::pos_type. |
traits_type |
A synonym for the template parameter Traits. |
| Member function | Description |
|---|---|
bad |
Indicates a loss of integrity of the stream buffer. |
clear |
Clears all error flags. |
copyfmt |
Copies flags from one stream to another. |
eof |
Indicates if the end of a stream has been reached. |
exceptions |
Indicates which exceptions will be thrown by the stream. |
fail |
Indicates failure to extract a valid field from a stream. |
fill |
Specifies or returns the character that will be used when the text isn't as wide as the stream. |
good |
Indicates the stream is in good condition. |
imbue |
Changes the locale. |
init |
Called by basic_ios constructors. |
move |
Moves all values, except the pointer to the stream buffer, from the parameter to the current object. |
narrow |
Finds the equivalent char to a given char_type. |
rdbuf |
Routes stream to specified buffer. |
rdstate |
Reads the state of bits for flags. |
set_rdbuf |
Assigns a stream buffer to be the read buffer for this stream object. |
setstate |
Sets additional flags. |
swap |
Exchanges the values in this basic_ios object for those of another basic_ios object. The pointers to the stream buffers aren't swapped. |
tie |
Ensures that one stream is processed before another stream. |
widen |
Finds the equivalent char_type to a given char. |
| Operator | Description |
|---|---|
explicit operator bool |
Allows use of a basic_ios object as a bool. Automatic type conversion is disabled to prevent common, unintended side effects. |
operator void * |
Indicates if the stream is still good. |
operator! |
Indicates if the stream isn't bad. |
Header: <ios>
Namespace: std
Indicates a loss of integrity of the stream buffer
bool bad() const;
true if rdstate & badbit is nonzero; otherwise false.
For more information on badbit, see ios_base::iostate.
// basic_ios_bad.cpp
// compile with: /EHsc
#include <iostream>
int main( void )
{
using namespace std;
bool b = cout.bad( );
cout << boolalpha;
cout << b << endl;
b = cout.good( );
cout << b << endl;
}
Constructs the basic_ios class.
explicit basic_ios(basic_streambuf<Elem, Traits>* sb);
basic_ios();
sb
Standard buffer to store input or output elements.
The first constructor initializes its member objects by calling init(_ Sb). The second (protected) constructor leaves its member objects uninitialized. A later call to init must initialize the object before it can be safely destroyed.
A synonym for the template parameter Elem.
typedef Elem char_type;
Clears all error flags.
void clear(iostate state = goodbit, bool reraise = false);
void clear(io_state state);
state
(Optional) The flags you want to set after clearing all flags. Defaults to goodbit.
reraise
(Optional) Specifies whether the exception should be re-raised. Defaults to false (won't re-raise the exception).
The flags are goodbit, failbit, eofbit, and badbit. Test for these flags with good, bad, eof, and fail
The member function replaces the stored stream state information with:
state | (rdbuf != 0 goodbit : badbit)
If state&exceptions is nonzero, it then throws an object of class failure.
For more information, see rdbuf and exceptions.
See rdstate and getline for examples using clear.
Copies flags from one stream to another.
basic_ios<Elem, Traits>& copyfmt(
const basic_ios<Elem, Traits>& right);
right
The stream whose flags you want to copy.
The this object for the stream to which you're copying the flags.
The member function reports the callback event erase_event. It then copies from right into *this the fill character, the tie pointer, and the formatting information. Before altering the exception mask, it reports the callback event copyfmt_event. If after the copy is complete, state&exceptions is nonzero, the function effectively calls clear with the argument rdstate. It returns *this.
// basic_ios_copyfmt.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>
int main( )
{
using namespace std;
ofstream x( "test.txt" );
int i = 10;
x << showpos;
cout << i << endl;
cout.copyfmt( x );
cout << i << endl;
}
Indicates if the end of a stream has been reached.
bool eof() const;
true if the end of the stream has been reached, false otherwise.
The member function returns true if rdstate & eofbit is nonzero. For more information on eofbit, see ios_base::iostate.
// basic_ios_eof.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>
using namespace std;
int main( int argc, char* argv[] )
{
fstream fs;
int n = 1;
fs.open( "basic_ios_eof.txt" ); // an empty file
cout << boolalpha
cout << fs.eof() << endl;
fs >> n; // Read the char in the file
cout << fs.eof() << endl;
}
Indicates which exceptions will be thrown by the stream.
iostate exceptions() const;
void exceptions(iostate Newexcept);
void exceptions(io_state Newexcept);
Newexcept
The flags that you want to throw an exception.
The flags that are currently specified to throw an exception for the stream.
The first member function returns the stored exception mask. The second member function stores _Except in the exception mask and returns its previous stored value. Storing a new exception mask can throw an exception just like the call clear( rdstate ).
// basic_ios_exceptions.cpp
// compile with: /EHsc /GR
#include <iostream>
int main( )
{
using namespace std;
cout << cout.exceptions( ) << endl;
cout.exceptions( ios::eofbit );
cout << cout.exceptions( ) << endl;
try
{
cout.clear( ios::eofbit ); // Force eofbit on
}
catch ( exception &e )
{
cout.clear( );
cout << "Caught the exception." << endl;
cout << "Exception class: " << typeid(e).name() << endl;
cout << "Exception description: " << e.what() << endl;
}
}
0
1
Caught the exception.
Exception class: class std::ios_base::failure
Exception description: ios_base::eofbit set
Indicates failure to extract a valid field from a stream.
bool fail() const;
true if rdstate & (badbit|failbit) is nonzero, otherwise false.
For more information on failbit, see ios_base::iostate.
// basic_ios_fail.cpp
// compile with: /EHsc
#include <iostream>
int main( void )
{
using namespace std;
bool b = cout.fail( );
cout << boolalpha;
cout << b << endl;
}
Specifies or returns the character that will be used when the text isn't as wide as the stream.
char_type fill() const;
char_type fill(char_type Char);
Char
The character you want as the fill character.
The current fill character.
The first member function returns the stored fill character. The second member function stores Char in the fill character and returns its previous stored value.
// basic_ios_fill.cpp
// compile with: /EHsc
#include <iostream>
#include <iomanip>
int main( )
{
using namespace std;
cout << setw( 5 ) << 'a' << endl;
cout.fill( 'x' );
cout << setw( 5 ) << 'a' << endl;
cout << cout.fill( ) << endl;
}
a
xxxxa
x
Indicates the stream is in good condition.
bool good() const;
true if rdstate == goodbit (no state flags are set), otherwise, false.
For more information on goodbit, see ios_base::iostate.
See basic_ios::bad for an example of using good.
Changes the locale.
locale imbue(const locale& Loc);
Loc
A locale string.
The previous locale.
If rdbuf isn't a NULL pointer, the member function calls
rdbuf-> pubimbue(_ Loc)
In any case, it returns ios_base::imbue(_ Loc).
For more information, see pubimbue and ios_base::imbue.
// basic_ios_imbue.cpp
// compile with: /EHsc
#include <iostream>
#include <locale>
int main( )
{
using namespace std;
cout.imbue( locale( "french_france" ) );
double x = 1234567.123456;
cout << x << endl;
}
Called by basic_ios constructors.
void init(basic_streambuf<Elem,Traits>* _Sb, bool _Isstd = false);
_Sb
Standard buffer to store input or output elements.
_Isstd
Specifies whether this is a standard stream.
The member function stores values in all member objects, so that:
rdbufreturns_Sb.tiereturns aNULLpointer.rdstatereturnsgoodbitif_Sbis nonzero; otherwise, it returnsbadbit.exceptionsreturnsgoodbit.flagsreturnsskipws | dec. For more information, seeskipwsanddec.widthreturns 0.precisionreturns 6.fillreturns the space character.getlocreturnslocale::classic.iwordreturns zero, andpwordreturns aNULLpointer for all argument values.
A synonym for traits_type::int_type.
typedef typename traits_type::int_type int_type;
Moves all values, except the pointer to the stream buffer, from the parameter to the current object.
void move(basic_ios&& right);
right
The ios_base object to move values from.
The protected member function moves all the values stored in right to *this except the stored stream buffer pointer, which is unchanged in right and set to a NULL pointer in *this. The stored tie pointer is set to a NULL pointer in right.
Finds the equivalent char to a given char_type.
char narrow(char_type Char, char Default = '\0') const;
Char
The char to convert.
Default
The char that you want returned if no equivalent is found.
The equivalent char to a given char_type.
The member function returns use_facet<ctype<E>>(getloc()).narrow(Char, Default).
For more information, see use_facet and getloc.
// basic_ios_narrow.cpp
// compile with: /EHsc
#include <ios>
#include <iostream>
#include <wchar.h>
int main( )
{
using namespace std;
wchar_t *x = L"test";
char y[10];
cout << x[0] << endl;
wcout << x << endl;
y[0] = wcout.narrow( x[0] );
cout << y[0] << endl;
}
A synonym for traits_type::off_type.
typedef typename traits_type::off_type off_type;
Indicates if the stream is still good.
operator void *() const;
The operator returns a NULL pointer only if fail.
// basic_ios_opgood.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
using namespace std;
cout << (bool)(&cout != 0) << endl; // Stream is still good
}
1
Indicates if the stream isn't bad.
bool operator!() const;
Returns the same as calling basic_ios::fail
// basic_ios_opbad.cpp
// compile with: /EHsc
#include <iostream>
int main( )
{
using namespace std;
cout << !cout << endl; // Stream is not bad
}
0
Allows use of a basic_ios object as a bool. Automatic type conversion is disabled to prevent common, unintended side effects.
explicit operator bool() const;
Returns true if the stream has no errors; otherwise false.
A synonym for traits_type::pos_type.
typedef typename traits_type::pos_type pos_type;
Routes stream to specified buffer.
basic_streambuf<Elem, Traits> *rdbuf() const;
basic_streambuf<Elem, Traits> *rdbuf(
basic_streambuf<Elem, Traits>* _Sb);
_Sb
A stream.
The first member function returns the stored stream buffer pointer.
The second member function stores _Sb in the stored stream buffer pointer and returns the previously stored value.
// basic_ios_rdbuf.cpp
// compile with: /EHsc
#include <ios>
#include <iostream>
#include <fstream>
int main( )
{
using namespace std;
ofstream file( "rdbuf.txt" );
streambuf *x = cout.rdbuf( file.rdbuf( ) );
cout << "test" << endl; // Goes to file
cout.rdbuf(x);
cout << "test2" << endl;
}
test2
Reads the stream error state.
iostate rdstate() const;
The stored stream state information.
// basic_ios_rdstate.cpp
// compile with: /EHsc
#include <iostream>
#include <fstream>
using namespace std;
void TestFlags( ios& x )
{
cout << ( x.rdstate( ) & ios::badbit ) << endl;
cout << ( x.rdstate( ) & ios::failbit ) << endl;
cout << ( x.rdstate( ) & ios::eofbit ) << endl;
cout << endl;
}
int main( )
{
fstream x( "c:\test.txt", ios::out );
x.clear( );
TestFlags( x );
x.clear( ios::badbit | ios::failbit | ios::eofbit );
TestFlags( x );
}
0
0
0
4
2
1
Sets the specified stream error flags (currently set stream error state flags remain unchanged):
| flag | Description |
|---|---|
goodbit |
No error |
badbit |
Unrecoverable error |
failbit |
I/O operation failed, such as a formatting or extraction error |
eofbit |
Stream has reached the end of the file |
void setstate(iostate _State);
_State
Additional flags to set.
The member function essentially calls clear(_ state | rdstate).
For more information, see clear and rdstate.
// basic_ios_setstate.cpp
// compile with: /EHsc
#include <ios>
#include <iostream>
using namespace std;
int main( )
{
bool b = cout.bad( );
cout << b << endl; // Good
cout.clear( ios::badbit );
b = cout.bad( );
// cout.clear( );
cout << b << endl; // Is bad, good
b = cout.fail( );
cout << b << endl; // Not failed
cout.setstate( ios::failbit );
b = cout.fail( );
cout.clear( );
cout << b << endl; // Is failed, good
return 0;
}
0
1
Assigns a stream buffer to be the read buffer for this stream object.
void set_rdbuf(
basic_streambuf<Elem, Tr>* strbuf)
strbuf
The stream buffer to become the read buffer.
The protected member function stores strbuf in the stream buffer pointer. It doesn't call clear.
Ensures that one stream is processed before another stream.
basic_ostream<Elem, Traits> *tie() const;
basic_ostream<Elem, Traits> *tie(
basic_ostream<Elem, Traits>* str);
str
A stream.
The first member function returns the stored tie pointer. The second member function stores str in the tie pointer and returns its previous stored value.
tie causes two streams to be synchronized, such that, operations on one stream occur after operations on the other stream are complete.
In the following example, by tying cin to cout, it's guaranteed that the Enter a number: string will go to the console before the number itself is extracted from cin. This eliminates the possibility that the "Enter a number:" string is still sitting in the buffer when the number is read, so that we're certain that the user actually has some prompt to respond to. By default, cin and cout are tied.
#include <ios>
#include <iostream>
int main( )
{
using namespace std;
int i;
cin.tie( &cout );
cout << "Enter a number:";
cin >> i;
}
A synonym for the template parameter Traits.
typedef Traits traits_type;
Finds the equivalent char_type to a given char.
char_type widen(char Char) const;
Char
The character to convert.
Finds the equivalent char_type to a given char.
The member function returns use_facet<ctype<E>>(getloc).widen(Char).
For more information, see use_facet and getloc.
// basic_ios_widen.cpp
// compile with: /EHsc
#include <ios>
#include <iostream>
#include <wchar.h>
int main( )
{
using namespace std;
char *z = "Hello";
wchar_t y[2] = {0,0};
cout << z[0] << endl;
y[0] = wcout.widen( z[0] );
wcout << &y[0] << endl;
}
Exchanges the values in this basic_ios object for those of another basic_ios object. However, the pointers to the stream buffers aren't swapped.
void swap(basic_ios&& right);
right
The basic_ios object that is used to exchange values.
The protected member function exchanges all the values stored in right with *this except the stored stream buffer pointer.
Thread Safety in the C++ Standard Library
iostream Programming
iostreams Conventions