1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4 <TITLE>Function Template read</TITLE> 5 <LINK REL="stylesheet" HREF="../../../../boost.css"> 6 <LINK REL="stylesheet" HREF="../theme/iostreams.css"> 7</HEAD> 8<BODY> 9 10<!-- Begin Banner --> 11 12 <H1 CLASS="title">Function Template <CODE>read</CODE></H1> 13 <HR CLASS="banner"> 14 15<!-- End Banner --> 16 17<DL class="page-index"> 18 <DT><A href="#overview">Overview</A></DT> 19 <DT><A href="#example">Example</A></DT> 20 <DT><A href="#headers">Headers</A></DT> 21 <DT><A href="#reference">Reference</A></DT> 22</DL> 23 24<A NAME="overview"></A> 25<H2>Overview</H2> 26 27<P> 28 The two overloads of the function template <CODE>read</CODE> provide a uniform interface for reading a sequence of characters from a <A HREF="../concepts/source.html">Source</A> or <A HREF="../concepts/input_filter.html">InputFilter</A>. 29 <UL> 30 <LI>The first overload can be used directly in the definitions of new Filter types (<I>see</I> <A HREF="#example">Example</A>), and figures in the specification of the <A HREF="../guide/concepts.html#device_concepts">Device</A> concepts. 31 <LI>The second overload is primarily for internal use by the library. 32 </UL> 33</P> 34 35<A NAME="example"></A> 36<H2>Example</H2> 37 38<P> 39 The following code illustrates the use of the function <CODE>read</CODE> in the definition of a <A HREF="../concepts/multi_character.html">Multi-Character</A> <A HREF="../concepts/input_filter.html">InputFilter</A>. 40</P> 41 42<PRE CLASS="broken_ie"> <SPAN CLASS="preprocessor">#include</SPAN> <SPAN CLASS="literal"><ctype.h></SPAN> <SPAN CLASS="comment">// tolower</SPAN> 43 <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/concepts.hpp"><SPAN CLASS="literal"><boost/iostreams/concepts.hpp></SPAN></A> <SPAN CLASS="comment">// multichar_input_filter</SPAN> 44 <SPAN CLASS="preprocessor">#include</SPAN> <A CLASS="header" HREF="../../../../boost/iostreams/operations.hpp"><SPAN CLASS="literal"><boost/iostreams/operations.hpp></SPAN></A> <SPAN CLASS="comment">// read</SPAN> 45 46 <SPAN CLASS="keyword">using</SPAN> <SPAN CLASS="keyword">namespace</SPAN> std; 47 <SPAN CLASS="keyword">namespace</SPAN> io = boost::iostreams; 48 49 <SPAN CLASS="keyword">struct</SPAN> tolower_filter : <SPAN CLASS="keyword">public</SPAN> io::multichar_input_filter { 50 <SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> Source> 51 streamsize read(Source& src, <SPAN CLASS="keyword">char</SPAN>* s, streamsize n) 52 { 53 streamsize result; 54 <SPAN CLASS="keyword">if</SPAN> ((result = io::read(src, s, n)) == <SPAN CLASS='numeric_literal'>-1</SPAN>) 55 <SPAN CLASS="keyword">return</SPAN> <SPAN CLASS='numeric_literal'>-1</SPAN>; <SPAN CLASS='comment'>// EOF</SPAN> 56 <SPAN CLASS="keyword">for</SPAN> (streamsize z = <SPAN CLASS="numeric_literal">0</SPAN>; z < result; ++z) 57 s[z] = tolower((<SPAN CLASS="keyword">unsigned</SPAN> <SPAN CLASS="keyword">char</SPAN>) s[z]); 58 <SPAN CLASS="keyword">return</SPAN> result; 59 } 60 };</PRE> 61 62<A NAME="headers"></A> 63<H2>Headers</H2> 64 65<DL> 66 <DT><A CLASS="header" HREF="../../../../boost/iostreams/operations.hpp"><CODE><boost/iostreams/operations.hpp></CODE></A></DT> 67 <DT><A CLASS="header" HREF="../../../../boost/iostreams/read.hpp"><CODE><boost/iostreams/read.hpp></CODE></A></DT> 68</DL> 69 70<A NAME="reference"></A> 71<H2>Reference</H2> 72 73<A NAME="description"></A> 74<H4>Description</H4> 75 76<P> 77 Reads a sequence of characters from a given instance of the template parameter <CODE>T</CODE>, returning the number of characters read, or <CODE>-1</CODE> to indicate end-of-sequence. 78</P> 79 80<A NAME="synopsis"></A> 81<H4>Synopsis</H4> 82 83<PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { 84 85<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">T</A>> 86std::streamsize <A CLASS="documented" HREF="#read_device">read</A>( T& <A CLASS="documented" HREF="#function_params">t</A>, 87 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="../guide/traits.html#char_type_of_ref">char_type_of</A><T>::type* <A CLASS="documented" HREF="#function_params">s</A>, 88 std::streamsize <A CLASS="documented" HREF="#function_params">n</A> ); 89 90<SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">T</A>, <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="#template_params">Source</A>> 91std::streamsize <A CLASS="documented" HREF="#read_filter">read</A>( T& <A CLASS="documented" HREF="#function_params">t</A>, 92 Source& <A CLASS="documented" HREF="#function_params">src</A>, 93 <SPAN CLASS="keyword">typename</SPAN> <A CLASS="documented" HREF="../guide/traits.html#char_type_of_ref">char_type_of</A><T>::type* <A CLASS="documented" HREF="#function_params">s</A>, 94 std::streamsize <A CLASS="documented" HREF="#function_params">n</A> ); 95 96} } <SPAN CLASS="comment">// End namespace boost::io</SPAN></PRE> 97 98<A NAME="template_params"></A> 99<H4>Template Parameters</H4> 100 101<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 102<TR> 103 <TR> 104 <TD VALIGN="top"><I>T</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 105 <TD>For the first overload, a model of <A HREF="../concepts/source.html">Source</A> or a standard input stream or stream buffer type. For the second overload, a model of <A HREF="../concepts/input_filter.html">InputFilter</A>. 106 </TR> 107 <TR> 108 <TD VALIGN="top"><I>Source</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 109 <TD>An <A HREF="../concepts/direct.html">indirect</A> model of <A HREF="../concepts/source.html">Source</A> with the same <A HREF="../guide/traits.html#char_type">character type</A> as <CODE>T</CODE> whose <A HREF="../guide/modes.html">mode</A> refines that of <CODE>T</CODE>. <CODE>Source</CODE> must also model <A HREF="../concepts/peekable.html">Peekable</A>. 110 </TR> 111</TABLE> 112 113<A NAME="function_params"></A> 114<H4>Function Parameters</H4> 115 116<TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> 117<TR> 118 <TR> 119 <TD VALIGN="top"><I>t</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 120 <TD>An instance of the Filter or Device type <CODE>T</CODE></TD> 121 </TR> 122 <TR> 123 <TD VALIGN="top"><I>s</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 124 <TD>The buffer into which characters should be read</TD> 125 </TR> 126 <TR> 127 <TD VALIGN="top"><I>n</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 128 <TD>The maximum number of characters to read</TD> 129 </TR> 130 <TR> 131 <TD VALIGN="top"><I>src</I></TD><TD WIDTH="2em" VALIGN="top">-</TD> 132 <TD>An instance of <CODE>Source</CODE> 133 </TR> 134</TABLE> 135 136<A NAME="read_device"></A> 137<H4>Semantics — Device Types</H4> 138 139<PRE CLASS="broken_ie"><SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> T> 140std::streamsize read( T& t, 141 <SPAN CLASS="keyword">typename</SPAN> char_type_of<T>::type* s, 142 std::streamsize n );</PRE> 143 144<P>The semantics of <CODE>read</CODE> depends on the <A HREF="../guide/traits.html#category">category</A> of <CODE>T</CODE> as follows:</P> 145 146<TABLE STYLE="margin-left:2em" BORDER=1 CELLPADDING=4> 147 <TR><TH><CODE>category_of<T>::type</CODE></TH><TH>semantics</TH></TR> 148 <TR> 149 <TD VALIGN="top">convertible to <A HREF="../guide/traits.html#category_tags"><CODE>istream_tag</CODE></A></TD> 150 <TD>invokes <CODE>t.read(s, n)</CODE> and returns <CODE>t.gcount()</CODE></TD> 151 </TR> 152 <TR> 153 <TD VALIGN="top">convertible to <A HREF="../guide/traits.html#category_tags"><CODE>streambuf_tag</CODE></A> but not to <A HREF="../guide/traits.html#category_tags"><CODE>istream_tag</CODE></A></TD> 154 <TD>returns <CODE>t.sgetn(s, n)</CODE></TD> 155 </TR> 156 <TR> 157 <TD VALIGN="top"><I>not</I> convertible to <A HREF="../guide/traits.html#category_tags"><CODE>direct_tag</CODE></A></TD> 158 <TD>returns <CODE>t.read(s, n)</CODE></TD> 159 </TR> 160 <TR> 161 <TD VALIGN="top">otherwise</TD> 162 <TD>compile-time error</CODE></TD> 163 </TR> 164</TABLE> 165 166<A NAME="read_filter"></A> 167<H4>Semantics — Filter Types</H4> 168 169<PRE CLASS="broken_ie"><SPAN CLASS="keyword">template</SPAN><<SPAN CLASS="keyword">typename</SPAN> T> 170std::streamsize read( T& t, 171 Source& src, 172 <SPAN CLASS="keyword">typename</SPAN> char_type_of<T>::type* s, 173 std::streamsize n );</PRE> 174 175<P>The semantics of <CODE>read</CODE> depends on the <A HREF="../guide/traits.html#category">category</A> of <CODE>T</CODE> as follows:</P> 176 177<TABLE STYLE="margin-bottom:2em;margin-left:2em" BORDER=1 CELLPADDING=4> 178 <TR><TH><CODE>category_of<T>::type</CODE></TH><TH>semantics</TH></TR> 179 <TR> 180 <TD VALIGN="top">convertible to <A HREF="../guide/traits.html#category_tags"><CODE>multichar_tag</CODE></A></TD> 181 <TD>returns <CODE>t.read(src, s, n)</CODE></TD> 182 </TR> 183 <TR> 184 <TD VALIGN="top">otherwise</TD> 185 <TD> 186 reads up to <CODE>n</CODE> characters into <CODE>s</CODE> by invoking <CODE>t.get(src)</CODE> repeatedly, halting if <CODE>traits_typre::eof</CODE> or <A HREF="../classes/char_traits.html#would_block"><CODE>traits_type::would_block</CODE></A> is returned, where <CODE>traits_type</CODE> is <A HREF="../classes/char_traits.html"><CODE>boost::iostreams::char_traits<Source></CODE></A></A>. Returns the number of characters read, or <CODE>-1</CODE> to indicate end-of-sequence. 187 </TD> 188 </TR> 189</TABLE> 190 191<!-- Begin Footer --> 192 193<HR> 194 195<P CLASS="copyright">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" target="_top">Jonathan Turkanis</a></P> 196<P CLASS="copyright"> 197 Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at <A HREF="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</A>) 198</P> 199 200<!-- End Footer --> 201 202</BODY>