1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>SeekableFilter
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">SeekableFilter
</H1>
20 A SeekableFilter is a
<A HREF=
"filter.html">Filter
</A> whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"../guide/modes.html#seekable">seekable
</A>.
26 A SeekableFilter operates on the character sequence controlled by a
<A HREF=
"seekable_device.html">SeekableDevice
</A>, providing access to a filtered sequence having the same character type. It may expose the filtered sequence in two ways:
28 <LI STYLE=
"list-style-type:lower-roman">
29 by defining member function
<CODE>get
</CODE>,
<CODE>put
</CODE> and
<CODE>seek
</CODE>.
31 <LI STYLE=
"list-style-type:lower-roman">
32 by defining member functions
<CODE>read
</CODE>,
<CODE>write
</CODE> and
<CODE>seek
</CODE>.
35 The second alternative is provided for enhanced performance. SeekableFilters implementing this alternative are referred to as
<I>Multi-Character
</I>. (
<I>See
</I> <A HREF=
"multi_character.html">Multi-Character Filter
</A>.)
38 <H2>Refinement of
</H2>
40 <P><A HREF=
"input_filter.html">InputFilter
</A>,
<A HREF=
"output_filter.html">OutputFilter
</A>.
</P>
42 <H2>Associated Types
</H2>
44 <TABLE CELLPADDING=
"5" BORDER=
"1">
45 <TR><TD>Character type
</TD><TD>The type of the characters in the filtered sequences
</TD></TR>
49 A type convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>filter_tag
</CODE></A> and to
<A HREF=
"../guide/modes.html#seekable"><CODE>seekable
</CODE></A>
55 The unique
<I>most-derived
</I> <A HREF=
"../guide/modes.html#mode_tags">mode tag
</A> to which Category is convertible
62 <TABLE CELLPADDING=
"2">
63 <TR><TD><CODE>F
</CODE></TD><TD>- A type which is a model of SeekableFilter
</TD></TR>
64 <TR><TD><CODE>D
</CODE></TD><TD>- A type which is a model of
<A HREF=
"device.html">Device
</A>, with the same character type as
<CODE>F
</CODE> and with mode convertible to the mode of
<CODE>F
</CODE></TD></TR>
65 <TR><TD><CODE>Ch
</CODE></TD><TD>- The character type of
<CODE>F
</CODE></TD></TR>
66 <TR><TD><CODE>Tr
</CODE></A></TD><TD>-
<A HREF=
"../classes/char_traits.html"><CODE>boost::iostreams::char_traits
<Ch
></CODE></A></TD></TR>
67 <TR><TD><CODE>f
</CODE></TD><TD>- Object of type
<CODE>F
</CODE></TD></TR>
68 <TR><TD><CODE>d
</CODE></TD><TD>- Object of type
<CODE>D
</CODE></TD></TR>
69 <TR><TD><CODE>c
</CODE></TD><TD>- Object of type
<CODE>Ch
</CODE></TD></TR>
70 <TR><TD><CODE>s1
</CODE></TD><TD>- Object of type
<CODE>Ch*
</CODE></TD></TR>
71 <TR><TD><CODE>s2
</CODE></TD><TD>- Object of type
<CODE>const Ch*
</CODE></TD></TR>
72 <TR><TD><CODE>n
</CODE></TD><TD>- Object of type
<CODE>std::streamsize
</CODE></TD></TR>
73 <TR><TD><CODE>off
</CODE></TD><TD>- Object of type
<A HREF=
"../functions/positioning.html#synopsis"><CODE>stream_offset
</CODE></A></TD></TR>
74 <TR><TD><CODE>way
</CODE></TD><TD>- Object of type
<CODE>std::ios_base::seekdir
</CODE></TD></TR>
75 <TR><TD><CODE>which
</CODE></TD><TD>- Object of type
<CODE>std::ios_base::openmode
</CODE></TD></TR>
76 <TR><TD><CODE>io
</CODE></TD><TD>- Alias for namespace
<CODE>boost::iostreams
</CODE></TD></TR>
79 <H2>Valid Expressions / Semantics
</H2>
81 <TABLE CELLPADDING=
"5" BORDER=
"1">
82 <TR><TH>Expression
</TH><TH>Expression Type
</TH><TH>Category Precondition
</TH><TH>Semantics
</TH></TR>
85 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#char_type_of_ref">char_type_of
</A><F
>::type
</CODE></PRE>
87 <TD><CODE>typename
</CODE> of the character type
</TD>
88 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
92 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#category_ref">category_of
</A><F
>::type
</CODE></PRE>
94 <TD><CODE>typename
</CODE> of the category
</TD>
95 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
98 <TD><PRE CLASS=
"plain_code"><CODE>f.get(d)
</CODE></PRE></TD>
99 <TD><CODE>Tr::int_type
</CODE></TD>
101 Not convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>multi_char_tag
</CODE></A>
104 Returns the next character in the sequence controlled by
<CODE>f
</CODE>, or
<CODE>Tr::eof()
</CODE> if the end of the sequence has been reached. The sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/read.html"><CODE>io::read
</CODE></A> and
<A HREF=
"../functions/putback.html"><CODE>io::putback
</CODE></A>.
106 <!-- reads up to <CODE>n</CODE> characters from the sequence controlled by <CODE>dev</CODE> into <CODE>s</CODE>, returning the number of characters read; returning a value less than n indicates end-of-sequence -->
110 <TD><PRE CLASS=
"plain_code"><CODE>f.put(d, c)
</CODE></PRE></TD>
111 <TD><CODE>bool
</CODE></TD>
113 Writes the character
<CODE>c
</CODE> to the sequence controlled by
<CODE>f
</CODE>. The sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/write.html"><CODE>io::write
</CODE></A>.
117 <TD><PRE CLASS=
"plain_code"><CODE>f.read(d, s1, n)
</CODE></PRE></TD>
118 <TD><PRE CLASS=
"plain_code"><CODE>std::streamsize
</CODE></PRE></TD>
120 Convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>multi_char_tag
</CODE></A>
123 Reads up to
<CODE></CODE> characters from the sequence controlled by
<CODE>f
</CODE> into the buffer
<CODE>s1
</CODE>, returning the number of characters read. Returning a value less than
<CODE>n
</CODE> indicates end-of-sequence. The sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/read.html"><CODE>io::read
</CODE></A> and
<A HREF=
"../functions/putback.html"><CODE>io::putback
</CODE></A>.
127 <TD><PRE CLASS=
"plain_code"><CODE>f.write(d, s2, n)
</CODE></PRE></TD>
128 <TD><PRE CLASS=
"plain_code"><CODE>std::streamsize
</CODE></PRE></TD>
130 Writes n characters from the buffer
<CODE>s2
</CODE> to the sequence controlled by
<CODE>f
</CODE>. The sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/write.html"><CODE>io::write
</CODE></A>.
134 <TD><PRE CLASS=
"plain_code"><CODE>f.seek(d, off, way)
</CODE></PRE></TD>
135 <TD><CODE>std::streampos
</CODE></TD>
136 <TD ALIGN=
"center">-
</TD>
139 Advances the read/write head by
<CODE>off
</CODE> characters, returning the new position, where the offset is calculated from:
141 <UL STYLE=
"margin:0,0,0,auto">
142 <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>
143 <LI STYLE=
"list-style-type:disc;list-style-image:none">the current position if
<CODE>way
</CODE> is
<CODE>ios_base::cur
</CODE>
144 <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>
147 The sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/read.html"><CODE>io::seek
</CODE></A> and using
<A HREF=
"../functions/putback.html"><CODE>io::write
</CODE></A> if the
<A HREF=
"../guide/modes.html">mode
</A> of
<CODE>F
</CODE> is convertible to
<A HREF=
"../guide/modes.html#output"><CODE>output
</CODE></A>.
156 Errors which occur during the execution of
<CODE>get
</CODE>,
<CODE>put
</CODE>,
<CODE>read
</CODE>,
<CODE>write
</CODE> or
<CODE>seek
</CODE> are indicated by throwing exceptions. Reaching the end of the sequence is not an error, but attempting to write past the end of the sequence is.
160 After an exception is thrown, a SeekableFilter must be in a consistent state; further i/o operations may throw exceptions but must have well-defined behaviour. Furthermore, unless it is
<A HREF=
"closable.html">Closable
</A>, it must be ready to begin processing a new character sequence.
165 <!-- Begin Footer -->
169 <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>
170 <P CLASS=
"copyright">
171 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>)