ceph/src/boost/libs/iostreams/doc/guide/traits.html

   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">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>&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">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>&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="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">&copy; Copyright 2008 <a href="http://www.coderage.com/" target="_top">CodeRage, LLC</a><br/>&copy; 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>)
 298 </P>
 299
 300 <!-- End Footer -->
 301
 302 </BODY>