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.

Although read is designed to be overloaded or specialized for new Filter and Device types, the default implementation should be suitable for most purposes.

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;
    using namespace boost::io;

    struct tolower_filter : public multichar_input_filter {
        template<typename Source>
        streamsize read(Source& src, char* s, streamsize n)
            {
                streamsize result = boost::iostreams::read(src, s, n);
                for (streamsize z = 0; z < result; ++z)
                    s[z] = tolower(s[z]);
                return result;
            }
    };

Headers

<boost/iostreams/operations.hpp>

Reference

Description

Reads a sequence of characters from a given instance of the template parameter T, returning the number of characters read.

Synopsis

namespace boost { namespace iostreams {
              
template<typename T>     
std::streamsize read( T& t, typename io_char<T>::type* s, std::streamsize n );

template<typename T, typename Source>
std::streamsize read( T& t, Source& src, typename io_char<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	-	A model of Source with the same character type as `T` whose i/o 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 io_char<T>::type* s, std::streamsize n );

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

`io_category<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 io_char<T>::type* s, std::streamsize n );