Function Template `read`

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\>](../../../../boost/iostreams/concepts.hpp)// multichar\_input\_filter#include[\<boost/iostreams/operations.hpp\>](../../../../boost/iostreams/operations.hpp)// readusingnamespacestd;namespaceio = boost::iostreams;structtolower_filter :publicio::multichar_input_filter {template<typenameSource>
        streamsize read(Source& src,char* s, streamsize n)
        {
            streamsize result;if((result = io::read(src, s, n)) ==-1)return-1;// EOFfor(streamsize z =0; z < result; ++z)
                s[z] = tolower((unsignedchar) s[z]);returnresult;
        }
    };

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

namespaceboost {namespaceiostreams {template<typename[T](#template_params)>     
std::streamsize[read](#read_device)( T&[t](#function_params),typename[char\_type\_of](../guide/traits.html#char_type_of_ref)<T>::type*[s](#function_params), 
                      std::streamsize[n](#function_params));template<typename[T](#template_params),typename[Source](#template_params)>
std::streamsize[read](#read_filter)( T&[t](#function_params),
                      Source&[src](#function_params),typename[char\_type\_of](../guide/traits.html#char_type_of_ref)<T>::type*[s](#function_params), 
                      std::streamsize[n](#function_params));

} }// 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<typenameT>     
std::streamsize read( T& t,typenamechar_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<typenameT>
std::streamsize read( T& t,
                      Source& src,typenamechar_type_of<T>::type* s,
                      std::streamsize n );