| 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> |
|---|
