Apache C++ Standard Library Reference Guide

## basic_ifstream

Library: Input/output

    basic_ifstream  basic_istream  basic_ios  ios_base

- Local Index
- Summary
- Synopsis
- Description
- Interface
- Member Types
- Nonmember Types
- Constructors
- Member Functions
- Example
- See Also
- Standards Conformance

### Local Index

#### Members

basic_ifstream() char_type close() | int_type is_open() off_type | open() pos_type rdbuf() | traits_type

#### Non-Members

ifstream | wifstream |

### Summary

Class that supports reading from named files or other devices associated with a file descriptor

### Synopsis

    #include <fstream>

    namespace std {
      template<class charT, class traits = char_traits<charT> >
      class basic_ifstream;
    }

### Description

The class template basic_ifstream supports reading from named files or other devices associated with a file descriptor. It uses a basic_filebuf object to control the associated sequences. It inherits from basic_istream and can therefore use all the formatted and unformatted input functions.

### Interface

    namespace std {

      template<class charT, class traits = char_traits<charT> >
      class basic_ifstream
             : public basic_istream<charT, traits>
      {
       public:

        typedef traits                      traits_type;
        typedef charT                       char_type;
        typedef typename traits::int_type   int_type;
        typedef typename traits::pos_type   pos_type;
        typedef typename traits::off_type   off_type;

        basic_ifstream();

        explicit basic_ifstream(const char*,
                                ios_base::openmode = ios_base::in);

        // extensions:
        explicit basic_ifstream(const char*,
                                ios_base::openmode, long);
        explicit basic_ifstream(int, char_type* = 0,
                                streamsize = /* default size */);
        explicit basic_ifstream(FILE*, char_type* = 0,
                                streamsize = /* default size */);

        basic_filebuf<char_type, traits_type> *rdbuf() const;
        bool is_open() const;
        void open(const char*, ios_base::openmode mode =
                  ios_base::in);

        // extensions:
        void open(const char*, ios_base::openmode, long);
        void open(int, char_type* = 0,
                  streamsize = /* default size */);
        void open(FILE*, char_type* = 0,
                  streamsize = /* default size */);

        void close();

    };

### Member Types

    char_type

The type `char_type` is a synonym for the template parameter `charT`.

    int_type

The type `int_type` is a synonym of type `traits::in_type`.

    off_type

The type `off_type` is a synonym of type `traits::off_type`.

    pos_type

The type `pos_type` is a synonym of type `traits::pos_type`.

    traits_type

The type `traits_type` is a synonym for the template parameter `traits`.

### Nonmember Types

    ifstream

The type `ifstream` is a specialization of class template basic_ifstream on type `char`:

`typedef basic_ifstream<char> ifstream;`

    wifstream

The type `wifstream` is a specialization of class template basic_ifstream on type `wchar_t`:

`typedef basic_ifstream<wchar_t> wifstream;`

### Constructors

    basic_ifstream();

Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor `basic_filebuf<char_type, traits_type>(rdbuf())`. After construction, a file can be attached to the basic_ifstream object by using the `open()` member function.

    basic_ifstream(const char* s,
                   ios_base::openmode mode = ios_base::in);

Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor `basic_filebuf<char_type, traits_type>(rdbuf())`. The constructor then calls `open(s,mode)` in order to attach the file, whose name is pointed to by `s`, to the basic_ifstream object.

    basic_ifstream(const char* s, ios_base::openmode mode,
                   long protection = 0666);

Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor `basic_filebuf<char_type, traits_type>(rdbuf())`. The constructor then calls `rdbuf()->open (s, mode, protection)` in order to attach the file, whose name is pointed to by `s`, to the basic_ifstream object. The third argument, `protection`, holds file permissions. It determines the read/write/execute file permissions under UNIX, but is more limited elsewhere.

> NOTE -- This function is not part of the C++ Standard, but is included here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

    basic_ifstream(int fd, char_type *buf, streamsize n);

Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor `basic_filebuf<char_type, traits_type>(rdbuf())`.The constructor then calls `rdbuf()->open (fd, buf, n)` in order to attach the file descriptor, `fd`, to the basic_ifstream object. If the function fails, it sets `ios_base::failbit`.

> NOTE -- This function is not part of the C++ Standard, but is included here as an extension in order to manipulate pipes, sockets, or other UNIX devices that can be accessed through file descriptors. See Appendix B for a complete list of extensions of this implementation.

    basic_ifstream(FILE *fp, char_type* buf, streamsize n);

Constructs an object of class basic_ifstream, initializing the base class basic_istream with the associated file buffer. This buffer is initialized by calling the basic_filebuf constructor `basic_filebuf<char_type, traits_type>(rdbuf ())`. The constructor then calls `rdbuf()->open (fp, buf, n)` in order to attach the file pointer, `fp,` to the basic_ifstream object. If the function fails, it sets `ios_base::failbit`.

> NOTE -- This function is not part of the C++ Standard, but is provided here as a convenience extension. See Appendix B for a complete list of extensions of this implementation.

### Member Functions

    void
    close();

Calls `rdbuf()->close()`; if it fails, calls the basic_ios member function `setstate(failbit)`.

    bool
    is_open() const;

Returns `rdbuf()->is_open()`.

    void
    open(const char* s,ios_base::openmode = ios_base::in);

Calls `rdbuf()->open(s, mode)` to open the file. If the call fails, calls the basic_ios member function `setstate(failbit)`.

    void
    open(const char* s, ios_base::openmode, long protection);

Calls `rdbuf()->open (s, mode, protection)` to open the file. If the call fails, calls the basic_ios member function `setstate(failbit)`. The third argument, `protection`, holds file permissions. `protection` determines the read/write/execute file permissions under UNIX. It is more limited under DOS, since files are always readable and do not have special execute permission.

> NOTE -- The third argument, protection, is not part of the C++ Standard, but is provided here as an extension. See Appendix B for a complete list of extensions of this implementation to the Standard.

    void
    open(int fd, char_type *buf = 0,
         streamsize n = /* default size */);

Calls `rdbuf()->open (fd, buf, n)` to open the file. If the call fails, calls the basic_ios member function `setstate(failbit)`.

> NOTE -- This function is not part of the C++ Standard, but is provided here as an extension. See Appendix B for a complete list of extensions of this implementation.

    void
    open(FILE *fp, char_type *buf = 0,
         streamsize n = /* default size */);

Calls `rdbuf()->open (fp, buf, n)` to open the file. If that call fails, calls `setstate (ios::failbit)`.

> NOTE -- This function is not part of the C++ Standard, but is provided here as an extension. See Appendix B for a complete list of extensions of this implementation.

    basic_filebuf<charT,traits>*
    rdbuf() const;

Returns a pointer to the basic_filebuf associated with the stream.

### Example

    //
    //  ifstream.cpp
    //

    #include <fstream>    // for fstream
    #include <iomanip>    // for setw
    #include <iostream>   // for cout, endl

    int main ( )
    {
        const char *ntbs = "Le minot passait la piece a frotter.";
        char   c;

        try {

            // create a read/write file-stream object
            std::ifstream in ("ifstream.results.out",
                              std::ios::in | std::ios::out |
                              std::ios::trunc);

            if (!in.is_open ())
                throw (std::ios::failure ("open error"));

            // associate the ostream object's buffer with
            // the ifstream object
            std::ostream out (in.rdbuf ());

            // output ntbs in out
            out << ntbs << std::endl;

            // seek to the beginning of the file
            in.seekg (0);

            // output each space-separated word on a separate line
            while (in.get (c)) {
                if (std::isspace (c, in.getloc ()))
                    std::cout << std::endl;
                else
                    std::cout << c;
            }

            std::cout << std::endl;

            // clear stream state, failbit | eofbit set by last call
            // to get ()
            in.clear ();

            // move back to the beginning of the file
            in.seekg (0);

            char buf [40];

            // guard against buffer overflow
            in.width (sizeof buf);

            // set right justification
            std::cout << std::right;

            // does the same thing as the previous code
            // output each word on a separate line in a field
            // of width 10
            while (in >> buf) {
                std::cout.width (10);
                std::cout << buf << std::endl;
            }

            std::cout << std::endl;

            // clear flags, last in >> buf set fail bit
            // because of a newline at end of string
            in.clear ();

            // output the base info before each integer
            out << std::showbase;

            std::ostream::pos_type pos= out.tellp ();

            const long l = 10;

            // output l in hex with a field with of 10
            out << std::hex << std::setw (10) << l << std::endl;

            // output l in oct with a field with of 10
            out << std::oct << std::setw (10) << l << std::endl;

            // output l in dec with a field with of 10
            out << std::dec << std::setw (10) << l << std::endl;

            // move back to the beginning of the file
            in.seekg (0);

            // output the entire file
            std::cout << in.rdbuf () << std::endl;

            // clear the flags
            in.clear ();

            // seek the input sequence to pos
            in.seekg (pos);

            int a, b, d;

            in.unsetf (std::ios::basefield);

            // read the previous outputted integer
            in >> a >> b >> d;

            // output 3 times 10
            std::cout << a << std::endl << b << std::endl << d
                      << std::endl;
        }
        catch (std::ios::failure e) {
            std::cout << e.what ();
        }

        return 0;
    }

    Program Output:

    Le
    minot
    passait
    la
    piece
    a
    frotter.

            Le
         minot
       passait
            la
         piece
             a
      frotter.

    Le minot passait la piece a frotter.
           0xa
           012
            10

    10
    10
    10

### See Also

char_traits, ios_base, basic_ios, basic_filebuf, basic_ofstream, basic_fstream

### Standards Conformance

ISO/IEC 14882:1998 -- International Standard for Information Systems --Programming Language C++, Section 27.8.1.5