1 <!DOCTYPE HTML PUBLIC
"-//W3C//DTD HTML 4.01 Transitional//EN">
4 <TITLE>I/O Traits and Categories
</TITLE>
5 <LINK REL=
"stylesheet" HREF=
"../../../../boost.css">
6 <LINK REL=
"stylesheet" HREF=
"../theme/iostreams.css">
12 <H1 CLASS=
"title">I/O Traits and Categories
</H1>
17 <DL class=
"page-index">
18 <DT><A href=
"#overview">Overview
</A></DT>
19 <DT><A href=
"#headers">Headers
</A></DT>
20 <DT><A href=
"#char_type_of_ref">Class template
<CODE>char_type_of
</CODE></A></DT>
21 <DT><A href=
"#int_type_of_ref">Class template
<CODE>int_type_of
</CODE></A></DT>
22 <DT><A href=
"#category_ref">Class template
<CODE>category_of
</CODE></A></DT>
23 <DT><A href=
"#category_tags">Category Tags
</A></DT>
29 <A NAME=
"overview"></A>
33 The header
<A CLASS=
"header" href=
"../../../../boost/iostreams/categories.hpp"><CODE><boost/iostreams/categories.hpp
></CODE></A> contains
<A href=
"#category_tags">category tags
</A> for classifying models of the various
<A href=
"concepts.html#filter_concepts">Filter
</A> and
<A href=
"concepts.html#device_concepts">Device
</A> concepts. The header
<A CLASS=
"header" href=
"../../../../boost/iostreams/traits.hpp"><CODE><boost/iostreams/traits.hpp
></CODE></A> contains the definitions of the metafunctions
<A HREF=
"#char_type_of_ref"><CODE>char_type_of
</CODE></A> and
<A HREF=
"#category_ref"><CODE>category
</CODE></A>, used to associate two fundamental types with each model of one the
<A href=
"concepts.html#filter_concepts">Filter
</A> or
<A href=
"concepts.html#device_concepts">Device
</A> concepts:
36 <A NAME=
"char_type"></A>
37 <H4>Character Type
</H4>
39 <P>The type of characters which a Filter or Device reads or writes.
</P>
41 <A NAME=
"category"></A>
45 A tag structure which the Iostreams library relies on to determine which operations a Filter or Device supports. It indicates, for a given type
<CODE>T
</CODE>:
48 <LI CLASS=
"square">whether
<CODE>T
</CODE> is a
<A href=
"concepts.html#filter_concepts">Filter
</A> or a
<A href=
"concepts.html#device_concepts">Device
</A>
49 <LI CLASS=
"square">the
<A href=
"modes.html">mode
</A> of
<CODE>T
</CODE>
50 <LI CLASS=
"square">any
<A href=
"concepts.html#optional_behavior">optional_behavior
</A> <CODE>T
</CODE> implements
53 Its function is similar to the
<CODE>iterator_category
</CODE> member of
<CODE>std::iterator_traits
</CODE>.
<A CLASS=
"footnote_ref" NAME=
"note_1_ref" HREF=
"#note_1"><SUP>[
1]
</SUP></A> Types which serve as categories are called
<A HREF=
"#category_tags">category tags
</A>.
56 <A NAME=
"headers"></A>
59 <DL class=
"page-index">
60 <DT><A CLASS=
"header" href=
"../../../../boost/iostreams/categories.hpp"><CODE><boost/iostreams/categories.hpp
></CODE></A></DT>
61 <DT><A CLASS=
"header" href=
"../../../../boost/iostreams/traits.hpp"><CODE><boost/iostreams/traits.hpp
></CODE></A></DT>
64 <A NAME=
"char_type_of_ref"></A>
65 <H2>Class Template
<CODE>char_type_of
</CODE></H2>
69 <P><A HREF=
"http://www.boost.org/libs/mpl/doc/refmanual/metafunction.html" TARGET=
"_top">Metafunction
</A> associating a
<A HREF=
"#char_type">character type
</A> to each
<A href=
"concepts.html#filter_concepts">Filter
</A> or
<A href=
"concepts.html#device_concepts">Device
</A> type. Although
<CODE>char_type_of
</CODE> is designed to be specialized for new Filter and Device types, the default implementation should be suitable for most purposes.
73 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
75 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> <A HREF=
"#char_type_template_params" CLASS=
"documented">T
</A>>
76 <SPAN CLASS=
"keyword">struct
</SPAN> <A CLASS=
"documented" HREF=
"#char_type_template_params">char_type_of
</A> {
77 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">see below
</SPAN> <A HREF=
"#char_type_of_type" CLASS=
"documented">type
</A>;
80 } }
<SPAN CLASS=
"comment">// End namespace boost::io
</SPAN></PRE>
82 <A NAME=
"char_type_template_params"></A>
83 <H4>Template parameters
</H4>
85 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
87 <TD VALIGN=
"top"><I>T
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
88 <TD>A model of one of the
<A href=
"concepts.html#filter_concepts">Filter
</A> or
<A href=
"concepts.html#device_concepts">Device
</A> concepts
</TD>
92 <A NAME=
"char_type_of_type"></A>
93 <H4><CODE>io_traits::type
</CODE></H4>
95 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">see below
</SPAN> char_type;
</PRE>
97 <P>The value of the nested type
<CODE>type
</CODE> depends on the template parameter
<CODE>T
</CODE> as follows:
</P>
99 <TABLE STYLE=
"margin-left:2em" BORDER=
1 CELLPADDING=
4>
100 <TR><TH><CODE>T
</CODE></TH><TH><CODE>char_type
</CODE></TH></TR>
102 <TD VALIGN=
"top">Sepcialization of
<CODE>std::back_insert_iterator
</CODE></TD>
103 <TD>The
<CODE>value_type
</CODE> of the iterator's
<CODE>container_type
</CODE></TD>
106 <TD VALIGN=
"top">All other types
</TD>
107 <TD><CODE>T::char_type
</CODE></TD>
111 <A NAME=
"int_type_of_ref"></A>
112 <H2>Class Template
<CODE>int_type_of
</CODE></H2>
116 <P><A HREF=
"http://www.boost.org/libs/mpl/doc/refmanual/metafunction.html" TARGET=
"_top">Metafunction
</A> associating an integral type to each
<A href=
"concepts.html#filter_concepts">Filter
</A> or
<A href=
"concepts.html#device_concepts">Device
</A> type. Although
<CODE>int_type_of
</CODE> is designed to be specialized for new Filter and Device types, the default implementation should be suitable for most purposes.
120 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
122 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> <A HREF=
"#int_type_template_params" CLASS=
"documented">T
</A>>
123 <SPAN CLASS=
"keyword">struct
</SPAN> <A CLASS=
"documented" HREF=
"#int_type_template_params">int_type_of
</A> {
124 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">see below
</SPAN> <A HREF=
"#int_type_of_type" CLASS=
"documented">type
</A>;
127 } }
<SPAN CLASS=
"comment">// End namespace boost::io
</SPAN></PRE>
129 <A NAME=
"int_type_template_params"></A>
130 <H4>Template parameters
</H4>
132 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
134 <TD VALIGN=
"top"><I>T
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
135 <TD>A model of one of the
<A href=
"concepts.html#filter_concepts">Filter
</A> or
<A href=
"concepts.html#device_concepts">Device
</A> concepts
</TD>
139 <A NAME=
"int_type_of_type"></A>
140 <H4><CODE>io_traits::type
</CODE></H4>
142 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">see below
</SPAN> char_type;
</PRE>
144 <P>Equal to
<CODE>std::char_traits
<char_type
>::int_type
</CODE>, where
<CODE>char_type
</CODE> is
<A HREF=
"#char_type_of_ref"><CODE>char_type_of
<T
>::type
</CODE></A>.
146 <A NAME=
"category_ref"></A>
147 <H2>Class Template
<CODE>category_of
</CODE></H2>
151 <P><A HREF=
"http://www.boost.org/libs/mpl/doc/refmanual/metafunction.html" TARGET=
"_top">Metafunction
</A> associating a
<A HREF=
"#category_tags">category tag
</A> to each
<A href=
"concepts.html#filter_concepts">Filter
</A> or
<A href=
"concepts.html#device_concepts">Device
</A> type. Although
<CODE>category
</CODE> is designed to be specialized for new Filter and Device types, the default implementation should be suitable for most purposes.
155 <PRE CLASS=
"broken_ie"><SPAN CLASS=
"keyword">namespace
</SPAN> boost {
<SPAN CLASS=
"keyword">namespace
</SPAN> iostreams {
157 <SPAN CLASS=
"keyword">template
</SPAN><<SPAN CLASS=
"keyword">typename
</SPAN> <A HREF=
"#category_template_params" CLASS=
"documented">T
</A>>
158 <SPAN CLASS=
"keyword">struct
</SPAN> <A CLASS=
"documented" HREF=
"#category_template_params">category_of
</A> {
159 <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">see below
</SPAN> <A HREF=
"#category_type" CLASS=
"documented">type
</A>;
162 } }
<SPAN CLASS=
"comment">// End namespace boost::io
</SPAN></PRE>
164 <A NAME=
"category_template_params"></A>
165 <H4>Template parameters
</H4>
167 <TABLE STYLE=
"margin-left:2em" BORDER=
0 CELLPADDING=
2>
169 <TD VALIGN=
"top"><I>T
</I></TD><TD WIDTH=
"2em" VALIGN=
"top">-
</TD>
170 <TD>A model of one of the
<A href=
"concepts.html#filter_concepts">Filter
</A> or
<A href=
"concepts.html#device_concepts">Device
</A> concepts
</TD>
174 <A NAME=
"category_type"></A>
175 <H4><CODE>category::type
</CODE></H4>
177 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">typedef
</SPAN> <SPAN CLASS=
"omitted">see below
</SPAN> type;
</PRE>
179 <P>The value of the nested type
<CODE>type
</CODE> depends on the template parameter
<CODE>T
</CODE> as follows:
</P>
181 <TABLE STYLE=
"margin-left:2em" BORDER=
1 CELLPADDING=
4>
182 <TR><TH><CODE>T
</CODE></TH><TH><CODE>category
</CODE></TH></TR>
184 <TD VALIGN=
"top">Specialization of
<CODE>std::basic_iostream
</CODE>, or derived from such a specialization
</TD>
185 <TD><CODE>iostream_tag
</CODE></TD>
188 <TD VALIGN=
"top">Specialization of
<CODE>std::basic_istream
</CODE>, or derived from such a specialization
</TD>
189 <TD><CODE>istream_tag
</CODE></TD>
192 <TD VALIGN=
"top">Specialization of
<CODE>std::basic_ostream
</CODE>, or derived from such a specialization
</TD>
193 <TD><CODE>ostream_tag
</CODE></TD>
196 <TD VALIGN=
"top">Specialization of
<CODE>std::basic_streambuf
</CODE>, or derived from such a specialization
</TD>
197 <TD><CODE>streambuf_tag
</CODE></TD>
200 <TD VALIGN=
"top">Specialization of
<CODE>std::back_insert_iterator
</CODE>, or derived from such a specialization
</TD>
201 <TD><CODE>insert_iterator_tag
</CODE></TD>
204 <TD VALIGN=
"top">All other types
</TD>
205 <TD><CODE>T::category
</CODE></TD>
209 <P>For more information, see
<A CLASS=
"header" href=
"../../../../boost/iostreams/traits.hpp"><CODE><boost/iostreams/traits.hpp
></CODE></A>.
</P>
211 <A NAME=
"category_tags"></A>
212 <H2>Category Tags
</H2>
215 In addition to the various
<A href=
"modes.html#mode_tags">mode tags
</A>, the header
<A CLASS=
"header" href=
"../../../../boost/iostreams/categories.hpp"><CODE><boost/iostreams/categories.hpp
></CODE></A> provides the category tags shown in the following table. To produce a new category tag which combines several existing tags, simply define a
<CODE>struct
</CODE> extending the existing tags.
<I>E.g.
</I>,
216 <PRE CLASS=
"broken_ie"> <SPAN CLASS=
"keyword">struct
</SPAN> category
221 This defines a category tag representing
<A href=
"modes.html#seekable">Seekable
</A>,
<A href=
"../concepts/localizable.html">Localizable
</A> <A href=
"../concepts/filter.html">Filters
</A>.
225 <TABLE STYLE=
"margin-left:2em;margin-bottom:2em" BORDER=
"1" CELLPADDING=
"6">
226 <TR><TH>Tag
</TH><TH>Description
</TH></TR>
228 <TD VALIGN=
"top"><CODE>filter_tag
</CODE></TD>
229 <TD>Indicates that a type models
<A href=
"../concepts/filter.html">Filter
</A></TD>
232 <TD VALIGN=
"top"><CODE>device_tag
</CODE></TD>
233 <TD>Indicates that a type models
<A href=
"../concepts/device.html">Device
</A></TD>
237 <CODE>closable_tag
</CODE><BR><CODE>localizable_tag
</CODE><BR>
238 <CODE>direct_tag
</CODE><BR><CODE>peekable_tag
</CODE><BR>
239 <CODE>multichar_tag
</CODE>
242 Used to indicate
<A href=
"concepts.html#optional_behavior">optional behavior
</A> implemented by a Filter or Device type
247 <CODE>source_tag
</CODE><BR>
248 <CODE>sink_tag
</CODE><BR>
249 <CODE>bidirectional_device_tag
</CODE><BR>
250 <CODE>seekable_device_tag
</CODE><BR>
251 <CODE>input_filter_tag
</CODE><BR>
252 <CODE>output_filter_tag
</CODE><BR>
253 <CODE>bidirectional_filter_tag
</CODE><BR>
254 <CODE>seekable_filter_tag
</CODE><BR>
255 <CODE>multichar_input_filter_tag
</CODE><BR>
256 <CODE>multichar_output_filter_tag
</CODE><BR>
257 <CODE>multichar_bidirectional_filter_tag
</CODE><BR>
258 <CODE>multichar_seekable_filter_tag
</CODE>
261 Convenience tags for defining models of the various
<A href=
"../concepts/filter.html">Filter
</A> and
<A href=
"../concepts/device.html">Device
</A> refinements
266 <CODE>istream_tag
</CODE><BR>
267 <CODE>ostream_tag
</CODE><BR>
268 <CODE>iostream_tag
</CODE><BR>
269 <CODE>streambuf_tag
</CODE>
272 Used internally to distinguish standard stream and stream buffer types
276 <TD VALIGN=
"top"><CODE>insert_iterator_tag
</CODE></TD>
277 <TD>Used internally to distinguish specialization of
<CODE>std::back_insert_iterator
</CODE></TD>
281 <!-- Begin Footnotes -->
286 <A CLASS=
"footnote_ref" NAME=
"note_1" HREF=
"#note_1_ref"><SUP>[
1]
</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" TARGET=
"_top">Tag Dispatching
</A> for a discussion.
289 <!-- End Footnotes -->
291 <!-- Begin Footer -->
295 <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>
296 <P CLASS=
"copyright">
297 Use modification and distribution are subject to the Boost Software License Version
1.0. (See accompanying file
<A href=
"../../../../LICENSE_1_0.txt">LICENSE_1_0.txt
</A> or copy at
<A href=
"http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt
</A>)