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/src/images/prev.png'></A> 21 <A HREF='guide.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/up.png'></A> 22 <A HREF='generic_streams.html'><IMG BORDER=0 WIDTH=19 HEIGHT=19 SRC='../../../../doc/src/images/next.png'></A> 23</DIV> 24 25<!-- End Nav --> 26 27<H2>3.2 Modes</H2> 28 29<DL class="page-index"> 30 <DT><A href="#overview">Overview</A></DT> 31 <DT><A href="#definitions">Definitions of the Modes</A></DT> 32 <DT><A href="#mode_hierarchy_diagrams">Mode Hierarchy Diagrams</A></DT> 33 <DT><A href="#mode_tags">Mode Tags</A></DT> 34 <DT><A href="#the_metafunction_mode">The metafunction <CODE>mode_of</CODE></A></DT> 35</DL> 36 37<HR STYLE="margin-top:1em"> 38 39<A NAME="overview"></A> 40<H2>Overview</H2> 41 42<P> 43 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 a <SPAN CLASS="term">mode</SPAN>. 44</P> 45 46<P> 47 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 a mode, represented by a <A HREF="#mode_tags">mode tag</A>. 48</P> 49 50<P> 51 The Iostreams library supports eight modes, described in the next section (<I>see also</I> <A CLASS="caption_ref" HREF="#mode_hierarchy_diagrams">Figure 2</A>). Of these, four are most import (<I>see </I> <A CLASS="caption_ref" HREF="#mode_hierarchy_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. 52</P> 53 54<A NAME="definitions"></A> 55<H2>Definitions of the Modes</H2> 56 57<P>Modes can be categorized in several ways: 58<UL> 59 <LI>Whether input, output or both input and output can be performed. 60 <LI>If both input and output are possible, whether there are two separate character sequences for input and output, or a single combined sequence. 61 <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. 62</UL> 63<P> 64 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: 65</P> 66 67<P>Modes are summarized in the following table:</P> 68 69<TABLE STYLE="margin-left:2em" BORDER=1 CELLPADDING=4> 70<TR><TH>Mode</TH><TH>Definition/Examples</TH></TR> 71 <!-- Input --> 72 <TR> 73 <TD VALIGN="top"><A NAME="input"></A><B>Input</B></TD> 74 <TD> 75 <TABLE> 76 <TR><TD VALIGN="top"><B>Definition:</B></TD><TD>Involves a single sequence of characters, for input</TD></TR> 77 <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::cin</CODE></TD></TR> 78 </TABLE> 79 </TD> 80 </TR> 81 82 <!-- Output --> 83 <TR> 84 <TD VALIGN="top"><A NAME="output"></A><B>Output</B></TD> 85 <TD> 86 <TABLE> 87 <TR><TD VALIGN="top"><B>Definition:</B></TD><TD>Involves a single sequence of characters, for output</TD></TR> 88 <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::cout</CODE></TD></TR> 89 </TABLE> 90 </TD> 91 </TR> 92 93 <!-- Bidirectional --> 94 <TR> 95 <TD VALIGN="top"><A NAME="bidirectional"></A><B>Bidirectional</B></TD> 96 <TD> 97 <TABLE> 98 <TR><TD VALIGN="top"><B>Definition:</B></TD> 99 <TD>Involves a two separate sequences of characters, one for input and one for output</TD></TR> 100 <TR><TD VALIGN="top"><B>Example:</B></TD><TD>A <CODE>std::iostream</CODE> for accessing a TCP connection</TD></TR> 101 </TABLE> 102 </TD> 103 </TR> 104 105 <!-- Input-seekable --> 106 <TR> 107 <TD VALIGN="top"><A NAME="input_seekable"></A><B>Input-seekable</B></TD> 108 <TD> 109 <TABLE> 110 <TR><TD VALIGN="top"><B>Definition:</B></TD> 111 <TD>Involves a single sequence of characters, for input, with a repositionable reading head</TD></TR> 112 <TR><TD VALIGN="top"><B>Examples:</B></TD><TD><CODE>std::ifstream</CODE>, <CODE>std::istringstream</CODE></TD></TR> 113 </TABLE> 114 </TD> 115 </TR> 116 117 <!-- Output-seekable --> 118 <TR> 119 <TD VALIGN="top"><A NAME="output_seekable"></A><B><PRE CLASS="plain_code"><P>Output-seekable</P></PRE></B></TD> 120 <TD> 121 <TABLE> 122 <TR><TD VALIGN="top"><B>Definition:</B></TD> 123 <TD>Involves a single sequence of characters, for output, with a repositionable writing head</TD></TR> 124 <TR><TD VALIGN="top"><B>Examples:</B></TD><TD><CODE>std::ofstream</CODE>, <CODE>std::ostringstream</CODE></TD></TR> 125 </TABLE> 126 </TD> 127 </TR> 128 129 <!-- Seekable --> 130 <TR> 131 <TD VALIGN="top"><A NAME="seekable"></A><B>Seekable</B></TD> 132 <TD> 133 <TABLE> 134 <TR><TD VALIGN="top"><B>Definition:</B></TD> 135 <TD>Involves a single sequence of characters, for input and output, with a combined repositionable read/write head</TD></TR> 136 <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::fstream</CODE></TD></TR> 137 </TABLE> 138 </TD> 139 </TR> 140 141 <!-- Dual-seekable --> 142 <TR> 143 <TD VALIGN="top"><A NAME="dual_seekable"></A><B>Dual-seekable</B></TD> 144 <TD> 145 <TABLE> 146 <TR><TD VALIGN="top"><B>Definition:</B></TD> 147 <TD>Involves a single sequence of characters, for input and output, with separate repositionable reading and writing heads</TD></TR> 148 <TR><TD VALIGN="top"><B>Example:</B></TD><TD><CODE>std::stringstream</CODE></TD></TR> 149 </TABLE> 150 </TD> 151 </TR> 152 153 <!-- Bidirectional-seekable --> 154 <TR> 155 <TD VALIGN="top"><A NAME="bidirectional_seekable"></A><B>Bidirectional-seekable</B></TD> 156 <TD> 157 <TABLE> 158 <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> 159 <TR><TD VALIGN="top"><B>Example:</B></TD><TD>No known examples</TD></TR> 160 </TABLE> 161 </TD> 162 </TR> 163 </TR> 164</TABLE> 165 166 167<P> 168 For more on the selection of modes, see the <A href="../rationale.html">Rationale</A>. 169</P> 170 171<A ID="mode_hierchy_diagrams"></A> 172<H2 ID="mode_hierarchy_diagrams">Mode Hierarchy Diagrams</H2> 173 174<P>The following diagrams display the refinement hierarchies among modes.</P> 175 176<TABLE STYLE="margin-left:2em" CELLSPACING=10> 177<TR> 178 <TD VALIGN="top"> 179 <P CLASS="caption"><B>Figure 1.</B> The four most important modes</P> 180 <IMG SRC="../graphics/important_modes.gif"> 181 </TD> 182 <TD WIDTH="30"></TD> 183 <TD ALIGN="right" VALIGN="top"> 184 <TABLE> 185 <TR><TD><IMG SRC="../graphics/key_important.gif"></TD><TD CLASS="caption">Most important</TD></TR> 186 <TR><TD><IMG SRC="../graphics/key_input_seq.gif"></TD><TD CLASS="caption">Input sequence</TD></TR> 187 <TR><TD><IMG SRC="../graphics/key_output_seq.gif"></TD><TD CLASS="caption">Output sequence</TD></TR> 188 <TR><TD><IMG SRC="../graphics/key_bidirectional_seq.gif"></TD><TD CLASS="caption">Combined input-output sequence</TD></TR> 189 <TR><TD><IMG SRC="../graphics/key_read_head.gif"></TD><TD CLASS="caption">Repositionable file-pointer for reading</TD></TR> 190 <TR><TD><IMG SRC="../graphics/key_write_head.gif"></TD><TD CLASS="caption">Repositionable file-pointer for writing</TD></TR> 191 <TR><TD><IMG SRC="../graphics/key_read_write_head.gif"></TD><TD CLASS="caption">Combined file-pointer for reading and writing</TD></TR> 192 </TABLE> 193 </TD> 194</TR> 195<TR> 196 <TD COLSPAN="3"> 197 <P CLASS="caption"><B>Figure 2.</B> The complete hierarchy of modes</P> 198 <IMG SRC="../graphics/modes.gif"> 199 </TD> 200</TR> 201</TABLE> 202 203<A NAME="mode_tags"></A> 204<H2>Mode Tags</H2> 205 206<P> 207 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. 208</P> 209<P> 210 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. 211</P> 212 213<A NAME="the_metafunction_mode"></A> 214<H2>The Metafunction <CODE>mode_of</CODE></H2> 215 216<P> 217 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>. 218 219</P> 220 221<!-- Begin Footnotes --> 222 223<HR> 224 225<P> 226 <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. 227</P> 228 229<!-- End Footnotes --> 230 231<!-- Begin Footer --> 232 233<HR> 234 235<P CLASS="copyright">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" target="_top">Jonathan Turkanis</a></P> 236<P CLASS="copyright"> 237 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>) 238</P> 239 240<!-- End Footer --> 241 242</BODY> 243
