1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Tuple library advanced features</title> 5<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="tuple_users_guide.html" title="Chapter 1. Boost.Tuple"> 8<link rel="up" href="tuple_users_guide.html" title="Chapter 1. Boost.Tuple"> 9<link rel="prev" href="tuple_users_guide.html" title="Chapter 1. Boost.Tuple"> 10<link rel="next" href="design_decisions_rationale.html" title="Design decisions rationale"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> 15<td align="center"><a href="../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="tuple_users_guide.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tuple_users_guide.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="tuple_users_guide.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_decisions_rationale.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="article"> 26<div class="titlepage"> 27<div> 28<div><h2 class="title"> 29<a name="tuple_advanced_interface"></a>Tuple library advanced features</h2></div> 30<div><p class="copyright">Copyright © 2001 Jaakko Järvi</p></div> 31<div><div class="legalnotice"> 32<a name="tuple_advanced_interface.legal"></a><p> 33 Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost 34 Software License, Version 1.0</a>. 35 </p> 36</div></div> 37</div> 38<hr> 39</div> 40<div class="toc"> 41<p><b>Table of Contents</b></p> 42<dl class="toc"> 43<dt><span class="section"><a href="tuple_advanced_interface.html#tuple_advanced_interface.metafunctions_for_tuple_types">Metafunctions 44 for tuple types</a></span></dt> 45<dt><span class="section"><a href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists">Cons lists</a></span></dt> 46<dt><span class="section"><a href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element">Traits 47 classes for tuple element types</a></span></dt> 48</dl> 49</div> 50<p> 51 The advanced features described in this document are all under namespace <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuples</span></code> 52 </p> 53<div class="section"> 54<div class="titlepage"><div><div><h3 class="title"> 55<a name="tuple_advanced_interface.metafunctions_for_tuple_types"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.metafunctions_for_tuple_types" title="Metafunctions for tuple types">Metafunctions 56 for tuple types</a> 57</h3></div></div></div> 58<p> 59 Suppose <code class="computeroutput"><span class="identifier">T</span></code> is a tuple type, 60 and <code class="computeroutput"><span class="identifier">N</span></code> is a constant integral 61 expression. 62 </p> 63<pre class="programlisting"><span class="identifier">element</span><span class="special"><</span><span class="identifier">N</span><span class="special">,</span> <span class="identifier">T</span><span class="special">>::</span><span class="identifier">type</span> 64</pre> 65<p> 66 gives the type of the <code class="computeroutput"><span class="identifier">N</span></code>-th 67 element in the tuple type <code class="computeroutput"><span class="identifier">T</span></code>. 68 If <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="keyword">const</span></code>, 69 the resulting type is <code class="computeroutput"><span class="keyword">const</span></code> 70 qualified as well. Note that the constness of <code class="computeroutput"><span class="identifier">T</span></code> 71 does not affect reference type elements. 72 </p> 73<pre class="programlisting"><span class="identifier">length</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">value</span> 74</pre> 75<p> 76 gives the length of the tuple type <code class="computeroutput"><span class="identifier">T</span></code>. 77 </p> 78</div> 79<div class="section"> 80<div class="titlepage"><div><div><h3 class="title"> 81<a name="tuple_advanced_interface.cons_lists"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists" title="Cons lists">Cons lists</a> 82</h3></div></div></div> 83<p> 84 Tuples are internally represented as <span class="emphasis"><em>cons lists</em></span>. For 85 example, the tuple 86 </p> 87<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">D</span><span class="special">></span> 88</pre> 89<p> 90 inherits from the type 91 </p> 92<pre class="programlisting"><span class="identifier">cons</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">cons</span><span class="special"><</span><span class="identifier">B</span><span class="special">,</span> <span class="identifier">cons</span><span class="special"><</span><span class="identifier">C</span><span class="special">,</span> <span class="identifier">cons</span><span class="special"><</span><span class="identifier">D</span><span class="special">,</span> <span class="identifier">null_type</span><span class="special">></span> <span class="special">></span> <span class="special">></span> <span class="special">></span> 93</pre> 94<p> 95 The tuple template provides the typedef inherited to access the cons list 96 representation. E.g.: <code class="computeroutput"><span class="identifier">tuple</span><span class="special"><</span><span class="identifier">A</span><span class="special">>::</span><span class="identifier">inherited</span></code> is the type <code class="computeroutput"><span class="identifier">cons</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> 97 <span class="identifier">null_type</span><span class="special">></span></code>. 98 </p> 99<div class="section"> 100<div class="titlepage"><div><div><h4 class="title"> 101<a name="tuple_advanced_interface.cons_lists.empty_tuple"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists.empty_tuple" title="Empty tuple">Empty 102 tuple</a> 103</h4></div></div></div> 104<p> 105 The internal representation of the empty tuple <code class="computeroutput"><span class="identifier">tuple</span><span class="special"><></span></code> is <code class="computeroutput"><span class="identifier">null_type</span></code>. 106 </p> 107</div> 108<div class="section"> 109<div class="titlepage"><div><div><h4 class="title"> 110<a name="tuple_advanced_interface.cons_lists.head_and_tail"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists.head_and_tail" title="Head and tail">Head 111 and tail</a> 112</h4></div></div></div> 113<p> 114 Both tuple template and the cons templates provide the typedefs <code class="computeroutput"><span class="identifier">head_type</span></code> and <code class="computeroutput"><span class="identifier">tail_type</span></code>. 115 The <code class="computeroutput"><span class="identifier">head_type</span></code> typedef gives 116 the type of the first element of the tuple (or the cons list). The <code class="computeroutput"><span class="identifier">tail_type</span></code> typedef gives the remaining 117 cons list after removing the first element. The head element is stored 118 in the member variable <code class="computeroutput"><span class="identifier">head</span></code> 119 and the tail list in the member variable <code class="computeroutput"><span class="identifier">tail</span></code>. 120 Cons lists provide the member function <code class="computeroutput"><span class="identifier">get_head</span><span class="special">()</span></code> for getting a reference to the head of 121 a cons list, and <code class="computeroutput"><span class="identifier">get_tail</span><span class="special">()</span></code> for getting a reference to the tail. 122 There are const and non-const versions of both functions. 123 </p> 124<p> 125 Note that in a one element tuple, <code class="computeroutput"><span class="identifier">tail_type</span></code> 126 equals <code class="computeroutput"><span class="identifier">null_type</span></code> and the 127 <code class="computeroutput"><span class="identifier">get_tail</span><span class="special">()</span></code> 128 function returns an object of type <code class="computeroutput"><span class="identifier">null_type</span></code>. 129 </p> 130<p> 131 The empty tuple (<code class="computeroutput"><span class="identifier">null_type</span></code>) 132 has no head or tail, hence the <code class="computeroutput"><span class="identifier">get_head</span></code> 133 and <code class="computeroutput"><span class="identifier">get_tail</span></code> functions 134 are not provided. 135 </p> 136<p> 137 Treating tuples as cons lists gives a convenient means to define generic 138 functions to manipulate tuples. For example, the following pair of function 139 templates assign <code class="computeroutput"><span class="number">0</span></code> to each 140 element of a tuple (obviously, the assignments must be valid operations 141 for the element types): 142 </p> 143<pre class="programlisting"><span class="keyword">inline</span> <span class="keyword">void</span> <span class="identifier">set_to_zero</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">null_type</span><span class="special">&)</span> <span class="special">{};</span> 144 145<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">H</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span> 146<span class="keyword">inline</span> <span class="keyword">void</span> <span class="identifier">set_to_zero</span><span class="special">(</span><span class="identifier">cons</span><span class="special"><</span><span class="identifier">H</span><span class="special">,</span> <span class="identifier">T</span><span class="special">>&</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">get_head</span><span class="special">()</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">set_to_zero</span><span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">get_tail</span><span class="special">());</span> <span class="special">}</span> 147</pre> 148</div> 149<div class="section"> 150<div class="titlepage"><div><div><h4 class="title"> 151<a name="tuple_advanced_interface.cons_lists.constructing_cons_lists"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists.constructing_cons_lists" title="Constructing cons lists">Constructing 152 cons lists</a> 153</h4></div></div></div> 154<p> 155 A cons list can be default constructed provided that all its elements can 156 be default constructed. 157 </p> 158<p> 159 A cons list can be constructed from its head and tail. The prototype of 160 the constructor is: 161 </p> 162<pre class="programlisting"><span class="identifier">cons</span><span class="special">(</span><span class="keyword">typename</span> <span class="identifier">access_traits</span><span class="special"><</span><span class="identifier">head_type</span><span class="special">>::</span><span class="identifier">parameter_type</span> <span class="identifier">h</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">tail_type</span><span class="special">&</span> <span class="identifier">t</span><span class="special">)</span> 163</pre> 164<p> 165 The traits template for the head parameter selects correct parameter types 166 for different kinds of element types (for reference elements the parameter 167 type equals the element type, for non-reference types the parameter type 168 is a reference to const non-volatile element type). 169 </p> 170<p> 171 For a one-element cons list the tail argument (<code class="computeroutput"><span class="identifier">null_type</span></code>) 172 can be omitted. 173 </p> 174</div> 175</div> 176<div class="section"> 177<div class="titlepage"><div><div><h3 class="title"> 178<a name="tuple_advanced_interface.traits_classes_for_tuple_element"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element" title="Traits classes for tuple element types">Traits 179 classes for tuple element types</a> 180</h3></div></div></div> 181<div class="section"> 182<div class="titlepage"><div><div><h4 class="title"> 183<a name="tuple_advanced_interface.traits_classes_for_tuple_element.access_traits"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element.access_traits" title="access_traits">access_traits</a> 184</h4></div></div></div> 185<p> 186 The template <code class="computeroutput"><span class="identifier">access_traits</span></code> 187 defines three type functions. Let <code class="computeroutput"><span class="identifier">T</span></code> 188 be a type of an element in a tuple: 189 </p> 190<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 191<li class="listitem"> 192 <code class="computeroutput"><span class="identifier">access_traits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">non_const_type</span></code> maps <code class="computeroutput"><span class="identifier">T</span></code> to the return type of the no n-const 193 access functions (nonmember and member <code class="computeroutput"><span class="identifier">get</span></code> 194 functions, and the <code class="computeroutput"><span class="identifier">get_head</span></code> 195 function). 196 </li> 197<li class="listitem"> 198 <code class="computeroutput"><span class="identifier">access_traits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">const_type</span></code> maps <code class="computeroutput"><span class="identifier">T</span></code> 199 to the return type of the const access functions. 200 </li> 201<li class="listitem"> 202 <code class="computeroutput"><span class="identifier">access_traits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">parameter_type</span></code> maps <code class="computeroutput"><span class="identifier">T</span></code> to the parameter type of the tuple 203 constructor. 204 </li> 205</ul></div> 206</div> 207<div class="section"> 208<div class="titlepage"><div><div><h4 class="title"> 209<a name="tuple_advanced_interface.traits_classes_for_tuple_element.make_tuple_traits"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element.make_tuple_traits" title="make_tuple_traits">make_tuple_traits</a> 210</h4></div></div></div> 211<p> 212 The element types of the tuples that are created with the <code class="computeroutput"><span class="identifier">make_tuple</span></code> functions are computed with 213 the type function <code class="computeroutput"><span class="identifier">make_tuple_traits</span></code>. 214 The type function call <code class="computeroutput"><span class="identifier">make_tuple_traits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">type</span></code> 215 implements the following type mapping: 216 </p> 217<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 218<li class="listitem"> 219 <span class="emphasis"><em>any reference type</em></span> -> <span class="emphasis"><em>compile time 220 error</em></span> 221 </li> 222<li class="listitem"> 223 <span class="emphasis"><em>any array type</em></span> -> <span class="emphasis"><em>constant reference 224 to the array type</em></span> 225 </li> 226<li class="listitem"> 227 <code class="computeroutput"><span class="identifier">reference_wrapper</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> 228 -> <code class="computeroutput"><span class="identifier">T</span><span class="special">&</span></code> 229 </li> 230<li class="listitem"> 231 <code class="computeroutput"><span class="identifier">T</span></code> -> <code class="computeroutput"><span class="identifier">T</span></code> 232 </li> 233</ul></div> 234<p> 235 Objects of type <code class="computeroutput"><span class="identifier">reference_wrapper</span></code> 236 are created with the <code class="computeroutput"><span class="identifier">ref</span></code> 237 and <code class="computeroutput"><span class="identifier">cref</span></code> functions (see 238 <a class="link" href="tuple_users_guide.html#tuple.constructing_tuples.make_tuple" title="The make_tuple function">The <code class="computeroutput"><span class="identifier">make_tuple</span></code> function</a>). 239 </p> 240<p> 241 Reference wrappers were originally part of the tuple library, but they 242 are now a general utility of boost. The <code class="computeroutput"><span class="identifier">reference_wrapper</span></code> 243 template and the <code class="computeroutput"><span class="identifier">ref</span></code> and 244 <code class="computeroutput"><span class="identifier">cref</span></code> functions are defined 245 in a separate file <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">ref</span><span class="special">.</span><span class="identifier">hpp</span></code></a> in the main boost include 246 directory; and directly in the <code class="computeroutput"><span class="identifier">boost</span></code> 247 namespace. 248 </p> 249</div> 250</div> 251</div> 252<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 253<td align="left"><p><small>Last revised: August 11, 2020 at 14:59:08 GMT</small></p></td> 254<td align="right"><div class="copyright-footer">Copyright © 2001 Jaakko Järvi<p> 255 Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost 256 Software License, Version 1.0</a>. 257 </p> 258</div></td> 259</tr></table> 260<hr> 261<div class="spirit-nav"> 262<a accesskey="p" href="tuple_users_guide.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tuple_users_guide.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="tuple_users_guide.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_decisions_rationale.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a> 263</div> 264</body> 265</html> 266
