basic_ios Class

  • Article

 

The latest version of this topic can be found at basic_ios Class.

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.

Syntax

 
template <class   
Elem  , class   
Traits>  
class basic_ios : public ios_base

Parameters

Elem
A type.

Traits
A variable of type char_traits.

Remarks

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

Constructors

basic_ios Constructs the basic_ios class.

Typedefs

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 Functions

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 is not 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 are not swapped.
tie Ensures that one stream is processed before another stream.
widen Finds the equivalent char_type to a given char.

Operators

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

Requirements

Header: <ios>

Namespace: std

basic_ios::bad

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

basic_ios::basic_ios

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.

basic_ios::char_type

A synonym for the template parameter Elem.

 
typedef Elem char  
_  
type;

basic_ios::clear

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.

basic_ios::copyfmt

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

basic_ios::eof

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

basic_ios::exceptions

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

basic_ios::fail

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

basic_ios::fill

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

basic_ios::good

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.

basic_ios::imbue

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

basic_ios::init

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:

  • rdbuf returns _Sb.

  • tie returns a null pointer.

  • rdstate returns goodbit if _Sb is nonzero; otherwise, it returns badbit.

  • exceptions returns goodbit.

  • flags returns skipws | dec.

  • width returns 0.

  • precision returns 6.

  • fill returns the space character.

  • getloc returns locale::classic.

  • iword returns zero, and pword returns a null pointer for all argument values.

basic_ios::int_type

A synonym for traits_type::int_type.

typedef typename traits_type::int_type int_type;

basic_ios::move

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.

basic_ios::narrow

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

basic_ios::off_type

A synonym for traits_type::off_type.

typedef typename traits_type::off_type off_type;

basic_ios::operator void *

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  
}  
  

1

basic_ios::operator!

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  
}  
  

0

basic_ios::operator bool

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.

basic_ios::pos_type

A synonym for traits_type::pos_type.

typedef typename traits_type::pos_type pos_type;

basic_ios::rdbuf

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

basic_ios::rdstate

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

basic_ios::setstate

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

basic_ios::set_rdbuf

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.

basic_ios::tie

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

basic_ios::traits_type

A synonym for the template parameter Traits.

 
typedef Traits traits  
_  
type;

basic_ios::widen

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

basic_ios::swap

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.

See Also

Thread Safety in the C++ Standard Library
iostream Programming
iostreams Conventions