# File Wrappers

Overview
Headers
Reference

- Class template `basic_file_source`
- Class template `basic_file_sink`
- Class template `basic_file`

## Overview

The class templates `basic_file_source`, `basic_file_sink` and `basic_file` are wrappers for `std::basic_filebuf` which are CopyConstructible and Assignable. They are useful whenever one wants to access a file without managing the lifetime of a standard file stream or stream buffer. This is because when a stream or stream buffer is added to a `filtering_streambuf` or `filtering_stream` it is stored as a reference which must remain valid until that stream or stream buffer is removed from the chain.

The most common specializations are accessible via the typedefs `file_source`, `file_sink`, `file`, `wfile_source`, `wfile_sink` and `wfile`.

## Headers

`<boost/iostreams/device/file.hpp>`

## Reference

### Class template `basic_file_source`

#### Description

CopyConstructible and Assignable wrapper for a `std::basic_filebuf` opened in read-only mode.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename Ch>
    class basic_file_source {
    public:
        typedef Ch                      char_type;
        typedef implementation-defined  category;
        basic_file_source( const std::string& path,
                           std::ios_base::openmode mode =
                               std::ios_base::in );
        bool is_open() const;
        ...
    };

    typedef basic_file_source<char>     file_source;
    typedef basic_file_source<wchar_t>  wfile_source;

    } } // End namespace boost::iostreams

#### Template parameters

Ch | - | The character type.

#### `basic_file_source::basic_file_source`

        basic_file_source( const std::string& path,
                           std::ios_base::openmode mode );

Constructs a `basic_file_source` which wraps a `std::basic_filebuf` `buf` opened as follows:

        mode |= std::ios_base::in;
        mode &= ~std::ios_base::out;
        buf.open(path.c_str(), mode);

#### `basic_file_source::is_open`

        bool is_open() const;

Returns `true` if the underlying instance of `basic_filebuf` was opened successfully.

### Class template `basic_file_sink`

#### Description

CopyConstructible and Assignable wrapper for a `std::basic_filebuf` opened in write-only mode.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename Ch>
    class basic_file_sink {
    public:
        typedef Ch                      char_type;
        typedef implementation-defined  category;
        basic_file_sink( const std::string& path,
                         std::ios_base::openmode mode =
                             std::ios_base::out );
        bool is_open() const;
        ...
    };

    typedef basic_file_sink<char>     file_sink;
    typedef basic_file_sink<wchar_t>  wfile_sink;

    } } // End namespace boost::iostreams

#### Template parameters

Ch | - | The character type.

#### `basic_file_sink::basic_file_sink`

        basic_file_sink( const std::string& path,
                         std::ios_base::openmode mode );

Constructs a `basic_file_sink` which wraps a `std::basic_filebuf` `buf` opened as follows:

        mode |= std::ios_base::out;
        mode &= ~std::ios_base::in;
        buf.open(path.c_str(), mode);

#### `basic_file_sink::is_open`

        bool is_open() const;

Returns `true` if the underlying instance of `basic_filebuf` was opened successfully.

### Class template `basic_file`

#### Description

CopyConstructible and Assignable wrapper for a `std::basic_filebuf` opened in read-write mode by default.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename Ch>
    class basic_file {
    public:
        typedef Ch                      char_type;
        typedef implementation-defined  category;
        basic_file( const std::string& path,
                    std::ios_base::openmode mode =
                        std::ios_base::in | std::ios_base::out );
        bool is_open() const;
        ...
    };

    typedef basic_file<char>     file;
    typedef basic_file<wchar_t>  wfile;

    } } // End namespace boost::iostreams

#### Template parameters

Ch | - | The character type.

#### `basic_file_::basic_file`

        basic_file( const std::string& path,
                    std::ios_base::openmode mode );

Constructs a `basic_file` which wraps a `std::basic_filebuf` `buf` opened as follows:

        mode |= std::ios_base::in | std::ios_base::out;
        buf.open(path.c_str(), mode);

#### `basic_file::is_open`

        bool is_open() const;

Returns `true` if the underlying instance of `basic_filebuf` was opened successfully.

Revised 20 May, 2004

© Copyright Jonathan Turkanis, 2004

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)