ceph/src/boost/libs/tuple/doc/tuple_advanced_interface.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3   <head>
   4     <title>Tuple library advanced features</title>
   5   </head>
   6
   7 <body bgcolor="#FFFFFF" text="#000000">
   8
   9 <IMG SRC="../../../boost.png"
  10      ALT="C++ Boost" width="277" height="86">
  11
  12     <h1>Tuple library advanced features</h1>
  13
  14 The advanced features described in this document are all under namespace <code>::boost::tuples</code>
  15
  16 <h2>Metafunctions for tuple types</h2>
  17 <p>
  18 Suppose <code>T</code> is a tuple type, and <code>N</code> is a constant integral expression.</p>
  19
  20 <pre><code>element&lt;N, T&gt;::type</code></pre>
  21
  22 <p>gives the type of the <code>N</code>th element in the tuple type <code>T</code>. If <code>T</code> is const, the resulting type is const qualified as well.
  23 Note that the constness of <code>T</code> does not affect reference type
  24 elements.
  25 </p>
  26
  27 <pre><code>length&lt;T&gt;::value</code></pre>
  28
  29 <p>gives the length of the tuple type <code>T</code>.
  30 </p>
  31
  32 <h2>Cons lists</h2>
  33
  34 <p>
  35 Tuples are internally represented as <i>cons lists</i>.
  36 For example, the tuple </p>
  37
  38 <pre><code>tuple&lt;A, B, C, D&gt;</code></pre>
  39
  40 <p>inherits from the type</p>
  41 <pre><code>cons&lt;A, cons&lt;B, cons&lt;C, cons&lt;D, null_type&gt; &gt; &gt; &gt;
  42 </code></pre>
  43
  44 <p>The tuple template provides the typedef <code>inherited</code> to access the cons list representation. E.g.:
  45 <code>tuple&lt;A&gt;::inherited</code> is the type <code>cons&lt;A, null_type&gt;</code>.
  46 </p>
  47
  48 <h4>Empty tuple</h4>
  49 <p>
  50 The internal representation of the empty tuple <code>tuple&lt;&gt;</code> is <code>null_type</code>.
  51 </p>
  52
  53 <h4>Head and tail</h4>
  54 <p>
  55 Both tuple template and the cons templates provide the typedefs <code>head_type</code> and <code>tail_type</code>.
  56 The <code>head_type</code> typedef gives the type of the first element of the tuple (or the cons list).
  57 The
  58 <code>tail_type</code> typedef gives the remaining cons list after removing the first element.
  59 The head element is stored in the member variable <code>head</code> and the tail list in the member variable <code>tail</code>.
  60 Cons lists provide the member function <code>get_head()</code> for getting a reference to the head of a cons list, and <code>get_tail()</code> for getting a reference to the tail.
  61 There are const and non-const versions of both functions.
  62 </p>
  63 <p>
  64 Note that in a one element tuple, <code>tail_type</code> equals <code>null_type</code> and the <code>get_tail()</code> function returns an object of type <code>null_type</code>.
  65 </p>
  66 <p>
  67 The empty tuple (<code>null_type</code>) has no head or tail, hence the <code>get_head</code> and <code>get_tail</code> functions are not provided.
  68 </p>
  69
  70 <p>
  71 Treating tuples as cons lists gives a convenient means to define generic functions to manipulate tuples. For example, the following pair of function templates assign 0 to each element of a tuple (obviously, the assignments must be valid operations for the element types):
  72
  73 <pre><code>inline void set_to_zero(const null_type&amp;) {};
  74
  75 template &lt;class H, class T&gt;
  76 inline void set_to_zero(cons&lt;H, T&gt;&amp; x) { x.get_head() = 0; set_to_zero(x.get_tail()); }
  77 </code></pre>
  78 <p>
  79
  80 <h4>Constructing cons lists</h4>
  81
  82 <p>
  83 A cons list can be default constructed provided that all its elements can be default constructed.
  84 </p>
  85 <p>
  86 A cons list can be constructed from its head and tail. The prototype of the constructor is:</p>
  87 <pre><code>cons(typename access_traits&lt;head_type&gt;::parameter_type h,
  88      const tail_type&amp; t)
  89 </code></pre>
  90 <p>The traits template for the head parameter selects correct parameter types for different kinds of element types (for reference elements the parameter type equals the element type, for non-reference types the parameter type is a reference to const non-volatile element type).
  91 </p>
  92 <p>
  93 For a one-element cons list the tail argument (<code>null_type</code>) can be omitted.
  94 </p>
  95
  96
  97 <h2>Traits classes for tuple element types</h2>
  98
  99 <h4><code>access_traits</code></h4>
 100 <p>
 101 The template <code>access_traits</code> defines three type functions. Let <code>T</code> be a type of an element in a tuple:</p>
 102 <ol>
 103 <li><code>access_traits&lt;T&gt;::non_const_type</code> maps <code>T</code> to the return type of the non-const access functions (nonmember and member <code>get</code> functions, and the <code>get_head</code> function).</li>
 104 <li><code>access_traits&lt;T&gt;::const_type</code> maps <code>T</code> to the return type of the const access functions.</li>
 105 <li><code>access_traits&lt;T&gt;::parameter_type</code> maps <code>T</code> to the parameter type of the tuple constructor.</li>
 106 </ol>
 107 <h4><code>make_tuple_traits</code></h4>
 108
 109 <p>The element types of the tuples that are created with the <code>make_tuple</code> functions are computed with the type function <code>make_tuple_traits</code>.
 110 The type function call <code>make_tuple_traits&lt;T&gt;::type</code> implements the following type mapping:</p>
 111 <ul>
 112 <li><i>any reference type</i> -&gt; <i>compile time error</i>
 113 </li>
 114 <li><i>any array type</i> -&gt; <i>constant reference to the array type</i>
 115 </li>
 116 <li><code>reference_wrapper&lt;T&gt;</code> -&gt; <code>T&amp;</code>
 117 </li>
 118 <li><code>T</code> -&gt; <code>T</code>
 119 </li>
 120 </ul>
 121
 122 <p>Objects of type <code>reference_wrapper</code> are created with the <code>ref</code> and <code>cref</code> functions (see <A href="tuple_users_guide.html#make_tuple">The <code>make_tuple</code> function</A>.)
 123 </p>
 124
 125 <p>Reference wrappers were originally part of the tuple library, but they are now a general utility of boost.
 126 The <code>reference_wrapper</code> template and the <code>ref</code> and <code>cref</code> functions are defined in a separate file <code>ref.hpp</code> in the main boost include directory; and directly in the <code>boost</code> namespace.
 127 </p>
 128
 129 <A href="tuple_users_guide.html">Back to the user's guide</A>
 130 <hr>
 131
 132 <p>&copy; Copyright Jaakko J&auml;rvi 2001.</p>
 133   </body>
 134 </html>