1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">Sink
</H1>
20 A Sink is a
<A HREF=
"device.html">Device
</A> whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"../guide/modes.html#output">output
</A>.
25 <P>A Sink provides write-access to a sequence of characters of a given type. In general, a Sink may expose this sequence in two ways:
</P>
27 <LI STYLE=
"list-style-type:lower-roman">
28 by defining a member function
<CODE>write
</CODE>, invoked indirectly by the Iostreams library through the function
<A HREF=
"../functions/write.html"><CODE>boost::iostreams::write
</CODE></A>;
30 <LI STYLE=
"list-style-type:lower-roman">
31 by defining a member function
<CODE>output_sequence
</CODE> returning a pair of pointers delimiting the sequence in its entirety.
35 <P>As a special case, Boost.Iostreams treats standard output streams as Sinks. (For details, see
<A HREF=
"../functions/write.html"><CODE>write
</CODE></A>.)
</P>
37 <P>The mode of a Sink is
<A HREF=
"../guide/modes.html#output"><CODE>output
</CODE></A> or one of its refinements.
</P>
41 <P>To be usable with the streams and stream buffers provided by the Boost Iostreams library, Sinks must model
<A HREF=
"blocking.html">Blocking
</A>.
45 <P>A model of Sink can be defined as follows:
</P>
47 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">struct
</SPAN> Sink {
48 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN> char_type;
49 <SPAN CLASS=
"keyword">typedef
</SPAN> sink_tag category;
50 std::streamsize write(
<SPAN CLASS=
"keyword">const
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>* s, std::streamsize n)
52 <SPAN CLASS=
"comment">// Write up to n characters from the buffer
53 // s to the output sequence, returning the
54 // number of characters written
</SPAN>
59 Here
<CODE>sink_tag
</CODE> is a
<A HREF=
"../guide/traits.html#category_tags">category tag
</A> identifying the type as a model of Sink. Typically a Sink can be defined by deriving from the helper classes
<A HREF=
"../classes/device.html#synopsis"><CODE>sink
</CODE></A> or
<A HREF=
"../classes/device.html#synopsis"><CODE>wsink
</CODE></A> and defining a member function
<CODE>write
</CODE>.
61 <H2>Refinement of
</H2>
63 <P><A HREF=
"device.html">Device
</A>.
</P>
66 <H2>Associated Types
</H2>
68 <P>Same as
<A HREF=
"device.html#types">Device
</A>, with the following additional requirements:
</P>
70 <TABLE CELLPADDING=
"5" BORDER=
"1">
71 <TR><TD>Category
</TD><TD>A type convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>device_tag
</CODE></A> and to
<A HREF=
"../guide/modes.html#mode_tags"><CODE>output
</CODE></A></TD></TR>
74 <A NAME=
"notation"></A>
77 <TABLE CELLPADDING=
"2">
78 <TR><TD><CODE>S
</CODE></TD><TD>- A type which is a model of Sink
</TD></TR>
79 <TR><TD><CODE>Ch
</CODE></TD><TD>- The character type
</TD></TR>
80 <TR><TD><CODE>snk
</CODE></TD><TD>- Object of type
<CODE>S
</CODE></TD></TR>
81 <TR><TD><CODE>s
</CODE></TD><TD>- Object of type
<CODE>const Ch*
</CODE></SPAN></TD></TR>
82 <TR><TD><CODE>n
</CODE></TD><TD>- Object of type
<CODE>std::streamsize
</CODE></TD></TR>
83 <TR><TD><CODE>io
</CODE></TD><TD>- Alias for namespace
<CODE>boost::iostreams
</CODE></TD></TR>
86 <A NAME=
"expressions"></A>
87 <H2>Valid Expressions / Semantics
</H2>
89 <P>Same as
<A HREF=
"device.html#types">Device
</A>, with the following additional requirements:
</P>
91 <TABLE CELLPADDING=
"5" BORDER=
"1">
92 <TR><TH>Expression
</TH><TH>Expression Type
</TH><TH>Category Precondition
</TH><TH>Semantics
</TH></TR>
95 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#char_type_of_ref">char_type_of
</A><S
>::type
</CODE></PRE>
97 <TD><CODE>typename
</CODE> of the character type
</TD>
98 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
102 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#category_ref">category_of
</A><S
>::type
</CODE></PRE>
104 <TD><CODE>typename
</CODE> of the category
</TD>
105 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
108 <TD><PRE CLASS=
"plain_code"><CODE><A HREF=
"../functions/write.html">io::write
</A>(snk, s, n)
</CODE></PRE></TD>
109 <TD><CODE>std::streamsize
</CODE></TD>
110 <TD>Not convertible to
<A HREF=
"direct.html"><CODE>direct_tag
</CODE></A></TD>
112 Writes up to
<CODE>n
</CODE> characters from the sequence beginning at
<CODE>s
</CODE> to the output sequence controlled by
<CODE>dev
</CODE>, returning the number of characters written
116 <TD><PRE CLASS=
"plain_code"><CODE>snk.output_sequence()
</CODE></PRE></TD>
117 <TD><PRE CLASS=
"plain_code"><CODE>std::pair
<Ch*,Ch*
></CODE></PRE></TD>
118 <TD>Convertible to
<A HREF=
"direct.html"><CODE>direct_tag
</CODE></A></TD>
119 <TD>Returns a pair of pointers delimiting the sequence controlled by
<CODE>snk
</CODE></TD>
126 Errors which occur during the execution of member functions
<CODE>write
</CODE> or
<CODE>output_sequence
</CODE>
127 are indicated by throwing exceptions. Attempting to write past the end of the sequence is always an error.
131 After an exception is thrown, a Sink must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour.
137 <LI>Standard output streams and stream buffers.
138 <LI><A HREF=
"../classes/array.html#array_sink"><CODE>array_sink
</CODE></A>,
<A HREF=
"../classes/file.html#file_sink"><CODE>file_sink
</CODE></A>,
<A HREF=
"../classes/file_descriptor.html#file_descriptor_sink"><CODE>file_descriptor_sink
</CODE></A>,
<A HREF=
"../classes/mapped_file.html#mapped_file_sink"><CODE>mapped_file_sink
</CODE></A>.
141 <!-- Begin Footer -->
145 <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>
146 <P CLASS=
"copyright">
147 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>)