1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>BidirectionalDevice
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">BidirectionalDevice
</H1>
20 An BidirectionalDevice is a
<A HREF=
"device.html">Device
</A> whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"../guide/modes.html#bidirectional">bidirectional
</A>.
26 An BidirectionalDevice provides read-access to a sequence of characters of a given type and write-access
27 to a separate sequence of characters of the same type. An BidirectionalDevice may expose these sequences in three ways:
<A CLASS=
"footnote_ref" NAME=
"note_1_ref" HREF=
"#note_1"><SUP>[
1]
</SUP></A>
29 <LI STYLE=
"list-style-type:lower-roman">
30 by defining member functions
<CODE>read
</CODE> and
<CODE>write
</CODE> , invoked indirectly by the Iostreams Library through the functions
<A HREF=
"../functions/read.html"><CODE>boost::iostreams::read
</CODE></A> and
<A HREF=
"../functions/write.html"><CODE>boost::iostreams::write
</CODE></A>;
32 <LI STYLE=
"list-style-type:lower-roman">
33 by overloading or specializing
<A HREF=
"../functions/read.html"><CODE>boost::iostreams::read
</CODE></A> and
<A HREF=
"../functions/write.html"><CODE>boost::iostreams::write
</CODE></A>; or
35 <LI STYLE=
"list-style-type:lower-roman">
36 by defining member functions
<CODE>input_sequence
</CODE> and
<CODE>output_sequence
</CODE> returning pairs of pointers delimiting the two sequences in their entirety.
41 <P>The i/o mode of a BidirectionalDevice is
<A HREF=
"../guide/modes.html#bidirectional">bidirectional
</A> or
<A HREF=
"../guide/modes.html#bidirectional_seekable">bidirectional-seekable
</A>.
</P>
45 <P>A model of BidirectionalDevice can be defined as follows:
</P>
47 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">struct
</SPAN> BidirectionalDevice {
48 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN> char_type;
49 <SPAN CLASS=
"keyword">typedef
</SPAN> bidirectional_device_tag category;
50 std::streamsize read(
<SPAN CLASS=
"keyword">char
</SPAN>* s, std::streamsize n)
52 <SPAN CLASS=
"comment">// Reads up to n characters from the input
53 // sequence into the buffer s, returning the number
54 // of characters read. Returning a value less than n
55 // indicates end-of-sequence.
</SPAN>
57 std::streamsize write(
<SPAN CLASS=
"keyword">const
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>* s, std::streamsize n)
59 <SPAN CLASS=
"comment">// Write up to n characters from the buffer
60 // s to the output sequence, returning the
61 // number of characters written
</SPAN>
66 Here
<CODE>category
</CODE> is a tag
<CODE>struct
</CODE> identifying the containing type as a model of BidirectionalDevice. When defining a new BidirectionalDevice, it suffices to use the tag
<CODE>bidirectional_device_tag
</CODE>. One can also derive from the helper classes
<A HREF=
"../classes/device.html"><CODE>device
<bidirectional
></CODE></A> or
<A HREF=
"../classes/device.html#synopsis"><CODE>wdevice
<bidirectional
></CODE></A>.
69 <H2>Refinement of
</H2>
71 <P><A HREF=
"source.html">Source
</A>,
<A HREF=
"sink.html">Sink
</A>.
</P>
73 <H2>Associated Types
</H2>
75 <P>Same as
<A HREF=
"device.html#types">Device
</A>, with the following additional requirements:
</P>
77 <TABLE CELLPADDING=
"5" BORDER=
"1">
78 <TR><TD>Category
</TD><TD>A type convertible to
<A HREF=
"../guide/traits.html#category_tags">device_tag
</A> and to
<A HREF=
"../guide/modes.html#mode_tags"><CODE>bidirectional
</CODE></A></TD></TR>
83 <TABLE CELLPADDING=
"2">
84 <TR><TD><CODE>D
</CODE></TD><TD>- A type which is a model of BidirectionalDevice
</TD></TR>
85 <TR><TD><CODE>Ch
</CODE></TD><TD>- The character type of
<CODE>D
</CODE></TD></TR>
86 <TR><TD><CODE>dev
</CODE></TD><TD>- Object of type
<CODE>D
</CODE></TD></TR>
87 <TR><TD><CODE>s1
</CODE></TD><TD>- Object of type
<CODE>Ch*
</CODE></SPAN></TD></TR>
88 <TR><TD><CODE>s2
</CODE></TD><TD>- Object of type
<CODE>const Ch*
</CODE></SPAN></TD></TR>
89 <TR><TD><CODE>n
</CODE></TD><TD>- Object of type
<CODE>std::streamsize
</CODE></TD></TR>
92 <H2>Valid Expressions / Semantics
</H2>
94 <P>Same as
<A HREF=
"device.html#types">Device
</A>, with the following additional requirements:
</P>
96 <TABLE CELLPADDING=
"5" BORDER=
"1">
97 <TR><TH>Expression
</TH><TH>Expression Type
</TH><TH>Category Precondition
</TH><TH>Semantics
</TH></TR>
99 <TD><PRE CLASS=
"plain_code"><CODE><A HREF=
"../functions/read.html">boost::iostreams::read
</A>(dev, s1, n)
</CODE></PRE></TD>
100 <TD><CODE>std::streamsize
</CODE></TD>
101 <TD ROWSPAN=
"2">Not convertible to
<A HREF=
"direct.html"><CODE>direct_tag
</CODE></A></TD>
103 Reads up to
<CODE>n
</CODE> characters from the input sequence controlled by
<CODE>dev
</CODE> into
<CODE>s1
</CODE>, returning the number of characters read; returning a value less than n indicates end-of-sequence
107 <TD><PRE CLASS=
"plain_code"><CODE><A HREF=
"../functions/write.html">boost::iostreams::write
</A>(dev, s2, n)
</CODE></PRE></TD>
108 <TD><CODE>std::streamsize
</CODE></TD>
110 Writes up to
<CODE>n
</CODE> characters from the sequence beginning at
<CODE>s2
</CODE> to the sequence controlled by
<CODE>dev
</CODE>, returning the number of characters written
114 <TD><PRE CLASS=
"plain_code"><CODE>dev.input_sequence()
</CODE></PRE></TD>
115 <TD><PRE CLASS=
"plain_code"><CODE>std::pair
<Ch*,Ch*
></CODE></PRE></TD>
116 <TD ROWSPAN=
"2">Convertible to
<A HREF=
"direct.html"><CODE>direct_tag
</CODE></A></TD>
117 <TD>Returns a pair of pointers delimiting the input sequence controlled by
<CODE>dev
</CODE></TD>
120 <TD><PRE CLASS=
"plain_code"><CODE>dev.output_sequence()
</CODE></PRE></TD>
121 <TD><PRE CLASS=
"plain_code"><CODE>std::pair
<Ch*,Ch*
></CODE></PRE></TD>
122 <TD>Returns a pair of pointers delimiting the output sequence controlled by
<CODE>dev
</CODE></TD>
129 Errors which occur during the execution of member functions
<CODE>read
</CODE>,
<CODE>write
</CODE>,
<CODE>input_sequence
</CODE> or
<CODE>output_sequence
</CODE> are indicated by throwing exceptions. Reaching the end of the input sequence is not an error, but attempting to write past the end of the output sequence is.
133 After an exception is thrown, an BidirectionalDevice must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour.
141 <!-- Begin Footnotes -->
144 <A CLASS=
"footnote_ref" NAME=
"note_1" HREF=
"#note_1_ref"><SUP>[
1]
</SUP></A>Strictly speaking, (i) and (ii) can be varied independently for input and output, so there are actually five possibilities.
147 <!-- End Footnotes -->
149 <!-- Begin Footer -->
153 <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>
154 <P CLASS=
"copyright">
155 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>)