1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>InputFilter
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">InputFilter
</H1>
17 <DL CLASS=
"page-index" STYLE=
"margin-top:0">
18 <DT><A HREF=
"#definition">Definition
</A>
19 <DT><A HREF=
"#description">Description
</A>
20 <DT><A HREF=
"#examples">Examples
</A>
21 <DT><A HREF=
"#detailed_specification">Detailed Specification
</A>
24 <A NAME=
"definition"></A>
28 An InputFilter is a
<A HREF=
"filter.html">Filter
</A> whose
<A HREF=
"../guide/modes.html">mode
</A> refines
<A HREF=
"../guide/modes.html#input">input
</A>.
31 <A NAME=
"description"></A>
35 An InputFilter operates on the character sequence controlled by a
<A HREF=
"source.html">Source
</A>, providing access to a filtered sequence having the same character type. It may expose the filtered sequence in two ways:
37 <LI STYLE=
"list-style-type:lower-roman">
38 by defining a member function
<CODE>get
</CODE>
40 <LI STYLE=
"list-style-type:lower-roman">
41 by defining a member function
<CODE>read
</CODE>
43 The second alternative is provided for enhanced performance. InputFilters implementing this alternative are referred to as
<I>Multi-Character
</I>. (
<I>See
</I> <A HREF=
"multi_character.html">Multi-Character Filter
</A>.)
46 <A NAME=
"examples"></A>
49 <H4>I. Ordinary InputFilter
</H4>
52 The following example shows an InputFilter which removes all non-alphabetic characters from a sequence.
55 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><ctype.h
></SPAN> <SPAN CLASS=
"comment">// isalpha
</SPAN>
56 <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><cstdio.h
></SPAN> <SPAN CLASS=
"comment">// EOF
</SPAN>
57 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/categories.hpp"><SPAN CLASS=
"literal"><boost/iostreams/categories.hpp
></SPAN></A> <SPAN CLASS=
"comment">// input_filter_tag
</SPAN>
58 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/operations.hpp"><SPAN CLASS=
"literal"><boost/iostreams/operations.hpp
></SPAN></A> <SPAN CLASS=
"comment">// get, WOULD_BLOCK
</SPAN>
60 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> std;
61 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> boost::iostreams;
63 <SPAN CLASS=
"keyword">struct
</SPAN> alphabetic_input_filter {
64 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN> char_type;
65 <SPAN CLASS=
"keyword">typedef
</SPAN> input_filter_tag category;
67 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> Source
>
68 <SPAN CLASS=
"keyword">int
</SPAN> get(Source
& src)
70 <SPAN CLASS=
"keyword">int
</SPAN> c;
71 <SPAN CLASS=
"keyword">while
</SPAN> ( (c = boost::iostreams::get(src)) != EOF
&&
72 c != WOULD_BLOCK
&&
73 !isalpha((
<SPAN CLASS=
"keyword">unsigned
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>) c) )
75 <SPAN CLASS=
"keyword">return
</SPAN> c;
80 Here
<CODE>char_type
</CODE> is the
<A HREF=
"../guide/traits.html#char_type">character type
</A> of the Filter,
<CODE>input_filter_tag
</CODE> is a
<A HREF=
"../guide/traits.html#category_tags">category tag
</A> identifying the Filter as a model of InputFilter, and the function
<A HREF=
"../functions/get.html"><CODE>boost::iostreams::get
</CODE></A> reads a character from an arbitrary Source.
<A CLASS=
"footnote_ref" NAME=
"note_1_ref" HREF=
"#note_1"><SUP>[
1]
</SUP></A> The constant
<A HREF=
"../classes/char_traits.html#WOULD_BLOCK"><CODE>WOULD_BLOCK
</CODE></A>, defined in the header
<A HREF=
"../../../../boost/iostreams/char_traits.hpp"><CODE><boost/iostreams/char_traits.hpp
></CODE></A>, is used to indicate that input is temporarily unavilable.
84 The Iostreams library defines two convenience classes,
<A HREF=
"../classes/filter.html#synopsis"><CODE>input_filter
</CODE></A> and
<A HREF=
"../classes/filter.html#synopsis"><CODE>input_wfilter
</CODE></A>, which provide member
<CODE>typedef
</CODE>s
<CODE>char_type
</CODE> and
<CODE>category
</CODE> as well as default implementations of several member functions. When defining a new model of InputFilter, it is often sufficient to derive from
<CODE>input_filter
</CODE> or
<CODE>input_wfilter
</CODE> and to define a member function
<CODE>get
</CODE>.
87 <H4>II. Multi-Character InputFilter
</H4>
90 The following example shows a Multi-Character InputFilter which performs the same filtering operation as the Filter in Example I.
93 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><ctype.h
></SPAN> <SPAN CLASS=
"comment">// isalpha
</SPAN>
94 <SPAN CLASS=
"preprocessor">#include
</SPAN> <SPAN CLASS=
"literal"><cstdio.h
></SPAN> <SPAN CLASS=
"comment">// EOF
</SPAN>
95 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/categories.hpp"><SPAN CLASS=
"literal"><boost/iostreams/categories.hpp
></SPAN></A> <SPAN CLASS=
"comment">// input_filter_tag
</SPAN>
96 <SPAN CLASS=
"preprocessor">#include
</SPAN> <A CLASS=
"header" HREF=
"../../../../boost/iostreams/concepts.hpp"><SPAN CLASS=
"literal"><boost/iostreams/operations.hpp
></SPAN></A> <SPAN CLASS=
"comment">// get
</SPAN>
98 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> std;
99 <SPAN CLASS=
"keyword">using
</SPAN> <SPAN CLASS=
"keyword">namespace
</SPAN> boost::io;
101 <SPAN CLASS=
"keyword">struct
</SPAN> alphabetic_input_filter {
102 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN> char_type;
103 <SPAN CLASS=
"keyword">typedef
</SPAN> multichar_input_filter_tag category;
105 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> Source
>
106 streamsize read(Source
& src,
<SPAN CLASS=
"keyword">char
</SPAN>* s, streamsize n)
108 <SPAN CLASS=
"keyword">int
</SPAN> c;
109 <SPAN CLASS=
"keyword">char
</SPAN>* first = s;
110 <SPAN CLASS=
"keyword">char
</SPAN>* last = s + n;
111 <SPAN CLASS=
"keyword">while
</SPAN> ( first != last
&&
112 (c = boost::iostreams::get(src)) != EOF
&&
113 c != WOULD_BLOCK
&&
114 isalpha((
<SPAN CLASS=
"keyword">unsigned
</SPAN> <SPAN CLASS=
"keyword">char
</SPAN>) c) )
118 streamsize result =
<SPAN CLASS=
"keyword">static_cast
</SPAN><streamsize
>(first - s);
119 <SPAN CLASS=
"keyword">return
</SPAN> result ==
<SPAN CLASS='numeric_literal'
>0</SPAN> && c != WOULD_BLOCK ?
120 <SPAN CLASS='numeric_literal'
>-
1</SPAN> :
126 Here
<CODE>multichar_input_filter_tag
</CODE> is a
<A HREF=
"../guide/traits.html#category">category tag
</A> identifying the Filter as a Multi-Character InputFilter.
129 The Iostreams library defines two convenience classes,
<A HREF=
"../classes/filter.html#synopsis"><CODE>multichar_input_filter
</CODE></A> and
<A HREF=
"../classes/filter.html#synopsis"><CODE>multichar_input_wfilter
</CODE></A>, which provide the member
<CODE>typedef
</CODE>s
<CODE>char_type
</CODE> and
<CODE>category
</CODE> as well as default implementations of several member functions. When defining a new Multi-Character InputFilter, it is often sufficient to derive from
<CODE>multichar_input_filter
</CODE> or
<CODE>multichar_input_wfilter
</CODE> and to define a member function
<CODE>read
</CODE>.
132 <A NAME=
"detailed_specification"></A>
133 <H2>Refinement of
</H2>
135 <P><A HREF=
"filter.html">Filter
</A>.
</P>
137 <H2>Associated Types
</H2>
139 <TABLE CELLPADDING=
"5" BORDER=
"1">
140 <TR><TD>Character type
</TD><TD>The type of the characters in the filtered sequences
</TD></TR>
144 A type convertible to
<A HREF=
"../guide/traits.html#category_tags"><CODE>filter_tag
</CODE></A> and to
<A HREF=
"../guide/modes.html#input"><CODE>input
</CODE></A>
150 The unique
<I>most-derived
</I> <A HREF=
"../guide/modes.html#mode_tags">mode tag
</A> to which Category is convertible
157 <TABLE CELLPADDING=
"2">
158 <TR><TD><CODE>F
</CODE></TD><TD>- A type which is a model of InputFilter
</TD></TR>
159 <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 refining the mode of
<CODE>F
</CODE></TD></TR>
160 <TR><TD><CODE>Ch
</CODE></TD><TD>- The character type of
<CODE>F
</CODE></TD></TR>
161 <TR><TD><CODE>Tr
</CODE></A></TD><TD>-
<A HREF=
"../classes/char_traits.html"><CODE>boost::iostreams::char_traits
<Ch
></CODE></A></TD></TR>
162 <TR><TD><CODE>f
</CODE></TD><TD>- Object of type
<CODE>F
</CODE></TD></TR>
163 <TR><TD><CODE>d
</CODE></TD><TD>- Object of type
<CODE>D
</CODE></TD></TR>
164 <TR><TD><CODE>s
</CODE></TD><TD>- Object of type
<CODE>Ch*
</CODE></TD></TR>
165 <TR><TD><CODE>n
</CODE></TD><TD>- Object of type
<CODE>std::streamsize
</CODE></TD></TR>
166 <TR><TD><CODE>io
</CODE></TD><TD>- Alias for namespace
<CODE>boost::iostreams
</CODE></TD></TR>
169 <A NAME=
"semantics"></A>
170 <H2>Valid Expressions / Semantics
</H2>
172 <TABLE CELLPADDING=
"5" BORDER=
"1">
173 <TR><TH>Expression
</TH><TH>Expression Type
</TH><TH>Category Precondition
</TH><TH>Semantics
</TH></TR>
176 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#char_type_of_ref">char_type_of
</A><F
>::type
</CODE></PRE>
178 <TD><CODE>typename
</CODE> of the character type
</TD>
179 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
183 <PRE CLASS=
"plain_code"><CODE>typename
<A HREF=
"../guide/traits.html#category_ref">category_of
</A><F
>::type
</CODE></PRE>
185 <TD><CODE>typename
</CODE> of the category
</TD>
186 <TD ALIGN=
"center">-
</TD><TD ALIGN=
"center">-
</TD>
189 <TD><PRE CLASS=
"plain_code"><CODE>f.get(d)
</CODE></PRE></TD>
190 <TD><CODE>Tr::int_type
</CODE></TD>
192 Convertible to
<A HREF=
"../guide/modes.html#mode_tags"><CODE>input
</CODE></A> but not to
<A HREF=
"../guide/traits.html#category_tags"><CODE>multichar_tag
</CODE></A>
195 Returns the next character in the input sequence controlled by
<CODE>f
</CODE>,
<CODE>Tr::eof()
</CODE> if the end of the sequence has been reached or
<CODE>Tr::would_block()
</CODE> if input is temporarily unavilable because a call to
<CODE>d
</CODE> has produced fewer characters than requested. The input sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/get.html"><CODE>io::get
</CODE></A>,
<A HREF=
"../functions/read.html"><CODE>io::read
</CODE></A> and
<A HREF=
"../functions/putback.html"><CODE>io::putback
</CODE></A>.
199 <TD><PRE CLASS=
"plain_code"><CODE>f.read(d, s, n)
</CODE></PRE></TD>
200 <TD><PRE CLASS=
"plain_code"><CODE>std::streamsize
</CODE></PRE></TD>
202 Convertible to
<A HREF=
"../guide/modes.html#mode_tags"><CODE>input
</CODE></A> and to
<A HREF=
"../guide/traits.html#category_tags"><CODE>multichar_tag
</CODE></A>
205 Reads up to
<CODE>n
</CODE> characters from the input sequence controlled by
<CODE>f
</CODE> into the buffer
<CODE>s
</CODE>, returning the number of characters read or
<CODE>-
1</CODE> to indicate end-of-sequence. A value less than
<CODE>n
</CODE> may be returned only at end-of-sequence or if input is temporarily unavilable because a call to
<CODE>d
</CODE> has produced fewer characters than requested. The input sequence controlled by
<CODE>d
</CODE> may be accessed using
<A HREF=
"../functions/get.html"><CODE>io::get
</CODE></A>,
<A HREF=
"../functions/read.html"><CODE>io::read
</CODE></A> and
<A HREF=
"../functions/putback.html"><CODE>io::putback
</CODE></A>.
213 Errors which occur during the execution of
<CODE>get
</CODE> and
<CODE>read
</CODE> are indicated by throwing exceptions. Reaching the end of the sequence is not an error.
217 After an exception is thrown, an InputFilter 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.
223 <LI>The
<A HREF=
"../guide/text_processing.html">Text Processing Filters
</A>.
224 <LI>The compression and decompression filters.
227 <H2>Acknowledgments
</H2>
230 The concept InputFilter was inspired by the
<I>extractors
</I> of
<A CLASS=
"footnote_ref" HREF=
"../bibliography.html#kanze">[Kanze]
</A>.
233 <!-- Begin Footnotes -->
238 <A CLASS=
"footnote_ref" NAME=
"note_1" HREF=
"#note_1_ref"><SUP>[
1]
</SUP></A>Technically,
<CODE>boost::iostreams::get
</CODE> requires that a Source be
<A HREF=
"../concepts/direct.html"><I>indirect
</I></A>.
241 <!-- End Footnotes -->
243 <!-- Begin Footer -->
247 <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>
248 <P CLASS=
"copyright">
249 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>)