Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/iostreams/doc/guide/modes.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 11.0 KB
Line 
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>&lt;boost/iostreams/traits.hpp&gt;</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> &#8212; 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 -->
23820 May, 2004
239<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
240</P>
241
242<P CLASS="copyright">&copy; 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>
Note: See TracBrowser for help on using the repository browser.