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.

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>::typesemantics
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>::typesemantics
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.