1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>Function Template write
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Function Template
<CODE>write
</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>write
</CODE> provide a uniform interface for writing a sequence of characters to a
<A HREF=
"../concepts/source.html">Sink
</A> or
<A HREF=
"../concepts/output_filter.html">OutputFilter
</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>write
</CODE> in the definition of an
<A HREF=
"../concepts/output_filter.html">OutputFilter
</A> which reverses its controlled sequence.
42 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><algorithm
></SPAN> <SPAN CLASS=
"comment">// reverse
</SPAN>
43 <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><vector
></SPAN>
44 <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">// output_filter
</SPAN>
45 <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">// write
</SPAN>
47 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> std;
48 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> boost::io;
50 <SPAN CLASS=
"keyword">struct
</SPAN> reversing_filter :
<SPAN CLASS=
"keyword">public
</SPAN> multichar_output_filter {
51 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> Sink
>
52 std::streamsize write(Sink
& snk,
<SPAN CLASS=
"keyword">const
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>* s, streamsize n)
54 data.insert(data.end(), s, s + n);
55 <SPAN CLASS=
"keyword">return
</SPAN> n;
57 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> Sink
>
58 <SPAN CLASS=
"keyword">void
</SPAN> close(Sink
& snk)
60 std::reverse(data.begin(), data.end());
61 boost::iostreams::write(
&data[
0], (streamsize) data.size());
64 std::vector
<<SPAN CLASS=
"keyword">char
</SPAN>> data;
67 <A NAME=
"headers"></A>
71 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/operations.hpp"><CODE><boost/iostreams/operations.hpp
></CODE></A></DT>
72 <DT><A CLASS=
"header" HREF=
"../../../../boost/iostreams/write.hpp"><CODE><boost/iostreams/write.hpp
></CODE></A></DT>
75 <A NAME=
"reference"></A>
78 <A NAME=
"description"></A>
81 <P>Attempts to write a sequence of characters to a given instance of the template parameter
<CODE>T
</CODE>, returning the number of characters written.
</P>
83 <A NAME=
"synopsis"></A>
86 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
88 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> <A CLASS=
"documented" HREF=
"#template_params">T
</A>>
90 <A CLASS=
"documented" HREF=
"#write_device">write
</A>( T
& <A CLASS=
"documented" HREF=
"#function_params">t
</A>,
91 <SPAN CLASS=
"keyword">const
</SPAN> <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>,
92 std::streamsize
<A CLASS=
"documented" HREF=
"#function_params">n
</A> );
94 <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">Sink
</A>>
96 <A CLASS=
"documented" HREF=
"#write_filter">write
</A>( T
& <A CLASS=
"documented" HREF=
"#function_params">t
</A>,
97 Sink
& <A CLASS=
"documented" HREF=
"#function_params">snk
</A>,
98 <SPAN CLASS=
"keyword">const
</SPAN> <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>,
99 std::streamsize
<A CLASS=
"documented" HREF=
"#function_params">n
</A> );
101 } }
<SPAN CLASS=
"comment">// End namespace boost::io
</SPAN></PRE>
103 <A NAME=
"template_params"></A>
104 <H4>Template Parameters
</H4>
106 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
109 <TD VALIGN=
"top"><I>T
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
110 <TD>For the first overload, a model of
<A HREF=
"../concepts/sink.html">Sink
</A>. For the second overload, a model of
<A HREF=
"../concepts/output_filter.html">OutputFilter
</A>.
113 <TD VALIGN=
"top"><I>Sink
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
114 <TD>A model of
<A HREF=
"../concepts/sink.html">Sink
</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>.
118 <A NAME=
"function_params"></A>
119 <H4>Function Parameters
</H4>
121 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
124 <TD VALIGN=
"top"><I>t
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
125 <TD>An instance of T
</CODE></TD>
128 <TD VALIGN=
"top"><I>s
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
129 <TD>A buffer containing characters to write
</TD>
132 <TD VALIGN=
"top"><I>n
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
133 <TD>The number of characters to write
</TD>
136 <TD VALIGN=
"top"><I>snk
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
137 <TD>An instance of
<CODE>Sink
</CODE>.
141 <A NAME=
"write_device"></A>
142 <H4>Semantics
— Device Types
</H4>
144 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T
>
147 <SPAN CLASS=
"keyword">const
</SPAN> <SPAN CLASS=
"keyword">typename
</SPAN> char_type_of
<T
>::type* s,
148 std::streamsize n );
</PRE>
150 <P>The semantics of
<CODE>write
</CODE> depends on the
<A HREF=
"../guide/traits.html#category">category
</A> of
<CODE>T
</CODE> as follows:
</P>
152 <TABLE STYLE=
"margin-left:2em" BORDER=
1 CELLPADDING=
4>
153 <TR><TH><CODE>category_of
<T
>::type
</CODE></TH><TH>semantics
</TH></TR>
155 <TD VALIGN=
"top">convertible to
<CODE>ostream_tag
</CODE></TD>
156 <TD>returns
<CODE>t.rdbuf()-
>sputn(s, n)
</CODE></TD>
159 <TD VALIGN=
"top">convertible to
<CODE>streambuf_tag
</CODE> but not to
<CODE>ostream_tag
</CODE></TD>
160 <TD>returns
<CODE>t.sputn(s, n)
</CODE></TD>
163 <TD VALIGN=
"top">otherwise
</TD>
164 <TD>returns
<CODE>t.write(s, n)
</CODE></TD>
168 <A NAME=
"write_filter"></A>
169 <H4>Semantics
— Filter Types
</H4>
171 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> T,
<SPAN CLASS=
"keyword">typename
</SPAN> Sink
>
175 <SPAN CLASS=
"keyword">const
</SPAN> <SPAN CLASS=
"keyword">typename
</SPAN> char_type_of
<T
>::type* s,
176 std::streamsize n );
</PRE>
178 <P>The semantics of
<CODE>write
</CODE> depends on the
<A HREF=
"../guide/traits.html#category">category
</A> of
<CODE>T
</CODE> as follows:
</P>
180 <TABLE STYLE=
"margin:0,0,2em,2em" BORDER=
1 CELLPADDING=
4>
181 <TR><TH><CODE>category_of
<T
>::type
</CODE></TH><TH>semantics
</TH></TR>
183 <TD VALIGN=
"top">convertible to
<CODE>multichar_tag
</CODE></TD>
184 <TD>returns
<CODE>t.write(snk, s, n)
</CODE></TD>
187 <TD VALIGN=
"top"><I>otherwise
</I></TD>
188 <TD>Attempts to write
<CODE>n
</CODE> characters from
<CODE>s
</CODE> by invoking
<CODE>t.put(snk, s[m])
</CODE> for each value
<CODE>m
</CODE> in the interval
<CODE>[
0, n)
</CODE>, halting if
<CODE>put
</CODE> returns
<CODE>false
</CODE>. Returns the number of characters written.
</TD>
192 <!-- Begin Footer -->
196 <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>
197 <P CLASS=
"copyright">
198 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>)