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