mirror of
https://github.com/boostorg/iostreams.git
synced 2026-02-22 15:32:20 +00:00
251 lines
11 KiB
HTML
Executable File
251 lines
11 KiB
HTML
Executable File
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML>
|
|
<HEAD>
|
|
<TITLE>Modes</TITLE>
|
|
<LINK REL='stylesheet' HREF='../../../boost.css'>
|
|
<LINK REL='stylesheet' HREF='theme/iostreams.css'>
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<!-- Begin Banner -->
|
|
|
|
<H1 CLASS='title'>Modes</H1>
|
|
<HR CLASS='banner'>
|
|
|
|
<!-- End Banner -->
|
|
|
|
<DL class='page-index'>
|
|
<DT><A href='#overview'>Overview</A></DT>
|
|
<DT><A href='#definitions'>Definitions of the Modes</A></DT>
|
|
<DT><A href='#mode_hierchy_diagrams'>Mode Hierchy Diagrams</A></DT>
|
|
<DT><A href='#mode_tags'>Mode Tags</A></DT>
|
|
<DT><A href='#the_metafunction_mode'>The metafunction <CODE>io_mode</CODE></A></DT>
|
|
</DL>
|
|
|
|
<HR>
|
|
|
|
<A NAME='overview'>
|
|
<H2>Overview</H2>
|
|
|
|
<P>
|
|
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'>i/o mode</SPAN>.
|
|
</P>
|
|
|
|
<P>
|
|
The templates <A HREF='policy_based_streams.html#streambuf_facade'><CODE>streambuf_facade</CODE></A> and <A HREF='policy_based_streams.html#stream_facade'><CODE>stream_facade</CODE></A> are each parameterized by an i/o mode, represented by a <A HREF='#mode_tags'>mode tag</A>.
|
|
</P>
|
|
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<A NAME='definitions'>
|
|
<H2>Definitions of the Modes</H2>
|
|
|
|
<P>Modes can be categorized in several ways:
|
|
<UL>
|
|
<LI>Whether input, output or both input and output can be performed.
|
|
<LI>If both input and output are possible, whether there are two separate character sequences for input and output, or a single combined sequence.
|
|
<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.
|
|
</UL>
|
|
<P>
|
|
The following properties are <I>not</I> related to i/o mode, and so need not be shared in order for a collection of Filters and Devices to work together:
|
|
</P>
|
|
<UL>
|
|
<LI>Whether a Filter or Device is <A HREF='concepts/closable.html'>Closable</A>.
|
|
<LI>Whether a Filter or Device is <A HREF='concepts/localizable.html'>Localizable</A>.
|
|
<LI>Whether a Device is <A HREF='concepts/direct.html'>Direct</A> or <A HREF='concepts/peekable.html'>Peekable</A>.
|
|
<LI>Whether a Filter is <A HREF='concepts/multi-character.html'>Multi-Character</A>.
|
|
</UL>
|
|
|
|
<!-- <P>
|
|
<I>Note</I>: There is one important property which must be shared by all Filters and Devices in a chain, but which is <I>not</I> enforced by the library:
|
|
</P>
|
|
<UL>
|
|
<LI>Whether an input or output sequence has a definite begining and end (like an HTML document) rather than being open-ended (like a continuous stock ticker).
|
|
</UL>
|
|
<P>
|
|
Users must be careful not to combine Filters which require a bounded sequence — such as the <A HREF='classes/regex_filter.html'>Regular Expression Filters</A> — with Devices which provide access to an open-ended character sequence.
|
|
</P> -->
|
|
|
|
<P>Modes are summarized in the following table:</P>
|
|
|
|
<TABLE STYLE='margin-left:2em' BORDER=1 CELLPADDING=4>
|
|
<TR><TH>Mode</TH><TH>Definition/Examples</TH></TR>
|
|
<!-- Input -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='input'></A><B>Input</B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<TR><TD VALIGN='top'><B>Definition:</B></TD><TD>Involves a single sequence of characters, for input</TD></TR>
|
|
<TR><TD VALIGN='top'><B>Example:</B></TD><TD><CODE>std::cin</CODE></TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
|
|
<!-- Output -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='output'></A><B>Output</B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<TR><TD VALIGN='top'><B>Definition:</B></TD><TD>Involves a single sequence of characters, for output</TD></TR>
|
|
<TR><TD VALIGN='top'><B>Example:</B></TD><TD><CODE>std::cout</CODE></TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
|
|
<!-- Bidirectional -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='bidirectional'></A><B>Bidirectional</B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<TR><TD VALIGN='top'><B>Definition:</B></TD>
|
|
<TD>Involves a two separate sequences of characters, one for input and one for output</TD></TR>
|
|
<TR><TD VALIGN='top'><B>Example:</B></TD><TD>A <CODE>std::iostream</CODE> for accessing a TCP connection</TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
|
|
<!-- Input-seekable -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='input_seekable'></A><B>Input-seekable</B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<TR><TD VALIGN='top'><B>Definition:</B></TD>
|
|
<TD>Involves a single sequence of characters, for input, with a repositionable reading head</TD></TR>
|
|
<TR><TD VALIGN='top'><B>Examples:</B></TD><TD><CODE>std::ifstream</CODE>, <CODE>std::istringstream</CODE></TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
|
|
<!-- Output-seekable -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='output_seekable'></A><B><PRE CLASS='plain_code'><P>Output-seekable</P></PRE></B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<TR><TD VALIGN='top'><B>Definition:</B></TD>
|
|
<TD>Involves a single sequence of characters, for output, with a repositionable writing head</TD></TR>
|
|
<TR><TD VALIGN='top'><B>Examples:</B></TD><TD><CODE>std::ofstream</CODE>, <CODE>std::ostringstream</CODE></TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
|
|
<!-- Seekable -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='seekable'></A><B>Seekable</B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<TR><TD VALIGN='top'><B>Definition:</B></TD>
|
|
<TD>Involves a single sequence of characters, for input and output, with a combined repositionable read/write head</TD></TR>
|
|
<TR><TD VALIGN='top'><B>Example:</B></TD><TD><CODE>std::fstream</CODE></TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
|
|
<!-- Dual-seekable -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='dual_seekable'></A><B>Dual-seekable</B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<TR><TD VALIGN='top'><B>Definition:</B></TD>
|
|
<TD>Involves a single sequence of characters, for input and output, with separate repositionable reading and writing heads</TD></TR>
|
|
<TR><TD VALIGN='top'><B>Example:</B></TD><TD><CODE>std::stringstream</CODE></TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
|
|
<!-- Bidirectional-seekable -->
|
|
<TR>
|
|
<TD VALIGN='top'><A NAME='bidirectional_seekable'></A><B>Bidirectional-seekable</B></TD>
|
|
<TD>
|
|
<TABLE>
|
|
<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>
|
|
<TR><TD VALIGN='top'><B>Example:</B></TD><TD>No known examples</TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
|
|
<P>
|
|
For more on the selection of modes, see the <A HREF='Rationale.html'>Rationale</A>.
|
|
</P>
|
|
|
|
<A NAME='mode_hierchy_diagrams'>
|
|
<H2>Mode Hierchy Diagrams</H2>
|
|
|
|
<P>The following diagrams display the refinement hierarchies among modes.</P>
|
|
|
|
<TABLE STYLE='margin-left:2em' CELLSPACING=10>
|
|
<TR>
|
|
<TD VALIGN='top'>
|
|
<P CLASS='caption'><B>Figure 1.</B> The four most important modes</P>
|
|
<IMG SRC='graphics/important_modes.gif'>
|
|
</TD>
|
|
<TD WIDTH='30'></TD>
|
|
<TD ALIGN='right' VALIGN='top'>
|
|
<TABLE>
|
|
<TR><TD><IMG SRC='graphics/key_important.gif'></TD><TD CLASS='caption'>Most important</TD></TR>
|
|
<TR><TD><IMG SRC='graphics/key_input_seq.gif'></TD><TD CLASS='caption'>Input sequence</TD></TR>
|
|
<TR><TD><IMG SRC='graphics/key_output_seq.gif'></TD><TD CLASS='caption'>Output sequence</TD></TR>
|
|
<TR><TD><IMG SRC='graphics/key_bidirectional_seq.gif'></TD><TD CLASS='caption'>Combined input-output sequence</TD></TR>
|
|
<TR><TD><IMG SRC='graphics/key_read_head.gif'></TD><TD CLASS='caption'>Repositionable file-pointer for reading</TD></TR>
|
|
<TR><TD><IMG SRC='graphics/key_write_head.gif'></TD><TD CLASS='caption'>Repositionable file-pointer for writing</TD></TR>
|
|
<TR><TD><IMG SRC='graphics/key_read_write_head.gif'></TD><TD CLASS='caption'>Combined file-pointer for reading and writing</TD></TR>
|
|
</TABLE>
|
|
</TD>
|
|
</TR>
|
|
<TR>
|
|
<TD COLSPAN='3'>
|
|
<P CLASS='caption'><B>Figure 2.</B> The complete hierarchy of modes</P>
|
|
<IMG SRC='graphics/modes.gif'>
|
|
</TD>
|
|
</TR>
|
|
</TABLE>
|
|
|
|
<A NAME='mode_tags'>
|
|
<H2>Mode Tags</H2>
|
|
|
|
<P>
|
|
Each i/o 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.
|
|
</P>
|
|
<P>
|
|
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 <A HREF='compression.html'>Compression/Decompression Filters</A> all have i/o mode <CODE>dual_use</CODE> so that they may be used with either input or output streams.
|
|
</P>
|
|
|
|
<A NAME='the_metafunction_mode'>
|
|
<H2>The Metafunction <CODE>io_mode</CODE></H2>
|
|
|
|
<P>
|
|
To determine the i/o mode of a model of a Filter or Device, use the metafunction <A HREF='classes/io_mode.html'><CODE>io_mode</CODE></A>.
|
|
|
|
</P>
|
|
|
|
<!-- Begin Footnotes -->
|
|
|
|
<HR>
|
|
|
|
<P>
|
|
<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.
|
|
</P>
|
|
|
|
<!-- End Footnotes -->
|
|
|
|
<!-- Begin Footer -->
|
|
|
|
<HR>
|
|
<P CLASS='copyright'>Revised
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->
|
|
20 May, 2004
|
|
<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
|
|
</P>
|
|
|
|
<P CLASS='copyright'>© Copyright Jonathan Turkanis, 2004</P>
|
|
<P CLASS='copyright'>
|
|
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>)
|
|
</P>
|
|
|
|
<!-- End Footer -->
|
|
|
|
</BODY> |