Windows apps
Collapse the table of content
Expand the table of content
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

basic_ios Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

The template class describes the storage and member functions common to both input streams (of template class basic_istream) and output streams (of template class 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  

Parameters

Elem
A type.

Traits
A variable of type char_traits.

An object of class basic_ios<class Elem, class Traits> stores:

Constructors

basic_iosConstructs the basic_ios class.

Typedefs

char_typeA synonym for the template parameter Elem.
int_typeA synonym for Traits::int_type.
off_typeA synonym for Traits::off_type.
pos_typeA synonym for Traits::pos_type.
traits_typeA synonym for the template parameter Traits.

Member Functions

badIndicates a loss of integrity of the stream buffer.
clearClears all error flags.
copyfmtCopies flags from one stream to another.
eofIndicates if the end of a stream has been reached.
exceptionsIndicates which exceptions will be thrown by the stream.
failIndicates failure to extract a valid field from a stream.
fillSpecifies or returns the character that will be used when the text is not as wide as the stream.
goodIndicates the stream is in good condition.
imbueChanges the locale.
initCalled by basic_ios constructors.
moveMoves all values, except the pointer to the stream buffer, from the parameter to the current object.
narrowFinds the equivalent char to a given char_type.
rdbufRoutes stream to specified buffer.
rdstateReads the state of bits for flags.
set_rdbufAssigns a stream buffer to be the read buffer for this stream object.
setstateSets additional flags.
swapExchanges the values in this basic_ios object for those of another basic_ios object. The pointers to the stream buffers are not swapped.
tieEnsures that one stream is processed before another stream.
widenFinds the equivalent char_type to a given char.

Operators

explicit operator boolAllows 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 is not bad.

Header: <ios>

Namespace: std

Indicates a loss of integrity of the stream buffer

bool bad() const;

Return Value

true if rdstate & badbit is nonzero; otherwise false.

For more information on badbit, see ios_base::iostate.

Example

  
// 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();

Parameters

_Sb
Standard buffer to store input or output elements.

Remarks

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);

Parameters

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 (will not re-raise the exception).

Remarks

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.

Example

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);

Parameters

right
The stream whose flags you want to copy.

Return Value

The this object for the stream to which you are copying the flags.

Remarks

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.

Example

  
// 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;

Return Value

true if the end of the stream has been reached, false otherwise.

Remarks

The member function returns true if rdstate & eofbit is nonzero. For more information on eofbit, see ios_base::iostate.

Example

  
// 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);

Parameters

_Newexcept
The flags that you want to throw an exception.

Return Value

The flags that are currently specified to thrown an exception for the stream.

Remarks

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. Note that storing a new exception mask can throw an exception just like the call clear( rdstate ).

Example

  
// 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;

Return Value

true if rdstate & (badbit|failbit) is nonzero, otherwise false.

For more information on failbit, see ios_base::iostate.

Example

  
// 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 is not as wide as the stream.

 
char  
_  
type fill() const;

 
char  
_  
type fill(char 
_  
type _Char);

Parameters

_Char
The character you want as the fill character.

Return Value

The current fill character.

Remarks

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.

Example

  
// 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;

Return Value

true if rdstate == goodbit (no state flags are set), otherwise, false.

For more information on goodbit, see ios_base::iostate.

Example

See basic_ios::bad for an example of using good.

Changes the locale.

 
locale imbue(const locale& _Loc);

Parameters

_Loc
A locale string.

Return Value

The previous locale.

Remarks

If rdbuf is not a null pointer, the member function calls

rdbuf-> pubimbue(_ Loc)

In any case, it returns ios_base::imbue(_ Loc).

Example

  
// 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);

Parameters

_Sb
Standard buffer to store input or output elements.

_Isstd
Specifies whether this is a standard stream.

Remarks

The member function stores values in all member objects, so that:

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);

Parameters

right
The ios_base object to move values from.

Remarks

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;

Parameters

_Char
The char to convert.

_Default
The char that you want returned if no equivalent is found.

Return Value

The equivalent char to a given char_type.

Remarks

The member function returns use_facet<Â ctype< E> >( getloc( ) ). narrow( _Char, _Default).

Example

  
// 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;

Return Value

The operator returns a null pointer only if fail.

Example

  
// basic_ios_opgood.cpp  
// compile with: /EHsc  
#include <iostream>  
  
int main( )  
{  
using namespace std;  
cout << (bool)(&cout != 0) << endl;   // Stream is still good  
}  
  

Indicates if the stream is not bad.

 
bool operator!() const;

Return Value

Returns fail.

Example

  
// basic_ios_opbad.cpp  
// compile with: /EHsc  
#include <iostream>  
  
int main( )  
{  
using namespace std;  
cout << !cout << endl;   // Stream is not bad  
}  
  

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;

Remarks

The operator returns a value convertible to false only if fail``(). The return type is convertible only to bool, not to void * or other known scalar type.

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);

Parameters

_Sb
A stream.

Remarks

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.

Example

  
// 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 state of bits for flags.

 
iostate rdstate() const;

Return Value

The stored stream state information.

Example

  
// 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 additional flags.

 
void setstate(iostate _State);

Parameters

_State
Additional flags to set.

Remarks

The member function effectively calls clear(_ State | rdstate).

Example

  
// 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)  

Parameters

strbuf
The stream buffer to become the read buffer.

Remarks

The protected member function stores strbuf in the stream buffer pointer.It does not 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);

Parameters

str
A stream.

Return Value

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.

Remarks

tie causes two streams to be synchronized, such that, operations on one stream occur after operations on the other stream are complete.

Example

In this example, by tying cin to cout, it is 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 are 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;

Parameters

_Char
The character to convert.

Return Value

Finds the equivalent char_type to a given char.

Remarks

The member function returns use_facet< ctype< E> >( getloc). widen( _Char).

Example

  
// 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 are not swapped.

 
void swap(basic_ios&& right);

Parameters

right
The basic_ios object that is used to exchange values.

Remarks

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

Show:
© 2016 Microsoft