1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
---|
2 | <HTML> |
---|
3 | <HEAD> |
---|
4 | <TITLE>I/O Traits and Categories</TITLE> |
---|
5 | <LINK REL="stylesheet" HREF="../../../../boost.css"> |
---|
6 | <LINK REL="stylesheet" HREF="../theme/iostreams.css"> |
---|
7 | </HEAD> |
---|
8 | <BODY> |
---|
9 | |
---|
10 | <!-- Begin Banner --> |
---|
11 | |
---|
12 | <H1 CLASS="title">I/O Traits and Categories</H1> |
---|
13 | <HR CLASS="banner"> |
---|
14 | |
---|
15 | <!-- End Banner --> |
---|
16 | |
---|
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> |
---|
24 | </DT> |
---|
25 | </DL> |
---|
26 | |
---|
27 | <HR> |
---|
28 | |
---|
29 | <A NAME="overview"></A> |
---|
30 | <H2>Overview</H2> |
---|
31 | |
---|
32 | <P> |
---|
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: |
---|
34 | </P> |
---|
35 | |
---|
36 | <A NAME="char_type"></A> |
---|
37 | <H4>Character Type</H4> |
---|
38 | |
---|
39 | <P>The type of characters which a Filter or Device reads or writes.</P> |
---|
40 | |
---|
41 | <A NAME="category"></A> |
---|
42 | <H4>Category</H4> |
---|
43 | |
---|
44 | <P> |
---|
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>: |
---|
46 | </P> |
---|
47 | <UL> |
---|
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 |
---|
51 | </UL> |
---|
52 | <P> |
---|
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>. |
---|
54 | </P> |
---|
55 | |
---|
56 | <A NAME="headers"></A> |
---|
57 | <H2>Headers</H2> |
---|
58 | |
---|
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> |
---|
62 | </DL> |
---|
63 | |
---|
64 | <A NAME="char_type_of_ref"></A> |
---|
65 | <H2>Class Template <CODE>char_type_of</CODE></H2> |
---|
66 | |
---|
67 | <H4>Description</H4> |
---|
68 | |
---|
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. |
---|
70 | |
---|
71 | <H4>Synopsis</H4> |
---|
72 | |
---|
73 | <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { |
---|
74 | |
---|
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>; |
---|
78 | }; |
---|
79 | |
---|
80 | } } <SPAN CLASS="comment">// End namespace boost::io</SPAN></PRE> |
---|
81 | |
---|
82 | <A NAME="char_type_template_params"></A> |
---|
83 | <H4>Template parameters</H4> |
---|
84 | |
---|
85 | <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> |
---|
86 | <TR> |
---|
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> |
---|
89 | </TR> |
---|
90 | </TABLE> |
---|
91 | |
---|
92 | <A NAME="char_type_of_type"></A> |
---|
93 | <H4><CODE>io_traits::type</CODE></H4> |
---|
94 | |
---|
95 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="omitted">see below</SPAN> char_type;</PRE> |
---|
96 | |
---|
97 | <P>The value of the nested type <CODE>type</CODE> depends on the template parameter <CODE>T</CODE> as follows:</P> |
---|
98 | |
---|
99 | <TABLE STYLE="margin-left:2em" BORDER=1 CELLPADDING=4> |
---|
100 | <TR><TH><CODE>T</CODE></TH><TH><CODE>char_type</CODE></TH></TR> |
---|
101 | <TR> |
---|
102 | <TD VALIGN="top"><A NAME="print_CR"></A>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> |
---|
104 | </TR> |
---|
105 | <TR> |
---|
106 | <TD VALIGN="top"><A NAME="print_CR"></A>All other types</TD> |
---|
107 | <TD><CODE>T::char_type</CODE></TD> |
---|
108 | </TR> |
---|
109 | </TABLE> |
---|
110 | |
---|
111 | <A NAME="int_type_of_ref"></A> |
---|
112 | <H2>Class Template <CODE>int_type_of</CODE></H2> |
---|
113 | |
---|
114 | <H4>Description</H4> |
---|
115 | |
---|
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. |
---|
117 | |
---|
118 | <H4>Synopsis</H4> |
---|
119 | |
---|
120 | <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { |
---|
121 | |
---|
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>; |
---|
125 | }; |
---|
126 | |
---|
127 | } } <SPAN CLASS="comment">// End namespace boost::io</SPAN></PRE> |
---|
128 | |
---|
129 | <A NAME="int_type_template_params"></A> |
---|
130 | <H4>Template parameters</H4> |
---|
131 | |
---|
132 | <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> |
---|
133 | <TR> |
---|
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> |
---|
136 | </TR> |
---|
137 | </TABLE> |
---|
138 | |
---|
139 | <A NAME="int_type_of_type"></A> |
---|
140 | <H4><CODE>io_traits::type</CODE></H4> |
---|
141 | |
---|
142 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="omitted">see below</SPAN> char_type;</PRE> |
---|
143 | |
---|
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>. |
---|
145 | |
---|
146 | <A NAME="category_ref"></A> |
---|
147 | <H2>Class Template <CODE>category_of</CODE></H2> |
---|
148 | |
---|
149 | <H4>Description</H4> |
---|
150 | |
---|
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. |
---|
152 | |
---|
153 | <H4>Synopsis</H4> |
---|
154 | |
---|
155 | <PRE CLASS="broken_ie"><SPAN CLASS="keyword">namespace</SPAN> boost { <SPAN CLASS="keyword">namespace</SPAN> iostreams { |
---|
156 | |
---|
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>; |
---|
160 | }; |
---|
161 | |
---|
162 | } } <SPAN CLASS="comment">// End namespace boost::io</SPAN></PRE> |
---|
163 | |
---|
164 | <A NAME="category_template_params"></A> |
---|
165 | <H4>Template parameters</H4> |
---|
166 | |
---|
167 | <TABLE STYLE="margin-left:2em" BORDER=0 CELLPADDING=2> |
---|
168 | <TR> |
---|
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> |
---|
171 | </TR> |
---|
172 | </TABLE> |
---|
173 | |
---|
174 | <A NAME="category_type"></A> |
---|
175 | <H4><CODE>category::type</CODE></H4> |
---|
176 | |
---|
177 | <PRE CLASS="broken_ie"> <SPAN CLASS="keyword">typedef</SPAN> <SPAN CLASS="omitted">see below</SPAN> type;</PRE> |
---|
178 | |
---|
179 | <P>The value of the nested type <CODE>type</CODE> depends on the template parameter <CODE>T</CODE> as follows:</P> |
---|
180 | |
---|
181 | <TABLE STYLE="margin-left:2em" BORDER=1 CELLPADDING=4> |
---|
182 | <TR><TH><CODE>T</CODE></TH><TH><CODE>category</CODE></TH></TR> |
---|
183 | <TR> |
---|
184 | <TD VALIGN="top"><A NAME="print_CR"></A>Specialization of <CODE>std::basic_iostream</CODE>, or derived from such a specialization</TD> |
---|
185 | <TD><CODE>iostream_tag</CODE></TD> |
---|
186 | </TR> |
---|
187 | <TR> |
---|
188 | <TD VALIGN="top"><A NAME="print_CR"></A>Specialization of <CODE>std::basic_istream</CODE>, or derived from such a specialization</TD> |
---|
189 | <TD><CODE>istream_tag</CODE></TD> |
---|
190 | </TR> |
---|
191 | <TR> |
---|
192 | <TD VALIGN="top"><A NAME="print_CR"></A>Specialization of <CODE>std::basic_ostream</CODE>, or derived from such a specialization</TD> |
---|
193 | <TD><CODE>ostream_tag</CODE></TD> |
---|
194 | </TR> |
---|
195 | <TR> |
---|
196 | <TD VALIGN="top"><A NAME="print_CR"></A>Specialization of <CODE>std::basic_streambuf</CODE>, or derived from such a specialization</TD> |
---|
197 | <TD><CODE>streambuf_tag</CODE></TD> |
---|
198 | </TR> |
---|
199 | <TR> |
---|
200 | <TD VALIGN="top"><A NAME="print_CR"></A>Specialization of <CODE>std::back_insert_iterator</CODE>, or derived from such a specialization</TD> |
---|
201 | <TD><CODE>insert_iterator_tag</CODE></TD> |
---|
202 | </TR> |
---|
203 | <TR> |
---|
204 | <TD VALIGN="top"><A NAME="print_CR"></A>All other types</TD> |
---|
205 | <TD><CODE>T::category</CODE></TD> |
---|
206 | </TR> |
---|
207 | </TABLE> |
---|
208 | |
---|
209 | <P>For more information, see <A CLASS="header" href="../../../../boost/iostreams/traits.hpp"><CODE><boost/iostreams/traits.hpp></CODE></A>.</P> |
---|
210 | |
---|
211 | <A NAME="category_tags"></A> |
---|
212 | <H2>Category Tags</H2> |
---|
213 | |
---|
214 | <P> |
---|
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 |
---|
217 | : seekable, |
---|
218 | filter_tag, |
---|
219 | localizable_tag |
---|
220 | { };</PRE> |
---|
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>. |
---|
222 | </P> |
---|
223 | |
---|
224 | |
---|
225 | <TABLE STYLE="margin-left:2em;margin-bottom:2em" BORDER="1" CELLPADDING="6"> |
---|
226 | <TR><TH>Tag</TH><TH>Description</TH></TR> |
---|
227 | <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> |
---|
230 | </TR> |
---|
231 | <TR> |
---|
232 | <TD VALIGN="top"><CODE>device_tag</CODE></TD> |
---|
233 | <TD>Indicates that a type models <A href="../concepts/device.html">Device</A></TD> |
---|
234 | </TR> |
---|
235 | <TR> |
---|
236 | <TD VALIGN="top"> |
---|
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> |
---|
240 | </TD> |
---|
241 | <TD> |
---|
242 | Used to indicate <A href="concepts.html#optional_behavior">optional behavior</A> implemented by a Filter or Device type |
---|
243 | </TD> |
---|
244 | </TR> |
---|
245 | <TR> |
---|
246 | <TD VALIGN="top"> |
---|
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> |
---|
259 | </TD> |
---|
260 | <TD> |
---|
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 |
---|
262 | </TD> |
---|
263 | </TR> |
---|
264 | <TR> |
---|
265 | <TD VALIGN="top"> |
---|
266 | <CODE>istream_tag</CODE><BR> |
---|
267 | <CODE>ostream_tag</CODE><BR> |
---|
268 | <CODE>iostream_tag</CODE><BR> |
---|
269 | <CODE>streambuf_tag</CODE> |
---|
270 | </TD> |
---|
271 | <TD> |
---|
272 | Used internally to distinguish standard stream and stream buffer types |
---|
273 | </TD> |
---|
274 | </TR> |
---|
275 | <TR> |
---|
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> |
---|
278 | </TR> |
---|
279 | </TABLE> |
---|
280 | |
---|
281 | <!-- Begin Footnotes --> |
---|
282 | |
---|
283 | <HR> |
---|
284 | |
---|
285 | <P> |
---|
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="../../../../more/generic_programming.html#tag_dispatching" TARGET="_top">Tag Dispatching</A> for a discussion. |
---|
287 | </P> |
---|
288 | |
---|
289 | <!-- End Footnotes --> |
---|
290 | |
---|
291 | <!-- Begin Footer --> |
---|
292 | |
---|
293 | <HR> |
---|
294 | <P CLASS="copyright">Revised |
---|
295 | <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B %Y" startspan --> |
---|
296 | 20 May 2004 |
---|
297 | <!--webbot bot="Timestamp" endspan i-checksum="38504" --> |
---|
298 | </P> |
---|
299 | |
---|
300 | <P CLASS="copyright">© Copyright <A HREF="http://www.kangaroologic.com" TARGET="_top">Jonathan Turkanis</A> 2004</P> |
---|
301 | <P CLASS="copyright"> |
---|
302 | 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>) |
---|
303 | </P> |
---|
304 | |
---|
305 | <!-- End Footer --> |
---|
306 | |
---|
307 | </BODY> |
---|