1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
5 <LINK REL=
"stylesheet" href=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" href=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">User's Guide
</H1>
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>
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>
37 <HR STYLE=
"margin-top:1em">
39 <A NAME=
"overview"></A>
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>.
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>.
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.
54 <A NAME=
"definitions"></A>
55 <H2>Definitions of the Modes
</H2>
57 <P>Modes can be categorized in several ways:
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.
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:
67 <P>Modes are summarized in the following table:
</P>
69 <TABLE STYLE=
"margin-left:2em" BORDER=
1 CELLPADDING=
4>
70 <TR><TH>Mode
</TH><TH>Definition/Examples
</TH></TR>
73 <TD VALIGN=
"top"><A NAME=
"input"></A><B>Input
</B></TD>
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>
84 <TD VALIGN=
"top"><A NAME=
"output"></A><B>Output
</B></TD>
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>
93 <!-- Bidirectional -->
95 <TD VALIGN=
"top"><A NAME=
"bidirectional"></A><B>Bidirectional
</B></TD>
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>
105 <!-- Input-seekable -->
107 <TD VALIGN=
"top"><A NAME=
"input_seekable"></A><B>Input-seekable
</B></TD>
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>
117 <!-- Output-seekable -->
119 <TD VALIGN=
"top"><A NAME=
"output_seekable"></A><B><PRE CLASS=
"plain_code"><P>Output-seekable
</P></PRE></B></TD>
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>
131 <TD VALIGN=
"top"><A NAME=
"seekable"></A><B>Seekable
</B></TD>
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>
141 <!-- Dual-seekable -->
143 <TD VALIGN=
"top"><A NAME=
"dual_seekable"></A><B>Dual-seekable
</B></TD>
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>
153 <!-- Bidirectional-seekable -->
155 <TD VALIGN=
"top"><A NAME=
"bidirectional_seekable"></A><B>Bidirectional-seekable
</B></TD>
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>
168 For more on the selection of modes, see the
<A href=
"../rationale.html">Rationale
</A>.
171 <A ID=
"mode_hierchy_diagrams"></A>
172 <H2 ID=
"mode_hierarchy_diagrams">Mode Hierarchy Diagrams
</H2>
174 <P>The following diagrams display the refinement hierarchies among modes.
</P>
176 <TABLE STYLE=
"margin-left:2em" CELLSPACING=
10>
179 <P CLASS=
"caption"><B>Figure
1.
</B> The four most important modes
</P>
180 <IMG SRC=
"../graphics/important_modes.gif">
183 <TD ALIGN=
"right" VALIGN=
"top">
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>
197 <P CLASS=
"caption"><B>Figure
2.
</B> The complete hierarchy of modes
</P>
198 <IMG SRC=
"../graphics/modes.gif">
203 <A NAME=
"mode_tags"></A>
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.
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.
213 <A NAME=
"the_metafunction_mode"></A>
214 <H2>The Metafunction
<CODE>mode_of
</CODE></H2>
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>.
221 <!-- Begin Footnotes -->
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.
229 <!-- End Footnotes -->
231 <!-- Begin Footer -->
235 <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>
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>)