Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/boost_1_34_1/libs/iostreams/doc/guide/traits.html @ 29

Last change on this file since 29 was 29, checked in by landauf, 17 years ago

updated boost from 1_33_1 to 1_34_1
File size: 14.2 KB
Line 
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>&lt;boost/iostreams/categories.hpp&gt;</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>&lt;boost/iostreams/traits.hpp&gt;</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>&lt;boost/iostreams/categories.hpp&gt;</CODE></A></DT>
61  <DT><A CLASS="header" href="../../../../boost/iostreams/traits.hpp"><CODE>&lt;boost/iostreams/traits.hpp&gt;</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>&lt;<SPAN CLASS="keyword">typename</SPAN> <A HREF="#char_type_template_params" CLASS="documented">T</A>&gt;
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>&lt;<SPAN CLASS="keyword">typename</SPAN> <A HREF="#int_type_template_params" CLASS="documented">T</A>&gt;
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&lt;char_type&gt;::int_type</CODE>, where <CODE>char_type</CODE> is <A HREF="#char_type_of_ref"><CODE>char_type_of&lt;T&gt;::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>&lt;<SPAN CLASS="keyword">typename</SPAN> <A HREF="#category_template_params" CLASS="documented">T</A>&gt;
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>&lt;boost/iostreams/traits.hpp&gt;</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>&lt;boost/iostreams/categories.hpp&gt;</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 -->
29620 May 2004
297<!--webbot bot="Timestamp" endspan i-checksum="38504" -->
298</P>
299
300<P CLASS="copyright">&copy; 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>
Note: See TracBrowser for help on using the repository browser.