]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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<N, T>::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<T>::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<A, B, C, D></code></pre> | |
39 | ||
40 | <p>inherits from the type</p> | |
41 | <pre><code>cons<A, cons<B, cons<C, cons<D, null_type> > > > | |
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<A>::inherited</code> is the type <code>cons<A, null_type></code>. | |
46 | </p> | |
47 | ||
48 | <h4>Empty tuple</h4> | |
49 | <p> | |
50 | The internal representation of the empty tuple <code>tuple<></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&) {}; | |
74 | ||
75 | template <class H, class T> | |
76 | inline void set_to_zero(cons<H, T>& 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<head_type>::parameter_type h, | |
88 | const tail_type& 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<T>::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<T>::const_type</code> maps <code>T</code> to the return type of the const access functions.</li> | |
105 | <li><code>access_traits<T>::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<T>::type</code> implements the following type mapping:</p> | |
111 | <ul> | |
112 | <li><i>any reference type</i> -> <i>compile time error</i> | |
113 | </li> | |
114 | <li><i>any array type</i> -> <i>constant reference to the array type</i> | |
115 | </li> | |
116 | <li><code>reference_wrapper<T></code> -> <code>T&</code> | |
117 | </li> | |
118 | <li><code>T</code> -> <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>© Copyright Jaakko Järvi 2001.</p> | |
133 | </body> | |
134 | </html> |