1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Function Template read
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Function Template
<CODE>read
</CODE></H1>
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>
24 <A NAME=
"overview"></A>
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>.
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.
35 <A NAME=
"example"></A>
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>.
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>
46 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> std;
47 <SPAN CLASS=
"keyword">namespace
</SPAN> io = boost::iostreams;
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)
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;
62 <A NAME=
"headers"></A>
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>
70 <A NAME=
"reference"></A>
73 <A NAME=
"description"></A>
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.
80 <A NAME=
"synopsis"></A>
83 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
85 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">T
</A>>
86 std::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> );
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>>
91 std::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> );
96 } }
<SPAN CLASS=
"comment">// End namespace boost::io
</SPAN></PRE>
98 <A NAME=
"template_params"></A>
99 <H4>Template Parameters
</H4>
101 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
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>.
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>.
113 <A NAME=
"function_params"></A>
114 <H4>Function Parameters
</H4>
116 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
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>
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>
127 <TD VALIGN=
"top"><I>n
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
128 <TD>The maximum number of characters to read
</TD>
131 <TD VALIGN=
"top"><I>src
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
132 <TD>An instance of
<CODE>Source
</CODE>
136 <A NAME=
"read_device"></A>
137 <H4>Semantics
— Device Types
</H4>
139 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
140 std::streamsize read( T
& t,
141 <SPAN CLASS=
"keyword">typename
</SPAN> char_type_of
<T
>::type* s,
142 std::streamsize n );
</PRE>
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>
146 <TABLE STYLE=
"margin-left:2em" BORDER=
1 CELLPADDING=
4>
147 <TR><TH><CODE>category_of
<T
>::type
</CODE></TH><TH>semantics
</TH></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>
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>
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>
161 <TD VALIGN=
"top">otherwise
</TD>
162 <TD>compile-time error
</CODE></TD>
166 <A NAME=
"read_filter"></A>
167 <H4>Semantics
— Filter Types
</H4>
169 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
170 std::streamsize read( T
& t,
172 <SPAN CLASS=
"keyword">typename
</SPAN> char_type_of
<T
>::type* s,
173 std::streamsize n );
</PRE>
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>
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>
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>
184 <TD VALIGN=
"top">otherwise
</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.
191 <!-- Begin Footer -->
195 <P CLASS=
"copyright">© Copyright
2008 <a href=
"http://www.coderage.com/" target=
"_top">CodeRage, LLC
</a><br/>© Copyright
2004-
2007 <a href=
"http://www.coderage.com/turkanis/" 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>)