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">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">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">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">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">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">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">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">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="http://www.boost.org/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 295<P CLASS="copyright">© Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>© Copyright 2004-2007 <a href="https://www.boost.org/users/people/jonathan_turkanis.html" 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>) 298</P> 299 300<!-- End Footer --> 301 302</BODY> 303