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.

For more information, see basic_filebuf.

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

Constructor	Description
basic_ifstream	Initializes a new instance of a basic_ifstream object.

Member functions

Member function	Description
close	Closes a file.
is_open	Determines if a file is open.
open	Opens a file.
rdbuf	Returns the address of the stored stream buffer.
swap	Exchanges the content of this basic_ifstream for the content of the provided basic_ifstream.

Operators

Operator	Description
operator=	Assigns the content of this stream object. This is a move assignment involving an rvalue that doesn't leave a copy behind.

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

For more information, see basic_istream, basic_filebuf, setstate, and open.

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). For more information, see rdbuf and basic_filebuf::open. If open fails, the function calls setstate(failbit), which may throw an ios_base::failure exception. For more information, see setstate.

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