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 );