[29] | 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> |
---|