# Function Template `read`

Overview
Example
Headers
Reference

## Overview

The two overloads of the function template `read` provide a uniform interface for reading a sequence of characters from a Source or InputFilter.

- The first overload can be used directly in the definitions of new Filter types (see Example), and figures in the specification of the Device concepts.
- The second overload is primarily for internal use by the library.

## Example

The following code illustrates the use of the function `read` in the definition of a Multi-Character InputFilter.

        #include <ctype.h>                        // tolower
        #include <boost/iostreams/concepts.hpp>   // multichar_input_filter
        #include <boost/iostreams/operations.hpp> // read

        using namespace std;
        namespace io = boost::iostreams;

        struct tolower_filter : public io::multichar_input_filter {
            template<typename Source>
            streamsize read(Source& src, char* s, streamsize n)
            {
                streamsize result;
                if ((result = io::read(src, s, n)) == -1)
                    return -1; // EOF
                for (streamsize z = 0; z < result; ++z)
                    s[z] = tolower((unsigned char) s[z]);
                return result;
            }
        };

## Headers

`<boost/iostreams/operations.hpp>`
`<boost/iostreams/read.hpp>`

## Reference

#### Description

Reads a sequence of characters from a given instance of the template parameter `T`, returning the number of characters read, or `-1` to indicate end-of-sequence.

#### Synopsis

    namespace boost { namespace iostreams {

    template<typename T>
    std::streamsize read( T& t,
                          typename char_type_of<T>::type* s,
                          std::streamsize n );

    template<typename T, typename Source>
    std::streamsize read( T& t,
                          Source& src,
                          typename char_type_of<T>::type* s,
                          std::streamsize n );

    } } // End namespace boost::io

#### Template Parameters

T | - | For the first overload, a model of Source or a standard input stream or stream buffer type. For the second overload, a model of InputFilter.
Source | - | An indirect model of Source with the same character type as `T` whose mode refines that of `T`. `Source` must also model Peekable.

#### Function Parameters

t | - | An instance of the Filter or Device type `T`
s | - | The buffer into which characters should be read
n | - | The maximum number of characters to read
src | - | An instance of `Source`

#### Semantics — Device Types

    template<typename T>
    std::streamsize read( T& t,
                          typename char_type_of<T>::type* s,
                          std::streamsize n );

The semantics of `read` depends on the category of `T` as follows:

`category_of<T>::type` | semantics
--- | ---
convertible to `istream_tag` | invokes `t.read(s, n)` and returns `t.gcount()`
convertible to `streambuf_tag` but not to `istream_tag` | returns `t.sgetn(s, n)`
not convertible to `direct_tag` | returns `t.read(s, n)`
otherwise | compile-time error

#### Semantics — Filter Types

    template<typename T>
    std::streamsize read( T& t,
                          Source& src,
                          typename char_type_of<T>::type* s,
                          std::streamsize n );

The semantics of `read` depends on the category of `T` as follows:

`category_of<T>::type` | semantics
--- | ---
convertible to `multichar_tag` | returns `t.read(src, s, n)`
otherwise | reads up to `n` characters into `s` by invoking `t.get(src)` repeatedly, halting if `traits_typre::eof` or `traits_type::would_block` is returned, where `traits_type` is `boost::iostreams::char_traits<Source>`. Returns the number of characters read, or `-1` to indicate end-of-sequence.

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)