1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
---|
2 | <HTML> |
---|
3 | <HEAD> |
---|
4 | <TITLE>Modes</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">User's Guide</H1> |
---|
13 | <HR CLASS="banner"> |
---|
14 | |
---|
15 | <!-- End Banner --> |
---|
16 | |
---|
17 | <!-- Begin Nav --> |
---|
18 | |
---|
19 | <DIV CLASS='nav'> |
---|
20 | <A HREF='concepts.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/html/images/prev.png'></A> |
---|
21 | <A HREF='guide.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/html/images/up.png'></A> |
---|
22 | <A HREF='generic_streams.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/html/images/next.png'></A> |
---|
23 | </DIV> |
---|
24 | |
---|
25 | <!-- End Nav --> |
---|
26 | |
---|
27 | <A NAME="overview"></A> |
---|
28 | <H2>3.2 Modes</H2> |
---|
29 | |
---|
30 | <DL class="page-index"> |
---|
31 | <DT><A href="#overview">Overview</A></DT> |
---|
32 | <DT><A href="#definitions">Definitions of the Modes</A></DT> |
---|
33 | <DT><A href="#mode_hierchy_diagrams">Mode Hierchy Diagrams</A></DT> |
---|
34 | <DT><A href="#mode_tags">Mode Tags</A></DT> |
---|
35 | <DT><A href="#the_metafunction_mode">The metafunction <CODE>mode_of</CODE></A></DT> |
---|
36 | </DL> |
---|
37 | |
---|
38 | <HR STYLE="margin-top:1em"> |
---|
39 | |
---|
40 | <A NAME="overview"></A> |
---|
41 | <H2>Overview</H2> |
---|
42 | |
---|
43 | <P> |
---|
44 | In order for a sequence of <A HREF="concepts.html#filter_concepts">Filters</A> and <A HREF="concepts.html#device_concepts">Devices</A> to work together they must have certain properties in common. The most basic requirement is that they have the same <A HREF="traits.html#char_type">character type</A>; a collection of additional properties which Filters and Devices must share to be used for a particular purpose is called an <SPAN CLASS="term">mode</SPAN>. |
---|
45 | </P> |
---|
46 | |
---|
47 | <P> |
---|
48 | The templates <A HREF="generic_streams.html#stream_buffer"><CODE>stream_buffer</CODE></A> and <A HREF="generic_streams.html#stream"><CODE>stream</CODE></A> are each parameterized by an mode, represented by a <A HREF="#mode_tags">mode tag</A>. |
---|
49 | </P> |
---|
50 | |
---|
51 | <P> |
---|
52 | The Iostreams library supports eight modes, described in the next section (<I>see also</I> <A CLASS="caption_ref" HREF="#mode_hierchy_diagrams">Figure 2</A>). Of these, four are most import (<I>see </I> <A CLASS="caption_ref" HREF="#mode_hierchy_diagrams">Figure 1</A>). The two modes <A HREF="#input">input</A> and <A HREF="#output">output</A> are by far the most common. Readers new to the Iostreams library should feel free to concentrate primarily on these two modes. |
---|
53 | </P> |
---|
54 | |
---|
55 | <A NAME="definitions"></A> |
---|
56 | <H2>Definitions of the Modes</H2> |
---|
57 | |
---|
58 | <P>Modes can be categorized in several ways: |
---|
59 | <UL> |
---|
60 | <LI>Whether input, output or both input and output can be performed. |
---|
61 | <LI>If both input and output are possible, whether there are two separate character sequences for input and output, or a single combined sequence. |
---|
62 | <LI>Whether the reading or writing heads are repositionable, and if so, whether there are separate heads for reading and writing or a single read/write head. |
---|
63 | </UL> |
---|
64 | <P> |
---|
65 | The concepts representing <A HREF="concepts.html#optional_behavior">optional behavior</A> are not related to mode, and so need not be shared in order for a collection of Filters and Devices to work together: |
---|
66 | </P> |
---|
67 | |
---|
68 | <P>Modes are summarized in the following table:</P> |
---|
69 | |
---|
70 | <A NAME="definitions"></A> |
---|
71 | <TABLE STYLE="margin-left:2em" BORDER=1 CELLPADDING=4> |
---|
72 | <TR><TH>Mode</TH><TH>Definition/Examples</TH></TR> |
---|
73 | <!-- Input --> |
---|
74 | <TR> |
---|
75 | <TD VALIGN="top"><A NAME="input"></A><B>Input</B></TD> |
---|
76 | <TD> |
---|
77 | <TABLE> |
---|
78 | <TR><TD VALIGN="top"><B>Definition:</B></TD><TD>Involves a single sequence of characters, for input</TD></TR> |
---|
79 | <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::cin</CODE></TD></TR> |
---|
80 | </TABLE> |
---|
81 | </TD> |
---|
82 | </TR> |
---|
83 | |
---|
84 | <!-- Output --> |
---|
85 | <TR> |
---|
86 | <TD VALIGN="top"><A NAME="output"></A><B>Output</B></TD> |
---|
87 | <TD> |
---|
88 | <TABLE> |
---|
89 | <TR><TD VALIGN="top"><B>Definition:</B></TD><TD>Involves a single sequence of characters, for output</TD></TR> |
---|
90 | <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::cout</CODE></TD></TR> |
---|
91 | </TABLE> |
---|
92 | </TD> |
---|
93 | </TR> |
---|
94 | |
---|
95 | <!-- Bidirectional --> |
---|
96 | <TR> |
---|
97 | <TD VALIGN="top"><A NAME="bidirectional"></A><B>Bidirectional</B></TD> |
---|
98 | <TD> |
---|
99 | <TABLE> |
---|
100 | <TR><TD VALIGN="top"><B>Definition:</B></TD> |
---|
101 | <TD>Involves a two separate sequences of characters, one for input and one for output</TD></TR> |
---|
102 | <TR><TD VALIGN="top"><B>Example:</B></TD><TD>A <CODE>std::iostream</CODE> for accessing a TCP connection</TD></TR> |
---|
103 | </TABLE> |
---|
104 | </TD> |
---|
105 | </TR> |
---|
106 | |
---|
107 | <!-- Input-seekable --> |
---|
108 | <TR> |
---|
109 | <TD VALIGN="top"><A NAME="input_seekable"></A><B>Input-seekable</B></TD> |
---|
110 | <TD> |
---|
111 | <TABLE> |
---|
112 | <TR><TD VALIGN="top"><B>Definition:</B></TD> |
---|
113 | <TD>Involves a single sequence of characters, for input, with a repositionable reading head</TD></TR> |
---|
114 | <TR><TD VALIGN="top"><B>Examples:</B></TD><TD><CODE>std::ifstream</CODE>, <CODE>std::istringstream</CODE></TD></TR> |
---|
115 | </TABLE> |
---|
116 | </TD> |
---|
117 | </TR> |
---|
118 | |
---|
119 | <!-- Output-seekable --> |
---|
120 | <TR> |
---|
121 | <TD VALIGN="top"><A NAME="output_seekable"></A><B><PRE CLASS="plain_code"><P>Output-seekable</P></PRE></B></TD> |
---|
122 | <TD> |
---|
123 | <TABLE> |
---|
124 | <TR><TD VALIGN="top"><B>Definition:</B></TD> |
---|
125 | <TD>Involves a single sequence of characters, for output, with a repositionable writing head</TD></TR> |
---|
126 | <TR><TD VALIGN="top"><B>Examples:</B></TD><TD><CODE>std::ofstream</CODE>, <CODE>std::ostringstream</CODE></TD></TR> |
---|
127 | </TABLE> |
---|
128 | </TD> |
---|
129 | </TR> |
---|
130 | |
---|
131 | <!-- Seekable --> |
---|
132 | <TR> |
---|
133 | <TD VALIGN="top"><A NAME="seekable"></A><B>Seekable</B></TD> |
---|
134 | <TD> |
---|
135 | <TABLE> |
---|
136 | <TR><TD VALIGN="top"><B>Definition:</B></TD> |
---|
137 | <TD>Involves a single sequence of characters, for input and output, with a combined repositionable read/write head</TD></TR> |
---|
138 | <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::fstream</CODE></TD></TR> |
---|
139 | </TABLE> |
---|
140 | </TD> |
---|
141 | </TR> |
---|
142 | |
---|
143 | <!-- Dual-seekable --> |
---|
144 | <TR> |
---|
145 | <TD VALIGN="top"><A NAME="dual_seekable"></A><B>Dual-seekable</B></TD> |
---|
146 | <TD> |
---|
147 | <TABLE> |
---|
148 | <TR><TD VALIGN="top"><B>Definition:</B></TD> |
---|
149 | <TD>Involves a single sequence of characters, for input and output, with separate repositionable reading and writing heads</TD></TR> |
---|
150 | <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::stringstream</CODE></TD></TR> |
---|
151 | </TABLE> |
---|
152 | </TD> |
---|
153 | </TR> |
---|
154 | |
---|
155 | <!-- Bidirectional-seekable --> |
---|
156 | <TR> |
---|
157 | <TD VALIGN="top"><A NAME="bidirectional_seekable"></A><B>Bidirectional-seekable</B></TD> |
---|
158 | <TD> |
---|
159 | <TABLE> |
---|
160 | <TR><TD VALIGN="top"><B>Definition:</B></TD><TD>Involves a two separate sequences of characters, one for input and one for output, each with a repositionable head</TD></TR> |
---|
161 | <TR><TD VALIGN="top"><B>Example:</B></TD><TD>No known examples</TD></TR> |
---|
162 | </TABLE> |
---|
163 | </TD> |
---|
164 | </TR> |
---|
165 | </TR> |
---|
166 | </TABLE> |
---|
167 | |
---|
168 | |
---|
169 | <P> |
---|
170 | For more on the selection of modes, see the <A href="../rationale.html">Rationale</A>. |
---|
171 | </P> |
---|
172 | |
---|
173 | <A NAME="mode_hierchy_diagrams"></A> |
---|
174 | <H2>Mode Hierchy Diagrams</H2> |
---|
175 | |
---|
176 | <P>The following diagrams display the refinement hierarchies among modes.</P> |
---|
177 | |
---|
178 | <TABLE STYLE="margin-left:2em" CELLSPACING=10> |
---|
179 | <TR> |
---|
180 | <TD VALIGN="top"> |
---|
181 | <P CLASS="caption"><B>Figure 1.</B> The four most important modes</P> |
---|
182 | <IMG SRC="../graphics/important_modes.gif"> |
---|
183 | </TD> |
---|
184 | <TD WIDTH="30"></TD> |
---|
185 | <TD ALIGN="right" VALIGN="top"> |
---|
186 | <TABLE> |
---|
187 | <TR><TD><IMG SRC="../graphics/key_important.gif"></TD><TD CLASS="caption">Most important</TD></TR> |
---|
188 | <TR><TD><IMG SRC="../graphics/key_input_seq.gif"></TD><TD CLASS="caption">Input sequence</TD></TR> |
---|
189 | <TR><TD><IMG SRC="../graphics/key_output_seq.gif"></TD><TD CLASS="caption">Output sequence</TD></TR> |
---|
190 | <TR><TD><IMG SRC="../graphics/key_bidirectional_seq.gif"></TD><TD CLASS="caption">Combined input-output sequence</TD></TR> |
---|
191 | <TR><TD><IMG SRC="../graphics/key_read_head.gif"></TD><TD CLASS="caption">Repositionable file-pointer for reading</TD></TR> |
---|
192 | <TR><TD><IMG SRC="../graphics/key_write_head.gif"></TD><TD CLASS="caption">Repositionable file-pointer for writing</TD></TR> |
---|
193 | <TR><TD><IMG SRC="../graphics/key_read_write_head.gif"></TD><TD CLASS="caption">Combined file-pointer for reading and writing</TD></TR> |
---|
194 | </TABLE> |
---|
195 | </TD> |
---|
196 | </TR> |
---|
197 | <TR> |
---|
198 | <TD COLSPAN="3"> |
---|
199 | <P CLASS="caption"><B>Figure 2.</B> The complete hierarchy of modes</P> |
---|
200 | <IMG SRC="../graphics/modes.gif"> |
---|
201 | </TD> |
---|
202 | </TR> |
---|
203 | </TABLE> |
---|
204 | |
---|
205 | <A NAME="mode_tags"></A> |
---|
206 | <H2>Mode Tags</H2> |
---|
207 | |
---|
208 | <P> |
---|
209 | Each mode is represented by a <SPAN CLASS="term">mode tag</SPAN>, defined in the header <A href="../../../../boost/iostreams/traits.hpp"><CODE><boost/iostreams/traits.hpp></CODE></A>. There are eight tags for the eight modes: <CODE>input</CODE>, <CODE>output</CODE>, <CODE>bidirectional</CODE>, <CODE>input_seekable</CODE>, <CODE>output_seekable</CODE>, <CODE>seekable</CODE>, <CODE>dual_seekable</CODE> and <CODE>bidirectional_seekable</CODE>.<SUP><A CLASS="footnote_ref" NAME="note_1_ref" HREF="#note_1">[1]</A></SUP> As with standard library iterator category tags, the tag corresponding to a mode is convertible to each of the tags corresponding to modes which the first mode refines. |
---|
210 | </P> |
---|
211 | <P> |
---|
212 | In addition, there is a <SPAN CLASS="term">pseudo-mode tag</SPAN> <CODE>dual_use</CODE>, which is used to define <A href="../concepts/dual_use_filter.html">DualUseFilters</A> — which can perform input or output, but not both simultaneously. This is useful to help reduce the number of different of Filter types. The <A href="../classes/regex_filter.html">Regular Expression Filters</A>, <A href="../classes/newline_filter.html">Newline Filters</A> and compression and decompression filters all have mode <CODE>dual_use</CODE> so that they may be used with either input or output streams. |
---|
213 | </P> |
---|
214 | |
---|
215 | <A NAME="the_metafunction_mode"></A> |
---|
216 | <H2>The Metafunction <CODE>mode_of</CODE></H2> |
---|
217 | |
---|
218 | <P> |
---|
219 | To determine the mode of a model of a Filter or Device, use the metafunction <A href="../classes/mode.html"><CODE>mode_of</CODE></A>. |
---|
220 | |
---|
221 | </P> |
---|
222 | |
---|
223 | <!-- Begin Footnotes --> |
---|
224 | |
---|
225 | <HR> |
---|
226 | |
---|
227 | <P> |
---|
228 | <SUP><A CLASS="footnote_ref" NAME="note_1" HREF="#note_1_ref">[1]</A></SUP>It is traditional for tag structures to have names ending with "<CODE>_tag</CODE>". Since mode tags feature prominently in user code, this suffix was dropped to improve readability. |
---|
229 | </P> |
---|
230 | |
---|
231 | <!-- End Footnotes --> |
---|
232 | |
---|
233 | <!-- Begin Footer --> |
---|
234 | |
---|
235 | <HR> |
---|
236 | <P CLASS="copyright">Revised |
---|
237 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan --> |
---|
238 | 20 May, 2004 |
---|
239 | <!--webbot bot="Timestamp" endspan i-checksum="38504" --> |
---|
240 | </P> |
---|
241 | |
---|
242 | <P CLASS="copyright">© Copyright <A HREF="http://www.kangaroologic.com" TARGET="_top">Jonathan Turkanis</A>, 2004</P> |
---|
243 | <P CLASS="copyright"> |
---|
244 | 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>) |
---|
245 | </P> |
---|
246 | |
---|
247 | <!-- End Footer --> |
---|
248 | |
---|
249 | </BODY> |
---|