basic_ifstream Class

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

Describes an object that controls extraction of elements and encoded objects from a stream buffer of class basic_filebuf< Elem, Tr>, with elements of type Elem, whose character traits are determined by the class Tr.

Syntax

template <class Elem, class Tr = char_traits<Elem>>  
class basic_ifstream : public basic_istream<Elem, Tr>  

Parameters

Elem
The basic element of the file buffer.

Tr
The traits of the basic element of the file buffer (usually char_traits< Elem>).

Remarks

The object stores an object of class basic_filebuf< Elem, Tr>.

Example

The following example shows how to read in text from a file.

// basic_ifstream_class.cpp  
// compile with: /EHsc  
  
#include <fstream>  
#include <iostream>  
  
using namespace std;  
  
int main(int argc, char **argv)  
{  
    ifstream ifs("basic_ifstream_class.txt");  
    if (!ifs.bad())  
    {  
        // Dump the contents of the file to cout.  
        cout << ifs.rdbuf();  
        ifs.close();  
    }  
}  

Input: basic_ifstream_class.txt

This is the contents of basic_ifstream_class.txt.  

Output

This is the contents of basic_ifstream_class.txt.  

Constructors

Member Functions

Operators

Requirements

Header: <fstream>

Namespace: std

basic_ifstream::basic_ifstream

Constructs an object of type basic_ifstream.

basic_ifstream();

explicit basic_ifstream(
    const char* _Filename,  
    ios_base::openmode _Mode = ios_base::in,  
    int _Prot = (int)ios_base::_Openprot);

explicit basic_ifstream(
    const wchar_t* _Filename,  
    ios_base::openmode _Mode = ios_base::in,  
    int _Prot = (int)ios_base::_Openprot);

basic_ifstream(basic_ifstream&& right);

Parameters

_Filename
The name of the file to open.

_Mode
One of the enumerations in ios_base::openmode.

_Prot
The default file opening protection, equivalent to the shflag parameter in _fsopen, _wfsopen.

Remarks

The first constructor initializes the base class by calling basic_istream( sb), where sb is the stored object of class basic_filebuf< Elem, Tr>. It also initializes sb by calling basic_filebuf< Elem, Tr>.

The second and third constructors initializes the base class by calling basic_istream( sb). It also initializes sb by calling basic_filebuf< Elem, Tr>, then sb. open( _Filename, _Mode | ios_base::in). If the latter function returns a null pointer, the constructor calls setstate( failbit).

The fourth constructor initializes the object with the contents of right, treated as an rvalue reference.

Example

The following example shows how to read in text from a file. To create the file, see the example for basic_ofstream::basic_ofstream.

// basic_ifstream_ctor.cpp  
// compile with: /EHsc  
  
#include <fstream>  
#include <iostream>  
  
using namespace std;  
  
int main(int argc, char **argv)  
{  
    ifstream ifs("basic_ifstream_ctor.txt");  
    if (!ifs.bad())  
    {  
        // Dump the contents of the file to cout.  
        cout << ifs.rdbuf();  
        ifs.close();  
    }  
}  

basic_ifstream::close

Closes a file.

void close();

Remarks

The member function calls rdbuf -> close.

Example

See basic_filebuf::close for an example that uses close.

basic_ifstream::is_open

Determines if a file is open.

bool is_open() const;

Return Value

true if the file is open, false otherwise.

Remarks

The member function returns rdbuf -> is_open.

Example

See basic_filebuf::is_open for an example that uses is_open.

basic_ifstream::open

Opens a file.

void open(
    const char* _Filename,  
    ios_base::openmode _Mode = ios_base::in,  
    int _Prot = (int)ios_base::_Openprot);

void open(
    const char* _Filename,  
    ios_base::openmode _Mode);

void open(
    const wchar_t* _Filename,  
    ios_base::openmode _Mode = ios_base::in,  
    int _Prot = (int)ios_base::_Openprot);

void open(
    const wchar_t* _Filename,  
    ios_base::openmode _Mode);

Parameters

_Filename
The name of the file to open.

_Mode
One of the enumerations in ios_base::openmode.

_Prot
The default file opening protection, equivalent to the shflag parameter in _fsopen, _wfsopen.

Remarks

The member function calls rdbuf -> open(_ Filename, _Mode | ios_base::in). If open fails, the function calls setstate( failbit), which may throw an ios_base::failure exception.

Example

See basic_filebuf::open for an example that uses open.

basic_ifstream::operator=

Assigns the content of this stream object. This is a move assignment involving an rvalue that does not leave a copy behind.

basic_ifstream& operator=(basic_ifstream&& right);

Parameters

right
An rvalue reference to a basic_ifstream object.

Return Value

Returns *this.

Remarks

The member operator replaces the contents of the object by using the contents of right, treated as an rvalue reference. For more information, see Lvalues and Rvalues.

basic_ifstream::rdbuf

Returns the address of the stored stream buffer.

basic_filebuf<Elem, Tr> *rdbuf
() const 

Return Value

A pointer to a basic_filebuf object representing the stored stream buffer.

Example

See basic_filebuf::close for an example that uses rdbuf.

basic_ifstream::swap

Exchanges the contents of two basic_ifstream objects.

void swap(basic_ifstream& right);

Parameters

right
A reference to another stream buffer.

Remarks

The member function exchanges the contents of this object for the contents of right.

See Also

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