1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Chapter 1. Boost.Tuple</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="next" href="tuple_advanced_interface.html" title="Tuple library advanced features"> 9</head> 10<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 11<table cellpadding="2" width="100%"><tr> 12<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td> 13<td align="center"><a href="../../../../index.html">Home</a></td> 14<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td> 15<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 16<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 17<td align="center"><a href="../../../../more/index.htm">More</a></td> 18</tr></table> 19<hr> 20<div class="spirit-nav"><a accesskey="n" href="tuple_advanced_interface.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div> 21<div class="chapter"> 22<div class="titlepage"><div> 23<div><h2 class="title"> 24<a name="tuple"></a>Chapter 1. Boost.Tuple</h2></div> 25<div><p class="copyright">Copyright © 2001 Jaakko Järvi</p></div> 26<div><div class="legalnotice"> 27<a name="tuple.legal"></a><p> 28 Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost 29 Software License, Version 1.0</a>. 30 </p> 31</div></div> 32</div></div> 33<div class="toc"> 34<p><b>Table of Contents</b></p> 35<dl class="toc"> 36<dt><span class="article"><a href="tuple_advanced_interface.html">Tuple library advanced features</a></span></dt> 37<dt><span class="article"><a href="design_decisions_rationale.html">Design decisions rationale</a></span></dt> 38<dt><span class="section"><a href="tuple_users_guide.html#tuple.using_library">Using the Library</a></span></dt> 39<dt><span class="section"><a href="tuple_users_guide.html#tuple.tuple_types">Tuple Types</a></span></dt> 40<dt><span class="section"><a href="tuple_users_guide.html#tuple.constructing_tuples">Constructing Tuples</a></span></dt> 41<dt><span class="section"><a href="tuple_users_guide.html#tuple.accessing_elements">Accessing Tuple Elements</a></span></dt> 42<dt><span class="section"><a href="tuple_users_guide.html#tuple.construction_and_assignment">Copy Construction and 43 Tuple Assignment</a></span></dt> 44<dt><span class="section"><a href="tuple_users_guide.html#tuple.relational_operators">Relational Operators</a></span></dt> 45<dt><span class="section"><a href="tuple_users_guide.html#tuple.tiers">Tiers</a></span></dt> 46<dt><span class="section"><a href="tuple_users_guide.html#tuple.streaming">Streaming</a></span></dt> 47<dt><span class="section"><a href="tuple_users_guide.html#tuple.performance">Performance</a></span></dt> 48<dt><span class="section"><a href="tuple_users_guide.html#tuple.portability">Portability</a></span></dt> 49<dt><span class="section"><a href="tuple_users_guide.html#tuple.more_details">More Details</a></span></dt> 50<dt><span class="section"><a href="tuple_users_guide.html#tuple.thanks">Acknowledgements</a></span></dt> 51<dt><span class="section"><a href="tuple_users_guide.html#tuple.references">References</a></span></dt> 52</dl> 53</div> 54<p> 55 A tuple (or n-tuple) is a fixed size collection of elements. Pairs, triples, 56 quadruples etc. are tuples. In a programming language, a tuple is a data object 57 containing other objects as elements. These element objects may be of different 58 types. 59 </p> 60<p> 61 Tuples are convenient in many circumstances. For instance, tuples make it easy 62 to define functions that return more than one value. 63 </p> 64<p> 65 Some programming languages, such as ML, Python and Haskell, have built-in tuple 66 constructs. Unfortunately C++ does not. To compensate for this "deficiency", 67 the Boost Tuple Library implements a tuple construct using templates. 68 </p> 69<div class="section"> 70<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 71<a name="tuple.using_library"></a><a class="link" href="tuple_users_guide.html#tuple.using_library" title="Using the Library">Using the Library</a> 72</h2></div></div></div> 73<p> 74 To use the library, just include: 75 </p> 76<pre class="programlisting"><span class="preprocessor">#include</span> <span class="string">"boost/tuple/tuple.hpp"</span> 77</pre> 78<p> 79 Comparison operators can be included with: 80 </p> 81<pre class="programlisting"><span class="preprocessor">#include</span> <span class="string">"boost/tuple/tuple_comparison.hpp"</span> 82</pre> 83<p> 84 To use tuple input and output operators, 85 </p> 86<pre class="programlisting"><span class="preprocessor">#include</span> <span class="string">"boost/tuple/tuple_io.hpp"</span> 87</pre> 88<p> 89 Both <code class="computeroutput"><span class="identifier">tuple_io</span><span class="special">.</span><span class="identifier">hpp</span></code> and <code class="computeroutput"><span class="identifier">tuple_comparison</span><span class="special">.</span><span class="identifier">hpp</span></code> include 90 <code class="computeroutput"><span class="identifier">tuple</span><span class="special">.</span><span class="identifier">hpp</span></code>. 91 </p> 92<p> 93 All definitions are in namespace <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuples</span></code>, 94 but the most common names are lifted to namespace <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span></code> with using declarations. These names 95 are: <code class="computeroutput"><span class="identifier">tuple</span></code>, <code class="computeroutput"><span class="identifier">make_tuple</span></code>, 96 <code class="computeroutput"><span class="identifier">tie</span></code> and <code class="computeroutput"><span class="identifier">get</span></code>. 97 Further, <code class="computeroutput"><span class="identifier">ref</span></code> and <code class="computeroutput"><span class="identifier">cref</span></code> are defined directly under the <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span></code> namespace. 98 </p> 99</div> 100<div class="section"> 101<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 102<a name="tuple.tuple_types"></a><a class="link" href="tuple_users_guide.html#tuple.tuple_types" title="Tuple Types">Tuple Types</a> 103</h2></div></div></div> 104<p> 105 A tuple type is an instantiation of the <code class="computeroutput"><span class="identifier">tuple</span></code> 106 template. The template parameters specify the types of the tuple elements. 107 The current version supports tuples with 0-10 elements. If necessary, the upper 108 limit can be increased up to, say, a few dozen elements. The data element can 109 be any C++ type. Note that <code class="computeroutput"><span class="keyword">void</span></code> 110 and plain function types are valid C++ types, but objects of such types cannot 111 exist. Hence, if a tuple type contains such types as elements, the tuple type 112 can exist, but not an object of that type. There are natural limitations for 113 element types that cannot be copied, or that are not default constructible 114 (see <a class="link" href="tuple_users_guide.html#tuple.constructing_tuples" title="Constructing Tuples">'Constructing tuples'</a> 115 below). 116 </p> 117<p> 118 For example, the following definitions are valid tuple instantiations (<code class="computeroutput"><span class="identifier">A</span></code>, <code class="computeroutput"><span class="identifier">B</span></code> 119 and <code class="computeroutput"><span class="identifier">C</span></code> are some user defined 120 classes): 121 </p> 122<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">></span> 123<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">double</span><span class="special">&,</span> <span class="keyword">const</span> <span class="keyword">double</span><span class="special">&,</span> <span class="keyword">const</span> <span class="keyword">double</span><span class="special">,</span> <span class="keyword">double</span><span class="special">*,</span> <span class="keyword">const</span> <span class="keyword">double</span><span class="special">*></span> 124<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> <span class="keyword">int</span><span class="special">(*)(</span><span class="keyword">char</span><span class="special">,</span> <span class="keyword">int</span><span class="special">),</span> <span class="identifier">B</span><span class="special">(</span><span class="identifier">A</span><span class="special">::*)(</span><span class="identifier">C</span><span class="special">&),</span> <span class="identifier">C</span><span class="special">></span> 125<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</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="special">></span> 126<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">A</span><span class="special">*,</span> <span class="identifier">tuple</span><span class="special"><</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">*,</span> <span class="keyword">const</span> <span class="identifier">B</span><span class="special">&,</span> <span class="identifier">C</span><span class="special">>,</span> <span class="keyword">bool</span><span class="special">,</span> <span class="keyword">void</span><span class="special">*></span> 127</pre> 128</div> 129<div class="section"> 130<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 131<a name="tuple.constructing_tuples"></a><a class="link" href="tuple_users_guide.html#tuple.constructing_tuples" title="Constructing Tuples">Constructing Tuples</a> 132</h2></div></div></div> 133<p> 134 The tuple constructor takes the tuple elements as arguments. For an <span class="emphasis"><em>n</em></span>- 135 element tuple, the constructor can be invoked with <span class="emphasis"><em>k</em></span> arguments, 136 where <code class="computeroutput"><span class="number">0</span></code> <= <span class="emphasis"><em>k</em></span> 137 <= <span class="emphasis"><em>n</em></span>. For example: 138 </p> 139<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">>()</span> 140<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">>(</span><span class="number">1</span><span class="special">)</span> 141<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">>(</span><span class="number">1</span><span class="special">,</span> <span class="number">3.14</span><span class="special">)</span> 142</pre> 143<p> 144 If no initial value for an element is provided, it is default initialized (and 145 hence must be default initializable). For example: 146 </p> 147<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">X</span> <span class="special">{</span> 148 <span class="identifier">X</span><span class="special">();</span> 149<span class="keyword">public</span><span class="special">:</span> 150 <span class="identifier">X</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">);</span> 151<span class="special">};</span> 152 153<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">X</span><span class="special">>()</span> <span class="comment">// error: no default constructor for X</span> 154<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">X</span><span class="special">,</span><span class="identifier">X</span><span class="special">>(</span><span class="identifier">string</span><span class="special">(</span><span class="string">"Jaba"</span><span class="special">),</span> <span class="identifier">string</span><span class="special">(</span><span class="string">"Daba"</span><span class="special">),</span> <span class="identifier">string</span><span class="special">(</span><span class="string">"Duu"</span><span class="special">))</span> <span class="comment">// ok</span> 155</pre> 156<p> 157 In particular, reference types do not have a default initialization: 158 </p> 159<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">double</span><span class="special">&>()</span> <span class="comment">// error: reference must be</span> 160 <span class="comment">// initialized explicitly</span> 161 162<span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> 163<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">double</span><span class="special">&>(</span><span class="identifier">d</span><span class="special">)</span> <span class="comment">// ok</span> 164 165<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">double</span><span class="special">&>(</span><span class="identifier">d</span><span class="special">+</span><span class="number">3.14</span><span class="special">)</span> <span class="comment">// error: cannot initialize</span> 166 <span class="comment">// non-const reference with a temporary</span> 167 168<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">const</span> <span class="keyword">double</span><span class="special">&>(</span><span class="identifier">d</span><span class="special">+</span><span class="number">3.14</span><span class="special">)</span> <span class="comment">// ok, but dangerous:</span> 169 <span class="comment">// the element becomes a dangling reference</span> 170</pre> 171<p> 172 Using an initial value for an element that cannot be copied, is a compile time 173 error: 174 </p> 175<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">Y</span> <span class="special">{</span> 176 <span class="identifier">Y</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Y</span><span class="special">&);</span> 177<span class="keyword">public</span><span class="special">:</span> 178 <span class="identifier">Y</span><span class="special">();</span> 179<span class="special">};</span> 180 181<span class="keyword">char</span> <span class="identifier">a</span><span class="special">[</span><span class="number">10</span><span class="special">];</span> 182 183<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">char</span><span class="special">[</span><span class="number">10</span><span class="special">],</span> <span class="identifier">Y</span><span class="special">>(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">Y</span><span class="special">());</span> <span class="comment">// error, neither arrays nor Y can be copied</span> 184<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">char</span><span class="special">[</span><span class="number">10</span><span class="special">],</span> <span class="identifier">Y</span><span class="special">>();</span> <span class="comment">// ok</span> 185</pre> 186<p> 187 Note particularly that the following is perfectly ok: 188 </p> 189<pre class="programlisting"><span class="identifier">Y</span> <span class="identifier">y</span><span class="special">;</span> 190<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">char</span><span class="special">(&)[</span><span class="number">10</span><span class="special">],</span> <span class="identifier">Y</span><span class="special">&>(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">y</span><span class="special">);</span> 191</pre> 192<p> 193 It is possible to come up with a tuple type that cannot be constructed. This 194 occurs if an element that cannot be initialized has a lower index than an element 195 that requires initialization. For example: <code class="computeroutput"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">char</span><span class="special">[</span><span class="number">10</span><span class="special">],</span> <span class="keyword">int</span><span class="special">&></span></code>. 196 </p> 197<p> 198 In sum, the tuple construction is semantically just a group of individual elementary 199 constructions. 200 </p> 201<div class="section"> 202<div class="titlepage"><div><div><h3 class="title"> 203<a name="tuple.constructing_tuples.make_tuple"></a><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> 204</h3></div></div></div> 205<p> 206 Tuples can also be constructed using the <code class="computeroutput"><span class="identifier">make_tuple</span></code> 207 (cf. <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span></code>) helper functions. This makes 208 the construction more convenient, saving the programmer from explicitly specifying 209 the element types: 210 </p> 211<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">></span> <span class="identifier">add_multiply_divide</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">a</span><span class="special">,</span> <span class="keyword">int</span> <span class="identifier">b</span><span class="special">)</span> <span class="special">{</span> 212 <span class="keyword">return</span> <span class="identifier">make_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">a</span><span class="special">*</span><span class="identifier">b</span><span class="special">,</span> <span class="keyword">double</span><span class="special">(</span><span class="identifier">a</span><span class="special">)/</span><span class="keyword">double</span><span class="special">(</span><span class="identifier">b</span><span class="special">));</span> 213<span class="special">}</span> 214</pre> 215<p> 216 By default, the element types are deduced to the plain non-reference types. 217 E.g.: 218 </p> 219<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">foo</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</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">b</span><span class="special">)</span> <span class="special">{</span> 220 <span class="special">...</span> 221 <span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">a</span><span class="special">,</span> <span class="identifier">b</span><span class="special">);</span> 222</pre> 223<p> 224 The <code class="computeroutput"><span class="identifier">make_tuple</span></code> invocation 225 results in a tuple of type <code class="computeroutput"><span class="identifier">tuple</span><span class="special"><</span><span class="identifier">A</span><span class="special">,</span> 226 <span class="identifier">B</span><span class="special">></span></code>. 227 </p> 228<p> 229 Sometimes the plain non-reference type is not desired, e.g. if the element 230 type cannot be copied. Therefore, the programmer can control the type deduction 231 and state that a reference to const or reference to non-const type should 232 be used as the element type instead. This is accomplished with two helper 233 template functions: <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">ref</span></code></a> and <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">cref</span></code></a>. Any argument can be wrapped 234 with these functions to get the desired type. The mechanism does not compromise 235 const correctness since a const object wrapped with ref results in a tuple 236 element with const reference type (see the fifth example below). For example: 237 </p> 238<pre class="programlisting"><span class="identifier">A</span> <span class="identifier">a</span><span class="special">;</span> <span class="identifier">B</span> <span class="identifier">b</span><span class="special">;</span> <span class="keyword">const</span> <span class="identifier">A</span> <span class="identifier">ca</span> <span class="special">=</span> <span class="identifier">a</span><span class="special">;</span> 239<span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">cref</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="comment">// creates tuple<const A&, B></span> 240<span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">ref</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="comment">// creates tuple<A&, B></span> 241<span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">a</span><span class="special">),</span> <span class="identifier">cref</span><span class="special">(</span><span class="identifier">b</span><span class="special">));</span> <span class="comment">// creates tuple<A&, const B&></span> 242<span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">cref</span><span class="special">(</span><span class="identifier">ca</span><span class="special">));</span> <span class="comment">// creates tuple<const A&></span> 243<span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">ca</span><span class="special">));</span> <span class="comment">// creates tuple<const A&></span> 244</pre> 245<p> 246 Array arguments to <code class="computeroutput"><span class="identifier">make_tuple</span></code> 247 functions are deduced to reference to const types by default; there is no 248 need to wrap them with <code class="computeroutput"><span class="identifier">cref</span></code>. 249 For example: 250 </p> 251<pre class="programlisting"><span class="identifier">make_tuple</span><span class="special">(</span><span class="string">"Donald"</span><span class="special">,</span> <span class="string">"Daisy"</span><span class="special">);</span> 252</pre> 253<p> 254 This creates an object of type <code class="computeroutput"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">const</span> <span class="keyword">char</span> <span class="special">(&)[</span><span class="number">7</span><span class="special">],</span> <span class="keyword">const</span> 255 <span class="keyword">char</span> <span class="special">(&)[</span><span class="number">6</span><span class="special">]></span></code> (note 256 that the type of a string literal is an array of const characters, not <code class="computeroutput"><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span></code>). However, to get <code class="computeroutput"><span class="identifier">make_tuple</span></code> 257 to create a tuple with an element of a non-const array type one must use 258 the <code class="computeroutput"><span class="identifier">ref</span></code> wrapper. 259 </p> 260<p> 261 Function pointers are deduced to the plain non-reference type, that is, to 262 plain function pointer. A tuple can also hold a reference to a function, 263 but such a tuple cannot be constructed with <code class="computeroutput"><span class="identifier">make_tuple</span></code> 264 (a const qualified function type would result, which is illegal): 265 </p> 266<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span> <span class="identifier">i</span><span class="special">);</span> 267 <span class="special">...</span> 268<span class="identifier">make_tuple</span><span class="special">(&</span><span class="identifier">f</span><span class="special">);</span> <span class="comment">// tuple<void (*)(int)></span> 269 <span class="special">...</span> 270<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">void</span> <span class="special">(&)(</span><span class="keyword">int</span><span class="special">)></span> <span class="special">></span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">f</span><span class="special">)</span> <span class="comment">// ok</span> 271<span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">f</span><span class="special">);</span> <span class="comment">// not ok</span> 272</pre> 273</div> 274</div> 275<div class="section"> 276<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 277<a name="tuple.accessing_elements"></a><a class="link" href="tuple_users_guide.html#tuple.accessing_elements" title="Accessing Tuple Elements">Accessing Tuple Elements</a> 278</h2></div></div></div> 279<p> 280 Tuple elements are accessed with the expression: 281 </p> 282<pre class="programlisting"><span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="identifier">N</span><span class="special">>()</span> 283</pre> 284<p> 285 or 286 </p> 287<pre class="programlisting"><span class="identifier">get</span><span class="special"><</span><span class="identifier">N</span><span class="special">>(</span><span class="identifier">t</span><span class="special">)</span> 288</pre> 289<p> 290 where <code class="computeroutput"><span class="identifier">t</span></code> is a tuple object and 291 <code class="computeroutput"><span class="identifier">N</span></code> is a constant integral expression 292 specifying the index of the element to be accessed. Depending on whether <code class="computeroutput"><span class="identifier">t</span></code> is const or not, <code class="computeroutput"><span class="identifier">get</span></code> 293 returns the <code class="computeroutput"><span class="identifier">N</span></code>-th element as 294 a reference to const or non-const type. The index of the first element is 295 <code class="computeroutput"><span class="number">0</span></code> and thus <code class="computeroutput"><span class="identifier">N</span></code> 296 must be between <code class="computeroutput"><span class="number">0</span></code> and <span class="emphasis"><em>k</em></span><code class="computeroutput"><span class="special">-</span><span class="number">1</span></code>, where <span class="emphasis"><em>k</em></span> 297 is the number of elements in the tuple. Violations of these constraints are 298 detected at compile time. Examples: 299 </p> 300<pre class="programlisting"><span class="keyword">double</span> <span class="identifier">d</span> <span class="special">=</span> <span class="number">2.7</span><span class="special">;</span> <span class="identifier">A</span> <span class="identifier">a</span><span class="special">;</span> 301<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&,</span> <span class="keyword">const</span> <span class="identifier">A</span><span class="special">&></span> <span class="identifier">t</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="identifier">d</span><span class="special">,</span> <span class="identifier">a</span><span class="special">);</span> 302<span class="keyword">const</span> <span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&,</span> <span class="keyword">const</span> <span class="identifier">A</span><span class="special">&></span> <span class="identifier">ct</span> <span class="special">=</span> <span class="identifier">t</span><span class="special">;</span> 303 <span class="special">...</span> 304<span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">get</span><span class="special"><</span><span class="number">0</span><span class="special">>(</span><span class="identifier">t</span><span class="special">);</span> <span class="identifier">i</span> <span class="special">=</span> <span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="number">0</span><span class="special">>();</span> <span class="comment">// ok</span> 305<span class="keyword">int</span> <span class="identifier">j</span> <span class="special">=</span> <span class="identifier">get</span><span class="special"><</span><span class="number">0</span><span class="special">>(</span><span class="identifier">ct</span><span class="special">);</span> <span class="comment">// ok</span> 306<span class="identifier">get</span><span class="special"><</span><span class="number">0</span><span class="special">>(</span><span class="identifier">t</span><span class="special">)</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> <span class="comment">// ok</span> 307<span class="identifier">get</span><span class="special"><</span><span class="number">0</span><span class="special">>(</span><span class="identifier">ct</span><span class="special">)</span> <span class="special">=</span> <span class="number">5</span><span class="special">;</span> <span class="comment">// error, can't assign to const</span> 308 <span class="special">...</span> 309<span class="keyword">double</span> <span class="identifier">e</span> <span class="special">=</span> <span class="identifier">get</span><span class="special"><</span><span class="number">1</span><span class="special">>(</span><span class="identifier">t</span><span class="special">);</span> <span class="comment">// ok</span> 310<span class="identifier">get</span><span class="special"><</span><span class="number">1</span><span class="special">>(</span><span class="identifier">t</span><span class="special">)</span> <span class="special">=</span> <span class="number">3.14</span><span class="special">;</span> <span class="comment">// ok</span> 311<span class="identifier">get</span><span class="special"><</span><span class="number">2</span><span class="special">>(</span><span class="identifier">t</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">A</span><span class="special">();</span> <span class="comment">// error, can't assign to const</span> 312<span class="identifier">A</span> <span class="identifier">aa</span> <span class="special">=</span> <span class="identifier">get</span><span class="special"><</span><span class="number">3</span><span class="special">>(</span><span class="identifier">t</span><span class="special">);</span> <span class="comment">// error: index out of bounds</span> 313 <span class="special">...</span> 314<span class="special">++</span><span class="identifier">get</span><span class="special"><</span><span class="number">0</span><span class="special">>(</span><span class="identifier">t</span><span class="special">);</span> <span class="comment">// ok, can be used as any variable</span> 315</pre> 316<p> 317 <span class="emphasis"><em>[Note:</em></span> The member <code class="computeroutput"><span class="identifier">get</span></code> 318 functions are not supported with MS Visual C++ compiler. Further, the compiler 319 has trouble with finding the non-member <code class="computeroutput"><span class="identifier">get</span></code> 320 functions without an explicit namespace qualifier. Hence, all <code class="computeroutput"><span class="identifier">get</span></code> calls should be qualified as <code class="computeroutput"><span class="identifier">tuples</span><span class="special">::</span><span class="identifier">get</span><span class="special"><</span><span class="identifier">N</span><span class="special">>(</span><span class="identifier">a_tuple</span><span class="special">)</span></code> when writing code that should compile with 321 MSVC++ 6.0.<span class="emphasis"><em>]</em></span> 322 </p> 323</div> 324<div class="section"> 325<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 326<a name="tuple.construction_and_assignment"></a><a class="link" href="tuple_users_guide.html#tuple.construction_and_assignment" title="Copy Construction and Tuple Assignment">Copy Construction and 327 Tuple Assignment</a> 328</h2></div></div></div> 329<p> 330 A tuple can be copy constructed from another tuple, provided that the element 331 types are element-wise copy constructible. Analogously, a tuple can be assigned 332 to another tuple, provided that the element types are element-wise assignable. 333 For example: 334 </p> 335<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">A</span> <span class="special">{};</span> 336<span class="keyword">class</span> <span class="identifier">B</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">A</span> <span class="special">{};</span> 337<span class="keyword">struct</span> <span class="identifier">C</span> <span class="special">{</span> <span class="identifier">C</span><span class="special">();</span> <span class="identifier">C</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">B</span><span class="special">&);</span> <span class="special">};</span> 338<span class="keyword">struct</span> <span class="identifier">D</span> <span class="special">{</span> <span class="keyword">operator</span> <span class="identifier">C</span><span class="special">()</span> <span class="keyword">const</span><span class="special">;</span> <span class="special">};</span> 339<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">char</span><span class="special">,</span> <span class="identifier">B</span><span class="special">*,</span> <span class="identifier">B</span><span class="special">,</span> <span class="identifier">D</span><span class="special">></span> <span class="identifier">t</span><span class="special">;</span> 340 <span class="special">...</span> 341<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="identifier">A</span><span class="special">*,</span> <span class="identifier">C</span><span class="special">,</span> <span class="identifier">C</span><span class="special">></span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">t</span><span class="special">);</span> <span class="comment">// ok</span> 342<span class="identifier">a</span> <span class="special">=</span> <span class="identifier">t</span><span class="special">;</span> <span class="comment">// ok</span> 343</pre> 344<p> 345 In both cases, the conversions performed are: 346 </p> 347<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 348<li class="listitem"> 349 <code class="computeroutput"><span class="keyword">char</span> <span class="special">-></span> 350 <span class="keyword">int</span></code>, 351 </li> 352<li class="listitem"> 353 <code class="computeroutput"><span class="identifier">B</span><span class="special">*</span> 354 <span class="special">-></span> <span class="identifier">A</span><span class="special">*</span></code> (derived class pointer to base class pointer), 355 </li> 356<li class="listitem"> 357 <code class="computeroutput"><span class="identifier">B</span> <span class="special">-></span> 358 <span class="identifier">C</span></code> (a user defined conversion), 359 and 360 </li> 361<li class="listitem"> 362 <code class="computeroutput"><span class="identifier">D</span> <span class="special">-></span> 363 <span class="identifier">C</span></code> (a user defined conversion). 364 </li> 365</ul></div> 366<p> 367 Note that assignment is also defined from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span></code> types: 368 </p> 369<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">float</span><span class="special">,</span> <span class="keyword">int</span><span class="special">></span> <span class="identifier">a</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="char">'a'</span><span class="special">);</span> 370</pre> 371</div> 372<div class="section"> 373<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 374<a name="tuple.relational_operators"></a><a class="link" href="tuple_users_guide.html#tuple.relational_operators" title="Relational Operators">Relational Operators</a> 375</h2></div></div></div> 376<p> 377 Tuples reduce the operators <code class="computeroutput"><span class="special">==</span></code>, 378 <code class="computeroutput"><span class="special">!=</span></code>, <code class="computeroutput"><span class="special"><</span></code>, 379 <code class="computeroutput"><span class="special">></span></code>, <code class="computeroutput"><span class="special"><=</span></code> 380 and <code class="computeroutput"><span class="special">>=</span></code> to the corresponding 381 elementary operators. This means, that if any of these operators is defined 382 between all elements of two tuples, then the same operator is defined between 383 the tuples as well. The equality operators for two tuples <code class="computeroutput"><span class="identifier">a</span></code> 384 and <code class="computeroutput"><span class="identifier">b</span></code> are defined as: 385 </p> 386<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 387<li class="listitem"> 388 <code class="computeroutput"><span class="identifier">a</span> <span class="special">==</span> 389 <span class="identifier">b</span></code> iff for each <code class="computeroutput"><span class="identifier">i</span></code>: <code class="computeroutput"><span class="identifier">a</span></code><sub>i</sub><code class="computeroutput"> 390 <span class="special">==</span> <span class="identifier">b</span></code><sub>i</sub> 391 </li> 392<li class="listitem"> 393 <code class="computeroutput"><span class="identifier">a</span> <span class="special">!=</span> 394 <span class="identifier">b</span></code> iff exists <code class="computeroutput"><span class="identifier">i</span></code>: 395 <code class="computeroutput"><span class="identifier">a</span></code><sub>i</sub><code class="computeroutput"> <span class="special">!=</span> 396 <span class="identifier">b</span></code><sub>i</sub> 397 </li> 398</ul></div> 399<p> 400 The operators <code class="computeroutput"><span class="special"><</span></code>, <code class="computeroutput"><span class="special">></span></code>, <code class="computeroutput"><span class="special"><=</span></code> 401 and <code class="computeroutput"><span class="special">>=</span></code> implement a lexicographical 402 ordering. 403 </p> 404<p> 405 Note that an attempt to compare two tuples of different lengths results in 406 a compile time error. Also, the comparison operators are <span class="emphasis"><em>"short-circuited"</em></span>: 407 elementary comparisons start from the first elements and are performed only 408 until the result is clear. 409 </p> 410<p> 411 Examples: 412 </p> 413<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">A</span><span class="special">></span> <span class="identifier">t1</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"same?"</span><span class="special">),</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">A</span><span class="special">());</span> 414<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">long</span><span class="special">,</span> <span class="identifier">A</span><span class="special">></span> <span class="identifier">t2</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"same?"</span><span class="special">),</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">A</span><span class="special">());</span> 415<span class="identifier">tuple</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">,</span> <span class="keyword">long</span><span class="special">,</span> <span class="identifier">A</span><span class="special">></span> <span class="identifier">t3</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"different"</span><span class="special">),</span> <span class="number">3</span><span class="special">,</span> <span class="identifier">A</span><span class="special">());</span> 416 417<span class="keyword">bool</span> <span class="keyword">operator</span><span class="special">==(</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">A</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"All the same to me..."</span><span class="special">;</span> <span class="keyword">return</span> <span class="keyword">true</span><span class="special">;</span> <span class="special">}</span> 418 419<span class="identifier">t1</span> <span class="special">==</span> <span class="identifier">t2</span><span class="special">;</span> <span class="comment">// true</span> 420<span class="identifier">t1</span> <span class="special">==</span> <span class="identifier">t3</span><span class="special">;</span> <span class="comment">// false, does not print "All the..."</span> 421</pre> 422</div> 423<div class="section"> 424<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 425<a name="tuple.tiers"></a><a class="link" href="tuple_users_guide.html#tuple.tiers" title="Tiers">Tiers</a> 426</h2></div></div></div> 427<p> 428 <span class="emphasis"><em>Tiers</em></span> are tuples, where all elements are of non-const 429 reference types. They are constructed with a call to the <code class="computeroutput"><span class="identifier">tie</span></code> 430 function template (cf. <code class="computeroutput"><span class="identifier">make_tuple</span></code>): 431 </p> 432<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span> <span class="keyword">char</span> <span class="identifier">c</span><span class="special">;</span> <span class="keyword">double</span> <span class="identifier">d</span><span class="special">;</span> 433 <span class="special">...</span> 434<span class="identifier">tie</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">a</span><span class="special">);</span> 435</pre> 436<p> 437 The above <code class="computeroutput"><span class="identifier">tie</span></code> function creates 438 a tuple of type <code class="computeroutput"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">&,</span> <span class="keyword">char</span><span class="special">&,</span> <span class="keyword">double</span><span class="special">&></span></code>. The same result could be achieved 439 with the call <code class="computeroutput"><span class="identifier">make_tuple</span><span class="special">(</span><span class="identifier">ref</span><span class="special">(</span><span class="identifier">i</span><span class="special">),</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">c</span><span class="special">),</span> <span class="identifier">ref</span><span class="special">(</span><span class="identifier">a</span><span class="special">))</span></code>. 440 </p> 441<p> 442 A tuple that contains non-const references as elements can be used to 'unpack' 443 another tuple into variables. E.g.: 444 </p> 445<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span> <span class="keyword">char</span> <span class="identifier">c</span><span class="special">;</span> <span class="keyword">double</span> <span class="identifier">d</span><span class="special">;</span> 446<span class="identifier">tie</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">c</span><span class="special">,</span> <span class="identifier">d</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">make_tuple</span><span class="special">(</span><span class="number">1</span><span class="special">,</span><span class="char">'a'</span><span class="special">,</span> <span class="number">5.5</span><span class="special">);</span> 447<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">i</span> <span class="special"><<</span> <span class="string">" "</span> <span class="special"><<</span> <span class="identifier">c</span> <span class="special"><<</span> <span class="string">" "</span> <span class="special"><<</span> <span class="identifier">d</span><span class="special">;</span> 448</pre> 449<p> 450 This code prints <code class="computeroutput"><span class="number">1</span> <span class="identifier">a</span> 451 <span class="number">5.5</span></code> to the standard output stream. A 452 tuple unpacking operation like this is found for example in ML and Python. 453 It is convenient when calling functions which return tuples. 454 </p> 455<p> 456 The tying mechanism works with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span></code> templates 457 as well: 458 </p> 459<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span> <span class="keyword">char</span> <span class="identifier">c</span><span class="special">;</span> 460<span class="identifier">tie</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span> <span class="identifier">c</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="char">'a'</span><span class="special">);</span> 461</pre> 462<div class="section"> 463<div class="titlepage"><div><div><h3 class="title"> 464<a name="tuple.tiers.ignore"></a><a class="link" href="tuple_users_guide.html#tuple.tiers.ignore" title="Ignore">Ignore</a> 465</h3></div></div></div> 466<p> 467 There is also an object called <code class="computeroutput"><span class="identifier">ignore</span></code> 468 which allows you to ignore an element assigned by a tuple. The idea is that 469 a function may return a tuple, only part of which you are interested in. 470 For example (note, that ignore is under the <code class="computeroutput"><span class="identifier">tuples</span></code> 471 subnamespace): 472 </p> 473<pre class="programlisting"><span class="keyword">char</span> <span class="identifier">c</span><span class="special">;</span> 474<span class="identifier">tie</span><span class="special">(</span><span class="identifier">tuples</span><span class="special">::</span><span class="identifier">ignore</span><span class="special">,</span> <span class="identifier">c</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">make_pair</span><span class="special">(</span><span class="number">1</span><span class="special">,</span> <span class="char">'a'</span><span class="special">);</span> 475</pre> 476</div> 477</div> 478<div class="section"> 479<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 480<a name="tuple.streaming"></a><a class="link" href="tuple_users_guide.html#tuple.streaming" title="Streaming">Streaming</a> 481</h2></div></div></div> 482<p> 483 The global <code class="computeroutput"><span class="keyword">operator</span><span class="special"><<</span></code> 484 has been overloaded for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">ostream</span></code> 485 such that tuples are output by recursively calling <code class="computeroutput"><span class="keyword">operator</span><span class="special"><<</span></code> for each element. 486 </p> 487<p> 488 Analogously, the global <code class="computeroutput"><span class="keyword">operator</span><span class="special">>></span></code> has been overloaded to extract tuples 489 from <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">istream</span></code> by recursively calling <code class="computeroutput"><span class="keyword">operator</span><span class="special">>></span></code> 490 for each element. 491 </p> 492<p> 493 The default delimiter between the elements is space, and the tuple is enclosed 494 in parenthesis. For Example: 495 </p> 496<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">float</span><span class="special">,</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">></span> <span class="identifier">a</span><span class="special">(</span><span class="number">1.0f</span><span class="special">,</span> <span class="number">2</span><span class="special">,</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">(</span><span class="string">"Howdy folks!"</span><span class="special">);</span> 497 498<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">a</span><span class="special">;</span> 499</pre> 500<p> 501 outputs the tuple as: <code class="computeroutput"><span class="special">(</span><span class="number">1.0</span> 502 <span class="number">2</span> <span class="identifier">Howdy</span> 503 <span class="identifier">folks</span><span class="special">!)</span></code> 504 </p> 505<p> 506 The library defines three manipulators for changing the default behavior: 507 </p> 508<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 509<li class="listitem"> 510 <code class="computeroutput"><span class="identifier">set_open</span><span class="special">(</span><span class="keyword">char</span><span class="special">)</span></code> defines 511 the character that is output before the first element. 512 </li> 513<li class="listitem"> 514 <code class="computeroutput"><span class="identifier">set_close</span><span class="special">(</span><span class="keyword">char</span><span class="special">)</span></code> defines 515 the character that is output after the last element. 516 </li> 517<li class="listitem"> 518 <code class="computeroutput"><span class="identifier">set_delimiter</span><span class="special">(</span><span class="keyword">char</span><span class="special">)</span></code> defines 519 the delimiter character between elements. 520 </li> 521</ul></div> 522<p> 523 Note, that these manipulators are defined in the tuples subnamespace. For example: 524 </p> 525<pre class="programlisting"><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">set_open</span><span class="special">(</span><span class="char">'['</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">set_close</span><span class="special">(</span><span class="char">']'</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">set_delimiter</span><span class="special">(</span><span class="char">','</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">a</span><span class="special">;</span> 526</pre> 527<p> 528 outputs the same tuple <code class="computeroutput"><span class="identifier">a</span></code> as: 529 <code class="computeroutput"><span class="special">[</span><span class="number">1.0</span><span class="special">,</span><span class="number">2</span><span class="special">,</span><span class="identifier">Howdy</span> <span class="identifier">folks</span><span class="special">!]</span></code> 530 </p> 531<p> 532 The same manipulators work with <code class="computeroutput"><span class="keyword">operator</span><span class="special">>></span></code> and <code class="computeroutput"><span class="identifier">istream</span></code> 533 as well. Suppose the <code class="computeroutput"><span class="identifier">cin</span></code> stream 534 contains the following data: 535 </p> 536<pre class="programlisting"><span class="special">(</span><span class="number">1</span> <span class="number">2</span> <span class="number">3</span><span class="special">)</span> <span class="special">[</span><span class="number">4</span><span class="special">:</span><span class="number">5</span><span class="special">]</span> 537</pre> 538<p> 539 The code: 540 </p> 541<pre class="programlisting"><span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">></span> <span class="identifier">i</span><span class="special">;</span> 542<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">></span> <span class="identifier">j</span><span class="special">;</span> 543 544<span class="identifier">cin</span> <span class="special">>></span> <span class="identifier">i</span><span class="special">;</span> 545<span class="identifier">cin</span> <span class="special">>></span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">set_open</span><span class="special">(</span><span class="char">'['</span><span class="special">)</span> <span class="special">>></span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">set_close</span><span class="special">(</span><span class="char">']'</span><span class="special">)</span> <span class="special">>></span> <span class="identifier">tuples</span><span class="special">::</span><span class="identifier">set_delimiter</span><span class="special">(</span><span class="char">':'</span><span class="special">);</span> 546<span class="identifier">cin</span> <span class="special">>></span> <span class="identifier">j</span><span class="special">;</span> 547</pre> 548<p> 549 reads the data into the tuples <code class="computeroutput"><span class="identifier">i</span></code> 550 and <code class="computeroutput"><span class="identifier">j</span></code>. 551 </p> 552<p> 553 Note that extracting tuples with <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span></code> 554 or C-style string elements does not generally work, since the streamed tuple 555 representation may not be unambiguously parseable. 556 </p> 557</div> 558<div class="section"> 559<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 560<a name="tuple.performance"></a><a class="link" href="tuple_users_guide.html#tuple.performance" title="Performance">Performance</a> 561</h2></div></div></div> 562<p> 563 All tuple access and construction functions are small inlined one-liners. Therefore, 564 a decent compiler can eliminate any extra cost of using tuples compared to 565 using hand-written tuple like classes. Particularly, with a decent compiler 566 there is no performance difference between this code: 567 </p> 568<pre class="programlisting"><span class="keyword">class</span> <span class="identifier">hand_made_tuple</span> <span class="special">{</span> 569 <span class="identifier">A</span> <span class="identifier">a</span><span class="special">;</span> <span class="identifier">B</span> <span class="identifier">b</span><span class="special">;</span> <span class="identifier">C</span> <span class="identifier">c</span><span class="special">;</span> 570<span class="keyword">public</span><span class="special">:</span> 571 <span class="identifier">hand_made_tuple</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">A</span><span class="special">&</span> <span class="identifier">aa</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">B</span><span class="special">&</span> <span class="identifier">bb</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">C</span><span class="special">&</span> <span class="identifier">cc</span><span class="special">)</span> 572 <span class="special">:</span> <span class="identifier">a</span><span class="special">(</span><span class="identifier">aa</span><span class="special">),</span> <span class="identifier">b</span><span class="special">(</span><span class="identifier">bb</span><span class="special">),</span> <span class="identifier">c</span><span class="special">(</span><span class="identifier">cc</span><span class="special">)</span> <span class="special">{};</span> 573 <span class="identifier">A</span><span class="special">&</span> <span class="identifier">getA</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">a</span><span class="special">;</span> <span class="special">};</span> 574 <span class="identifier">B</span><span class="special">&</span> <span class="identifier">getB</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">b</span><span class="special">;</span> <span class="special">};</span> 575 <span class="identifier">C</span><span class="special">&</span> <span class="identifier">getC</span><span class="special">()</span> <span class="special">{</span> <span class="keyword">return</span> <span class="identifier">c</span><span class="special">;</span> <span class="special">};</span> 576<span class="special">};</span> 577 578<span class="identifier">hand_made_tuple</span> <span class="identifier">hmt</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> 579<span class="identifier">hmt</span><span class="special">.</span><span class="identifier">getA</span><span class="special">();</span> <span class="identifier">hmt</span><span class="special">.</span><span class="identifier">getB</span><span class="special">();</span> <span class="identifier">hmt</span><span class="special">.</span><span class="identifier">getC</span><span class="special">();</span> 580</pre> 581<p> 582 and this code: 583 </p> 584<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">t</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> 585<span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="number">0</span><span class="special">>();</span> <span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="number">1</span><span class="special">>();</span> <span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="number">2</span><span class="special">>();</span> 586</pre> 587<p> 588 Note, that there are widely used compilers (e.g. bcc 5.5.1) which fail to optimize 589 this kind of tuple usage. 590 </p> 591<p> 592 Depending on the optimizing ability of the compiler, the tier mechanism may 593 have a small performance penalty compared to using non-const reference parameters 594 as a mechanism for returning multiple values from a function. For example, 595 suppose that the following functions <code class="computeroutput"><span class="identifier">f1</span></code> 596 and <code class="computeroutput"><span class="identifier">f2</span></code> have equivalent functionalities: 597 </p> 598<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f1</span><span class="special">(</span><span class="keyword">int</span><span class="special">&,</span> <span class="keyword">double</span><span class="special">&);</span> 599<span class="identifier">tuple</span><span class="special"><</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">></span> <span class="identifier">f2</span><span class="special">();</span> 600</pre> 601<p> 602 Then, the call #1 may be slightly faster than #2 in the code below: 603 </p> 604<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">i</span><span class="special">;</span> <span class="keyword">double</span> <span class="identifier">d</span><span class="special">;</span> 605 <span class="special">...</span> 606<span class="identifier">f1</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span><span class="identifier">d</span><span class="special">);</span> <span class="comment">// #1</span> 607<span class="identifier">tie</span><span class="special">(</span><span class="identifier">i</span><span class="special">,</span><span class="identifier">d</span><span class="special">)</span> <span class="special">=</span> <span class="identifier">f2</span><span class="special">();</span> <span class="comment">// #2</span> 608</pre> 609<p> 610 See [<a class="link" href="tuple_users_guide.html#publ_1">1</a>, <a class="link" href="tuple_users_guide.html#publ_2">2</a>] for 611 more in-depth discussions about efficiency. 612 </p> 613<div class="section"> 614<div class="titlepage"><div><div><h3 class="title"> 615<a name="tuple.performance.effect_on_compile_time"></a><a class="link" href="tuple_users_guide.html#tuple.performance.effect_on_compile_time" title="Effect on Compile Time">Effect on Compile 616 Time</a> 617</h3></div></div></div> 618<p> 619 Compiling tuples can be slow due to the excessive amount of template instantiations. 620 Depending on the compiler and the tuple length, it may be more than 10 times 621 slower to compile a tuple construct, compared to compiling an equivalent 622 explicitly written class, such as the <code class="computeroutput"><span class="identifier">hand_made_tuple</span></code> 623 class above. However, as a realistic program is likely to contain a lot of 624 code in addition to tuple definitions, the difference is probably unnoticeable. 625 Compile time increases between 5 and 10 percent were measured for programs 626 which used tuples very frequently. With the same test programs, memory consumption 627 of compiling increased between 22% to 27%. See [<a class="link" href="tuple_users_guide.html#publ_1">1</a>, 628 <a class="link" href="tuple_users_guide.html#publ_2">2</a>] for details. 629 </p> 630</div> 631</div> 632<div class="section"> 633<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 634<a name="tuple.portability"></a><a class="link" href="tuple_users_guide.html#tuple.portability" title="Portability">Portability</a> 635</h2></div></div></div> 636<p> 637 The library code is(?) standard C++ and thus the library works with a standard 638 conforming compiler. Below is a list of compilers and known problems with each 639 compiler: 640 </p> 641<div class="informaltable"><table class="table"> 642<colgroup> 643<col> 644<col> 645</colgroup> 646<thead><tr> 647<th> 648 <p> 649 Compiler 650 </p> 651 </th> 652<th> 653 <p> 654 Problems 655 </p> 656 </th> 657</tr></thead> 658<tbody> 659<tr> 660<td> 661 <p> 662 gcc 2.95 663 </p> 664 </td> 665<td> 666 <p> 667 - 668 </p> 669 </td> 670</tr> 671<tr> 672<td> 673 <p> 674 edg 2.44 675 </p> 676 </td> 677<td> 678 <p> 679 - 680 </p> 681 </td> 682</tr> 683<tr> 684<td> 685 <p> 686 Borland 5.5 687 </p> 688 </td> 689<td> 690 <p> 691 Can't use function pointers or member pointers as tuple elements 692 </p> 693 </td> 694</tr> 695<tr> 696<td> 697 <p> 698 Metrowerks 6.2 699 </p> 700 </td> 701<td> 702 <p> 703 Can't use <code class="computeroutput"><span class="identifier">ref</span></code> and 704 <code class="computeroutput"><span class="identifier">cref</span></code> wrappers 705 </p> 706 </td> 707</tr> 708<tr> 709<td> 710 <p> 711 MS Visual C++ 712 </p> 713 </td> 714<td> 715 <p> 716 No reference elements (<code class="computeroutput"><span class="identifier">tie</span></code> 717 still works). Can't use <code class="computeroutput"><span class="identifier">ref</span></code> 718 and <code class="computeroutput"><span class="identifier">cref</span></code> wrappers 719 </p> 720 </td> 721</tr> 722</tbody> 723</table></div> 724</div> 725<div class="section"> 726<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 727<a name="tuple.more_details"></a><a class="link" href="tuple_users_guide.html#tuple.more_details" title="More Details">More Details</a> 728</h2></div></div></div> 729<p> 730 <a class="link" href="tuple_advanced_interface.html" title="Tuple library advanced features">Advanced features</a> (describes 731 some metafunctions etc.). 732 </p> 733<p> 734 <a class="link" href="design_decisions_rationale.html" title="Design decisions rationale">Rationale behind some design/implementation 735 decisions</a>. 736 </p> 737</div> 738<div class="section"> 739<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 740<a name="tuple.thanks"></a><a class="link" href="tuple_users_guide.html#tuple.thanks" title="Acknowledgements">Acknowledgements</a> 741</h2></div></div></div> 742<p> 743 Gary Powell has been an indispensable helping hand. In particular, stream manipulators 744 for tuples were his idea. Doug Gregor came up with a working version for MSVC, 745 David Abrahams found a way to get rid of most of the restrictions for compilers 746 not supporting partial specialization. Thanks to Jeremy Siek, William Kempf 747 and Jens Maurer for their help and suggestions. The comments by Vesa Karvonen, 748 John Max Skaller, Ed Brey, Beman Dawes, David Abrahams and Hartmut Kaiser helped 749 to improve the library. The idea for the <code class="computeroutput"><span class="identifier">tie</span></code> 750 mechanism came from an old usenet article by Ian McCulloch, where he proposed 751 something similar for <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">pair</span></code>s. 752 </p> 753</div> 754<div class="section"> 755<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 756<a name="tuple.references"></a><a class="link" href="tuple_users_guide.html#tuple.references" title="References">References</a> 757</h2></div></div></div> 758<p> 759 <a name="publ_1"></a>[1] Järvi J.: <span class="emphasis"><em>Tuples and multiple return 760 values in C++</em></span>, TUCS Technical Report No 249, 1999. 761 </p> 762<p> 763 <a name="publ_2"></a>[2] Järvi J.: <span class="emphasis"><em>ML-Style Tuple Assignment 764 in Standard C++ - Extending the Multiple Return Value Formalism</em></span>, 765 TUCS Technical Report No 267, 1999. 766 </p> 767<p> 768 <a name="publ_3"></a>[3] Järvi J.: <span class="emphasis"><em>Tuple Types and Multiple 769 Return Values</em></span>, C/C++ Users Journal, August 2001. 770 </p> 771</div> 772</div> 773<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 774<td align="left"><p><small>Last revised: August 11, 2020 at 14:59:08 GMT</small></p></td> 775<td align="right"><div class="copyright-footer"></div></td> 776</tr></table> 777<hr> 778<div class="spirit-nav"><a accesskey="n" href="tuple_advanced_interface.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a></div> 779</body> 780</html> 781
