boost/iostreams
2
0
Fork 0
mirror of https://github.com/boostorg/iostreams.git synced 2026-02-22 15:32:20 +00:00
Code Issues Projects Releases Wiki Activity
Files
64e784fc6d395fbdfd9da311fcd3eda331bf1acd
iostreams/doc/concepts/device.html

278 lines
15 KiB
HTML
Executable File
Raw Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<TITLE>Device</TITLE>
<LINK REL='stylesheet' HREF='../../../../boost.css'>
<LINK REL='stylesheet' HREF='../theme/iostreams.css'>
<STYLE> P.concept { margin:.5em } </STYLE>
</HEAD>
<BODY>
<!-- Begin Banner -->
<H1 CLASS='title'>Device</H1>
<HR CLASS='banner'>
<!-- End Banner -->
<H2>Description</H2>
<P>
A Device provides access to one or two character sequences. It may provide access to an <SPAN CLASS='term'>input sequence</SPAN>, for reading, an <SPAN CLASS='term'>output sequence</SPAN>, for writing, or both. The relationship between the two sequences, as well as the operations that may be performed on them, depends on the Device type.
</P>
<P>
Typically, Devices are class types which define one or more member functions <CODE>read</CODE>, <CODE>write</CODE> and <CODE>seek</CODE> having interfaces resembling the member functions <CODE>sgetn</CODE>, <CODE>sputn</CODE> and <CODE>pubseekoff</CODE> of <CODE>std::basic_streambuf</CODE>.<A CLASS='footnote_ref' NAME='note_1_ref' HREF='#note_1'><SUP>[1]</SUP></A> The concept Device is defined a bit more broadly, however, so that pre-existing types, such as standard streams and stream buffers, can be treated as models of Device, and so that Devices managing in-memory sequences can be optimized.
</P>
<P>
Each Device type has an associated character type and category. The <A HREF='../traits.html#char_type'>character type</A> is the type of the characters in the sequence or sequences controlled by instances of <CODE>D</CODE>. The <A HREF='../traits.html#category'>category</A> is a tag structure which the Iostreams Library relies on to determine which operations <CODE>D</CODE> supports. Its function is similar to the <CODE>iterator_category</CODE> member of <CODE>std::iterator_traits</CODE>.<A CLASS='footnote_ref' NAME='note_2_ref' HREF='#note_2'><SUP>[2]</SUP></A>
</P>
<P>
There is one refinement of Device for each of the eight <A HREF='../modes.html'>modes</A>, and for each such refinement there is a corresponding refinement of <A HREF='filter.html'>Filter</A>. In order to express this corresponce cleanly, it is helpful to include the requirements of the various refinements of Device in the definition of Device itself, qualified by category. The various refinements of Device can then be characterized exactly by the following definitions. For convenience, the requirements of the four most common Device refinements are also documented individually.
</P>
<TABLE CELLPADDING='5' BORDER='1'>
<TR><TH>Concept</TH><TH>Definition</TH></TR>
<TR>
<TD><A href='source.html'>Source</A></TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#input'><CODE>input</CODE></A></TD>
</TR>
<TR>
<TD><A href='sink.html'>Sink</A></TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#output'><CODE>output</CODE></A></TD>
</TR>
<TR>
<TD><A href='bidirectional_device.html'>BidirectionalDevice</A></TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#bidirectional'><CODE>bidirectional</CODE></A></TD>
</TR>
<TR>
<TD><A href='seekable_device.html'>SeekableDevice</A></TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#seekable'><CODE>seekable</CODE></A></TD>
</TR>
<TR>
<TD>SeekableSource</TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#input_seekable'><CODE>input_seekable</CODE></A></TD>
</TR>
<TR>
<TD>SeekableSink</TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#output_seekable'><CODE>output_seekable</CODE></A></TD>
</TR>
<TR>
<TD>BidirectionalSeekableDevice</TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#bidirectional_seekable'><CODE>bidirectional_seekable</CODE></A></TD>
</TR>
<TR>
<TD>DualSeekableDevice</TD>
<TD>Refinement of Device with io_mode convertible to <A HREF='../modes.html#dual_seekable'><CODE>dual_seekable</CODE></A></TD>
</TR>
</TABLE>
<H2>Standard Streams and Stream Buffers</H2>
<P>
Standard streams and stream buffer types are model of Device. It is not possible to tell the exact <A HREF='../modes.html'>i/o mode</A> of an arbitrary stream or stream buffer, so the Iostreams Library has to guess. (<I>See</I> <A HREF='../classes/mode.html#mode_type'>Class Template <CODE>io_mode</CODE>.</A>) If the i/o mode selected by default does not accurately reflect a particular implementation, the function template <A HREF='../functions/adapt.html'><CODE>adapt</CODE></A> may be used.
</P>
<H2>Refinement of</H2>
<A NAME='types'></A>
<H2>Associated Types</H2>
<TABLE CELLPADDING='5' BORDER='1'>
<TR><TD>Character type</TD><TD>The type of the characters in the controlled sequences</TD></TR>
<TR>
<TD>Category</TD>
<TD>
A type convertible to <A HREF="../traits.html#category_tags">device_tag</A> and to a unique <I>most-derived</I> <A HREF="../modes.html#mode_tags">mode tag</A>
</TD>
</TR>
<TR>
<TD>Mode</TD>
<TD>
The unique <I>most-derived</I> <A HREF="../modes.html#mode_tags">mode tag</A> to which Category is convertible
</TD>
</TR>
</TABLE>
<H2>Notation</H2>
<TABLE CELLPADDING='2'>
<TR><TD><CODE>D</CODE></TD><TD>- A type which is a model of Device</TD></TR>
<TR><TD><CODE>Ch</CODE></TD><TD>- The character type of <CODE>D</CODE></TD></TR>
<TR><TD><CODE>dev</CODE></TD><TD>- Object of type <CODE>D</CODE></TD></TR>
<TR><TD><CODE>s1</CODE></TD><TD>- Object of type <CODE>Ch*</CODE></TD></TR>
<TR><TD><CODE>s2</CODE></TD><TD>- Object of type <CODE>const Ch*</CODE></TD></TR>
<TR><TD><CODE>n</CODE></TD><TD>- Object of type <CODE>std::streamsize</CODE></TD></TR>
<TR><TD><CODE>off</CODE></TD><TD>- Object of type <CODE>std::streamoff</CODE></TD></TR>
<TR><TD><CODE>way</CODE></TD><TD>- Object of type <CODE>std::ios_base::seekdir</CODE></TD></TR>
<TR><TD><CODE>which</CODE></TD><TD>- Object of type <CODE>std::ios_base::openmode</CODE></TD></TR>
</TABLE>
<A NAME='expressions'></A>
<H2>Valid Expressions &#8212; Typenames</H2>
<TABLE CELLPADDING='5' BORDER='1'>
<TR><TH>Expression</TH><TH>Expression Type</TH></TR>
<TR>
<TD><CODE>typename <A HREF='../traits.html'>io_char</A>&lt;D&gt;::type</CODE></TD>
<TD><CODE>typename</CODE> of the character type</TD>
</TR>
<TR>
<TD><CODE>typename <A HREF='../traits.html'>io_category</A>&lt;D&gt;::type</CODE></TD>
<TD><CODE>typename</CODE> of the category</TD>
</TR>
</TABLE>
<H2>Valid Expressions / Semantics &#8212; Input</H2>
<TABLE CELLPADDING='5' BORDER='1'>
<TR><TH>Expression</TH><TH>Expression Type</TH><TH>Category Precondition</TH><TH>Semantics</TH></TR>
<TR>
<TD><PRE CLASS='plain_code'><CODE><A HREF='../functions/read.html'>boost::iostreams::read</A>(dev, s1, n)</CODE></PRE></TD>
<TD><CODE>std::streamsize</CODE></TD>
<TD>
Convertible to <A HREF="../modes.html#mode_tags"><CODE>input</CODE></A> but not to <A HREF="../traits.html#category_tags"><CODE>direct_tag</CODE></A>
</TD>
<TD>
Reads up to <CODE>n</CODE> characters from the sequence controlled by <CODE>dev</CODE> into <CODE>s1</CODE>, returning the number of characters read; returning a value less than n indicates end-of-sequence
</TD>
</TR>
<TR>
<TD><PRE CLASS='plain_code'><CODE>dev.input_sequence()</CODE></PRE></TD>
<TD><PRE CLASS='plain_code'><CODE>std::pair&lt;Ch*,Ch*&gt;</CODE></PRE></TD>
<TD>
Convertible to <A HREF="../modes.html#mode_tags"><CODE>input</CODE></A> and to <A HREF="../traits.html#category_tags"><CODE>direct_tag</CODE></A>
</TD>
<TD>Returns a pair of pointers delimiting the sequence controlled by <CODE>dev</CODE></TD>
</TR>
</TABLE>
<H2>Valid Expressions / Semantics &#8212; Output</H2>
<TABLE CELLPADDING='5' BORDER='1'>
<TR><TH>Expression</TH><TH>Expression Type</TH><TH>Category Precondition</TH><TH>Semantics</TH></TR>
<TR>
<TD><PRE CLASS='plain_code'><CODE><A HREF='../functions/write.html'>boost::iostreams::write</A>(dev, s2, n)</CODE></PRE></TD>
<TD><CODE>void</CODE></TD>
<TD>
Convertible to <A HREF="../modes.html#mode_tags"><CODE>output</CODE></A> but not to <A HREF="../traits.html#category_tags"><CODE>direct_tag</CODE></A>
</TD>
<TD>
Writes <CODE>n</CODE> characters from the sequence beginning at <CODE>s2</CODE> to the sequence controlled by <CODE>dev</CODE>
</TD>
</TR>
<TR>
<TD><PRE CLASS='plain_code'><CODE>dev.output_sequence()</CODE></PRE></TD>
<TD><PRE CLASS='plain_code'><CODE>std::pair&lt;Ch*,Ch*&gt;</CODE></PRE></TD>
<TD>
Convertible to <A HREF="../modes.html#mode_tags"><CODE>output</CODE></A> and to <A HREF="../traits.html#category_tags"><CODE>direct_tag</CODE></A>
</TD>
<TD>Returns a pair of pointers delimiting the sequence controlled by <CODE>dev</CODE></TD>
</TR>
</TABLE>
<H2>Valid Expressions / Semantics &#8212; Random-Access</H2>
<TABLE CELLPADDING='5' BORDER='1'>
<TR><TH>Expression</TH><TH>Expression Type</TH><TH>Category Precondition</TH><TH>Semantics</TH></TR>
<TR>
<TD><PRE CLASS='plain_code'><CODE><A HREF='../functions/seek.html'>boost::iostreams::seek</A>(dev, off, way)</CODE></PRE></TD>
<TD><CODE>std::streamoff</CODE></TD>
<TD>
Convertible to <A HREF="../modes.html#mode_tags"><CODE>seekable</CODE></A> but not to <A HREF="../traits.html#category_tags"><CODE>direct_tag</CODE></A>
</TD>
<TD>
<P CLASS='concept'>
Advances the read/write head by <CODE>off</CODE> characters, returning the new position, where the offset is calculated from:
</P>
<UL STYLE='margin:0,0,0,auto'>
<LI STYLE='list-style-type:disc;list-style-image:none'>the start of the sequence if <CODE>way</CODE> is <CODE>ios_base::beg</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the current position if <CODE>way</CODE> is <CODE>ios_base::cur</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the end of the sequence if <CODE>way</CODE> is <CODE>ios_base::end</CODE>
</UL>
<!-- Advances the read/write head by <CODE>off</CODE> characters, returning the new position, where the offset is calculated from:
<UL STYLE='margin:0,0,0,auto'>
<LI STYLE='list-style-type:disc;list-style-image:none'>the start of the sequence if <CODE>way</CODE> is <CODE>ios_base::beg</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the current position if <CODE>way</CODE> is <CODE>ios_base::cur</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the end of the sequence if <CODE>way</CODE> is <CODE>ios_base::end</CODE>
</UL> -->
</TD>
</TR>
<TR>
<TD><PRE CLASS='plain_code'><CODE><A HREF='../functions/seek.html'>boost::iostreams::seek</A>(dev, off, way, which)</CODE></PRE></TD>
<TD><CODE>std::streamoff</CODE></TD>
<TD>
Convertible to <A HREF="../modes.html#mode_tags"><CODE>dual_seekable</CODE></A> or <A HREF="../modes.html#mode_tags"><CODE>bidirectional_seekable</CODE></A> but not to <A HREF="../traits.html#category_tags"><CODE>direct_tag</CODE></A>
</TD>
<TD>
<P CLASS='concept'>
Repositions the read head (if <CODE>which</CODE> is <CODE>std::ios_base::in</CODE>), the write head (if <CODE>which</CODE> is <CODE>std::ios_base::out</CODE>) or both heads (if <CODE>which</CODE> is <CODE>std::ios_base::in | std::ios_base::out</CODE>) by <CODE>off</CODE> characters, returning the new position, where the offset is calculated from
</P>
<UL STYLE='margin:0,0,0,auto'>
<LI STYLE='list-style-type:disc;list-style-image:none'>the start of the sequence if <CODE>way</CODE> is <CODE>ios_base::beg</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the current position if <CODE>way</CODE> is <CODE>ios_base::cur</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the end of the sequence if <CODE>way</CODE> is <CODE>ios_base::end</CODE>
</UL>
<P CLASS='concept'>
The result is undefined if <CODE>way</CODE> is <CODE>ios_base::cur</CODE> and <CODE>which</CODE> is <CODE>(std::ios_base::in | std::ios_base::out)</CODE>.
</P>
<!-- Repositions the read head (if <CODE>which</CODE> is <CODE>std::ios_base::in</CODE>), the write head (if <CODE>which</CODE> is <CODE>std::ios_base::out</CODE>) or
both heads (if <CODE>which</CODE> is <CODE>std::ios_base::in | std::ios_base::out</CODE>) by <CODE>off</CODE> characters, returning the new position, where the offset is calculated from:
<UL STYLE='margin:0,0,0,auto'>
<LI STYLE='list-style-type:disc;list-style-image:none'>the start of the sequence if <CODE>way</CODE> is <CODE>ios_base::beg</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the current position if <CODE>way</CODE> is <CODE>ios_base::cur</CODE>
<LI STYLE='list-style-type:disc;list-style-image:none'>the end of the sequence if <CODE>way</CODE> is <CODE>ios_base::end</CODE>
</UL>
The result is undefined if <CODE>way</CODE> is <CODE>ios_base::cur</CODE> and <CODE>which</CODE> is <CODE>(std::ios_base::in | std::ios_base::out)</CODE>. -->
</TD>
</TR>
</TABLE>
<H2>Exceptions</H2>
<P>
Errors which occur during the execution of <CODE>read</CODE>, <CODE>write</CODE>, <CODE>seek</CODE>, <CODE>input_sequence</CODE> or <CODE>output_sequence</CODE> are indicated by throwing exceptions. Reaching the end of the input sequence is not an error, but attempting to write past the end of the output sequence is.
</P>
<P>
After an exception is thrown, a Device must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour.
</P>
<H2>Models</H2>
<P>
See <A HREF='source.html'>Source</A>, <A HREF='sink.html'>Sink</A>, <A HREF='bidirectional_device.html'>BidirectionalDevice</A> and <A HREF='seekable_device.html'>SeekableDevice</A>.
</P>
<!-- Begin Footnotes -->
<HR>
<P>
<A CLASS='footnote_ref' NAME='note_1' HREF='#note_1_ref'><SUP>[1]</SUP></A>Familiarity with these <CODE>std::basic_streambuf</CODE> members is not required.
</P>
<P>
<A CLASS='footnote_ref' NAME='note_2' HREF='#note_2_ref'><SUP>[2]</SUP></A><A CLASS='bib_ref' HREF='../bibliography.html#iso'>[I<SPAN STYLE='font-size:80%'>SO</SPAN>]</A>, 24.3.1. <I>See</I> <A HREF='http://www.boost.org/more/generic_programming.html#tag_dispatching'>Tag Dispatching</A> for a discussion.
</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'>&copy; 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>
Reference in New Issue View Git Blame Copy Permalink