# Null Devices

Overview
Acknowledgments
Headers
Reference

Class template `basic_null_source`
Class template `basic_null_sink`
Class template `basic_null_device`

## Overview

The class templates `basic_null_source`, `basic_null_sink` and `basic_null_device` are models of Device whose member functions all have trivial implementations. A `basic_null_source` is a Source whose member function `read` returns `-1`, indicating end-of-sequence. A `basic_null_sink` is a Sink whose member function `write` consumes and ignores the characters passed to it. A `basic_null_device` combines — depending on its template parameter `Mode` — the trivial `read` and `write` functions just described with a member `seek` that always returns an invalid stream position.

In addition, each of the above templates is Closable, with a no-op implementation of `close`.

## Acknowledgments

The templates described here were inspired by Daryle Walker's `basic_nullbuf` template. See Disconnected Streams.

## Headers

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

## Reference

### Class template `basic_null_source`

#### Description

Model of Source whose member function `read` returns `-1`, indicating end-of-sequence.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename Ch>
    class basic_null_source {
    public:
        typedef Ch                        char_type;
        typedef [implementation-defined]  category;

        basic_null_source();
        std::streamsize read(char_type* s, std::streamsize n);
        void close();
    };

    typedef basic_null_source<char>     null_source;
    typedef basic_null_source<wchar_t>  wnull_source;

    } } // End namespace boost::io

#### Template parameters

Ch | - | The character type type.

#### `basic_null_source::basic_null_source`

        basic_null_source();

Constructs a `basic_null_source`.

#### `basic_null_source::read`

        std::streamsize read(char_type* s, std::streamsize n);

Returns `-1`.

#### `basic_null_source::close`

        void close();

No-op.

### Class template `basic_null_sink`

#### Description

Model of Sink whose member function `write` consumes and ignores the contents of the character buffer passed to it.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename Ch>
    class basic_null_sink {
    public:
        typedef Ch                        char_type;
        typedef [implementation-defined]  category;

        basic_null_sink();
        std::streamsize write(const char_type* s, std::streamsize n);
        void close();
    };

    typedef basic_null_sink<char>     null_sink;
    typedef basic_null_sink<wchar_t>  wnull_sink;

    } } // End namespace boost::io

#### Template parameters

Ch | - | The character type type.

#### `basic_null_sink::basic_null_sink`

        basic_null_sink();

Constructs a `basic_null_sink`.

#### `basic_null_sink::write`

        std::streamsize write(const char_type* s, std::streamsize n);

Returns `n`.

#### `basic_null_sink::close`

        void close();

No-op.

### Class template `basic_null_device`

#### Description

Model of Device whose mode is specified as a template parameter, and whose member functions have trivial implementations, as follows:

- `read` returns `-1`, indicating end-of-sequence
- `write` consumes but ignores the entire contents of the character buffer passed to it
- `seek` returns an invalid stream position

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename Ch, typename Mode>
    class basic_null_device {
    public:
        typedef Ch                        char_type;
        typedef [implementation-defined]  category;

        basic_null_device();
        std::streamsize read(char_type* s, std::streamsize n);
        std::streamsize write(const char_type* s, std::streamsize n);
        stream_offset seek( stream_offset off, std::ios_base::seekdir way,
                            std::ios_base::openmode which =
                                std::ios_base::in | std::ios_base::out );
        void close();
    };

    } } // End namespace boost::io

#### Template parameters

Ch | - | The character type.
Mode | - | The mode.

#### `basic_null_device::basic_null_device`

        basic_null_device();

Constructs a `basic_null_device`.

#### `basic_null_device::read`

        std::streamsize read(char_type* s, std::streamsize n);

Returns `-1`. Enabled if `Mode` refines `input`.

#### `basic_null_device::write`

        std::streamsize write(const char_type* s, std::streamsize n);

Returns `n`. Enabled if `Mode` refines `output`.

#### `basic_null_device::seek`

         stream_offset seek( stream_offset off, std::ios_base::seekdir way,
                             std::ios_base::openmode which =
                                 std::ios_base::in | std::ios_base::out );

Returns an invalid stream position. Enabled if `Mode` permits random access.

#### `basic_null_device::close`

        void close();

No-op.

Revised 02 Feb 2008

© Copyright 2008 CodeRage, LLC
© Copyright 2004-2007 Jonathan Turkanis

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)