Edit

basic_ios Class

  • Article

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.

Syntax

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

Parameters

Elem
A character type.

Traits
A type providing information about the character type, defaults to char_traits < Elem >.

Remarks

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 >.

  • Formatting information.

  • 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.

Constructors

Constructor Description
basic_ios Constructs the basic_ios class.

Typedefs

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 functions

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.

Operators

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.

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 (won't 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.

For more information, see rdbuf and exceptions.

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're 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 throw 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. 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 isn't 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 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.

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:

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

For more information, see use_facet and getloc.

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 isn't bad.

bool operator!() const;

Return Value

Returns the same as calling basic_ios::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

Returns true if the stream has no errors; otherwise false.

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 stream error state.

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

Parameters

_State
Additional flags to set.

Remarks

The member function essentially calls clear(_ state | rdstate).

For more information, see clear and 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 doesn't 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 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;
}

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

For more information, see use_facet and getloc.

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 aren't 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