libs/tuple/doc/html/tuple_users_guide.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Chapter&#160;1.&#160;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&#160;1.&#160;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&#160;1.&#160;Boost.Tuple</h2></div>
  25 <div><p class="copyright">Copyright &#169; 2001 Jaakko J&#228;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">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span>
 123 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">double</span><span class="special">&amp;,</span> <span class="keyword">const</span> <span class="keyword">double</span><span class="special">&amp;,</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">*&gt;</span>
 124 <span class="identifier">tuple</span><span class="special">&lt;</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">&amp;),</span> <span class="identifier">C</span><span class="special">&gt;</span>
 125 <span class="identifier">tuple</span><span class="special">&lt;</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">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&gt;</span> <span class="special">&gt;</span>
 126 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">*,</span> <span class="identifier">tuple</span><span class="special">&lt;</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">&amp;,</span> <span class="identifier">C</span><span class="special">&gt;,</span> <span class="keyword">bool</span><span class="special">,</span> <span class="keyword">void</span><span class="special">*&gt;</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> &lt;= <span class="emphasis"><em>k</em></span>
 137       &lt;= <span class="emphasis"><em>n</em></span>. For example:
 138     </p>
 139 <pre class="programlisting"><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;()</span>
 140 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;(</span><span class="number">1</span><span class="special">)</span>
 141 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;(</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">&lt;</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">&gt;()</span>                                              <span class="comment">// error: no default constructor for X</span>
 154 <span class="identifier">tuple</span><span class="special">&lt;</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">&gt;(</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">&lt;</span><span class="keyword">double</span><span class="special">&amp;&gt;()</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">&lt;</span><span class="keyword">double</span><span class="special">&amp;&gt;(</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">&lt;</span><span class="keyword">double</span><span class="special">&amp;&gt;(</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">&lt;</span><span class="keyword">const</span> <span class="keyword">double</span><span class="special">&amp;&gt;(</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">&amp;);</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">&lt;</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">&gt;(</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">&lt;</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">&gt;();</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">&lt;</span><span class="keyword">char</span><span class="special">(&amp;)[</span><span class="number">10</span><span class="special">],</span> <span class="identifier">Y</span><span class="special">&amp;&gt;(</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">&lt;</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">&amp;&gt;</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">&lt;</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">&gt;</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">&amp;</span> <span class="identifier">a</span><span class="special">,</span> <span class="identifier">B</span><span class="special">&amp;</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">&lt;</span><span class="identifier">A</span><span class="special">,</span>
 226         <span class="identifier">B</span><span class="special">&gt;</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&lt;const A&amp;, B&gt;</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&lt;A&amp;, B&gt;</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&lt;A&amp;, const B&amp;&gt;</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&lt;const A&amp;&gt;</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&lt;const A&amp;&gt;</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">&lt;</span><span class="keyword">const</span> <span class="keyword">char</span> <span class="special">(&amp;)[</span><span class="number">7</span><span class="special">],</span> <span class="keyword">const</span>
 255         <span class="keyword">char</span> <span class="special">(&amp;)[</span><span class="number">6</span><span class="special">]&gt;</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">(&amp;</span><span class="identifier">f</span><span class="special">);</span> <span class="comment">// tuple&lt;void (*)(int)&gt;</span>
 269   <span class="special">...</span>
 270 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">void</span> <span class="special">(&amp;)(</span><span class="keyword">int</span><span class="special">)&gt;</span> <span class="special">&gt;</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">&lt;</span><span class="identifier">N</span><span class="special">&gt;()</span>
 283 </pre>
 284 <p>
 285       or
 286     </p>
 287 <pre class="programlisting"><span class="identifier">get</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">&gt;(</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">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&amp;,</span> <span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;&gt;</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">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&amp;,</span> <span class="keyword">const</span> <span class="identifier">A</span><span class="special">&amp;&gt;</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">&lt;</span><span class="number">0</span><span class="special">&gt;(</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">&lt;</span><span class="number">0</span><span class="special">&gt;();</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">&lt;</span><span class="number">0</span><span class="special">&gt;(</span><span class="identifier">ct</span><span class="special">);</span>                       <span class="comment">// ok</span>
 306 <span class="identifier">get</span><span class="special">&lt;</span><span class="number">0</span><span class="special">&gt;(</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">&lt;</span><span class="number">0</span><span class="special">&gt;(</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">&lt;</span><span class="number">1</span><span class="special">&gt;(</span><span class="identifier">t</span><span class="special">);</span> <span class="comment">// ok</span>
 310 <span class="identifier">get</span><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;(</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">&lt;</span><span class="number">2</span><span class="special">&gt;(</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">&lt;</span><span class="number">3</span><span class="special">&gt;(</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">&lt;</span><span class="number">0</span><span class="special">&gt;(</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">&lt;</span><span class="identifier">N</span><span class="special">&gt;(</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">&amp;);</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">&lt;</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">&gt;</span> <span class="identifier">t</span><span class="special">;</span>
 340   <span class="special">...</span>
 341 <span class="identifier">tuple</span><span class="special">&lt;</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">&gt;</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">-&gt;</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">-&gt;</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">-&gt;</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">-&gt;</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">&lt;</span><span class="keyword">float</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</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">&lt;</span></code>,
 379       <code class="computeroutput"><span class="special">&gt;</span></code>, <code class="computeroutput"><span class="special">&lt;=</span></code>
 380       and <code class="computeroutput"><span class="special">&gt;=</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">&lt;</span></code>, <code class="computeroutput"><span class="special">&gt;</span></code>, <code class="computeroutput"><span class="special">&lt;=</span></code>
 401       and <code class="computeroutput"><span class="special">&gt;=</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">&lt;</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">&gt;</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">&lt;</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">&gt;</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">&lt;</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">&gt;</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">&lt;&lt;</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">&lt;</span><span class="keyword">int</span><span class="special">&amp;,</span> <span class="keyword">char</span><span class="special">&amp;,</span> <span class="keyword">double</span><span class="special">&amp;&gt;</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">&lt;&lt;</span> <span class="identifier">i</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</span>  <span class="identifier">c</span> <span class="special">&lt;&lt;</span> <span class="string">" "</span> <span class="special">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</span></code> for each element.
 486     </p>
 487 <p>
 488       Analogously, the global <code class="computeroutput"><span class="keyword">operator</span><span class="special">&gt;&gt;</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">&gt;&gt;</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">&lt;</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">&gt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&lt;&lt;</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">&gt;&gt;</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">&lt;</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">&gt;</span> <span class="identifier">i</span><span class="special">;</span>
 542 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">j</span><span class="special">;</span>
 543
 544 <span class="identifier">cin</span> <span class="special">&gt;&gt;</span> <span class="identifier">i</span><span class="special">;</span>
 545 <span class="identifier">cin</span> <span class="special">&gt;&gt;</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">&gt;&gt;</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">&gt;&gt;</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">&gt;&gt;</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">&amp;</span> <span class="identifier">aa</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">B</span><span class="special">&amp;</span> <span class="identifier">bb</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">C</span><span class="special">&amp;</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">&amp;</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">&amp;</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">&amp;</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">&lt;</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">&gt;</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">&lt;</span><span class="number">0</span><span class="special">&gt;();</span> <span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span><span class="number">1</span><span class="special">&gt;();</span> <span class="identifier">t</span><span class="special">.</span><span class="identifier">get</span><span class="special">&lt;</span><span class="number">2</span><span class="special">&gt;();</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">&amp;,</span> <span class="keyword">double</span><span class="special">&amp;);</span>
 599 <span class="identifier">tuple</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">double</span><span class="special">&gt;</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&#228;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&#228;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&#228;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: December 10, 2019 at 00:21:48 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>