generic-library/boost
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
boost/libs/tuple/doc/html/tuple_advanced_interface.html
Edouard DUPIN d0115b733d [DEV] add v1.76.0
2021-10-05 21:37:46 +02:00

266 lines
20 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Tuple library advanced features</title>
<link rel="stylesheet" href="../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="tuple_users_guide.html" title="Chapter 1. Boost.Tuple">
<link rel="up" href="tuple_users_guide.html" title="Chapter 1. Boost.Tuple">
<link rel="prev" href="tuple_users_guide.html" title="Chapter 1. Boost.Tuple">
<link rel="next" href="design_decisions_rationale.html" title="Design decisions rationale">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../boost.png"></td>
<td align="center"><a href="../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="tuple_users_guide.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tuple_users_guide.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="tuple_users_guide.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_decisions_rationale.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="article">
<div class="titlepage">
<div>
<div><h2 class="title">
<a name="tuple_advanced_interface"></a>Tuple library advanced features</h2></div>
<div><p class="copyright">Copyright © 2001 Jaakko Järvi</p></div>
<div><div class="legalnotice">
<a name="tuple_advanced_interface.legal"></a><p>
Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost
Software License, Version 1.0</a>.
</p>
</div></div>
</div>
<hr>
</div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl class="toc">
<dt><span class="section"><a href="tuple_advanced_interface.html#tuple_advanced_interface.metafunctions_for_tuple_types">Metafunctions
for tuple types</a></span></dt>
<dt><span class="section"><a href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists">Cons lists</a></span></dt>
<dt><span class="section"><a href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element">Traits
classes for tuple element types</a></span></dt>
</dl>
</div>
<p>
The advanced features described in this document are all under namespace <code class="computeroutput"><span class="special">::</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">tuples</span></code>
</p>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="tuple_advanced_interface.metafunctions_for_tuple_types"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.metafunctions_for_tuple_types" title="Metafunctions for tuple types">Metafunctions
for tuple types</a>
</h3></div></div></div>
<p>
Suppose <code class="computeroutput"><span class="identifier">T</span></code> is a tuple type,
and <code class="computeroutput"><span class="identifier">N</span></code> is a constant integral
expression.
</p>
<pre class="programlisting"><span class="identifier">element</span><span class="special">&lt;</span><span class="identifier">N</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span>
</pre>
<p>
gives the type of the <code class="computeroutput"><span class="identifier">N</span></code>-th
element in the tuple type <code class="computeroutput"><span class="identifier">T</span></code>.
If <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="keyword">const</span></code>,
the resulting type is <code class="computeroutput"><span class="keyword">const</span></code>
qualified as well. Note that the constness of <code class="computeroutput"><span class="identifier">T</span></code>
does not affect reference type elements.
</p>
<pre class="programlisting"><span class="identifier">length</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">value</span>
</pre>
<p>
gives the length of the tuple type <code class="computeroutput"><span class="identifier">T</span></code>.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="tuple_advanced_interface.cons_lists"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists" title="Cons lists">Cons lists</a>
</h3></div></div></div>
<p>
Tuples are internally represented as <span class="emphasis"><em>cons lists</em></span>. For
example, the tuple
</p>
<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">,</span> <span class="identifier">D</span><span class="special">&gt;</span>
</pre>
<p>
inherits from the type
</p>
<pre class="programlisting"><span class="identifier">cons</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span> <span class="identifier">cons</span><span class="special">&lt;</span><span class="identifier">B</span><span class="special">,</span> <span class="identifier">cons</span><span class="special">&lt;</span><span class="identifier">C</span><span class="special">,</span> <span class="identifier">cons</span><span class="special">&lt;</span><span class="identifier">D</span><span class="special">,</span> <span class="identifier">null_type</span><span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span> <span class="special">&gt;</span>
</pre>
<p>
The tuple template provides the typedef inherited to access the cons list
representation. E.g.: <code class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">&gt;::</span><span class="identifier">inherited</span></code> is the type <code class="computeroutput"><span class="identifier">cons</span><span class="special">&lt;</span><span class="identifier">A</span><span class="special">,</span>
<span class="identifier">null_type</span><span class="special">&gt;</span></code>.
</p>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="tuple_advanced_interface.cons_lists.empty_tuple"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists.empty_tuple" title="Empty tuple">Empty
tuple</a>
</h4></div></div></div>
<p>
The internal representation of the empty tuple <code class="computeroutput"><span class="identifier">tuple</span><span class="special">&lt;&gt;</span></code> is <code class="computeroutput"><span class="identifier">null_type</span></code>.
</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="tuple_advanced_interface.cons_lists.head_and_tail"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists.head_and_tail" title="Head and tail">Head
and tail</a>
</h4></div></div></div>
<p>
Both tuple template and the cons templates provide the typedefs <code class="computeroutput"><span class="identifier">head_type</span></code> and <code class="computeroutput"><span class="identifier">tail_type</span></code>.
The <code class="computeroutput"><span class="identifier">head_type</span></code> typedef gives
the type of the first element of the tuple (or the cons list). The <code class="computeroutput"><span class="identifier">tail_type</span></code> typedef gives the remaining
cons list after removing the first element. The head element is stored
in the member variable <code class="computeroutput"><span class="identifier">head</span></code>
and the tail list in the member variable <code class="computeroutput"><span class="identifier">tail</span></code>.
Cons lists provide the member function <code class="computeroutput"><span class="identifier">get_head</span><span class="special">()</span></code> for getting a reference to the head of
a cons list, and <code class="computeroutput"><span class="identifier">get_tail</span><span class="special">()</span></code> for getting a reference to the tail.
There are const and non-const versions of both functions.
</p>
<p>
Note that in a one element tuple, <code class="computeroutput"><span class="identifier">tail_type</span></code>
equals <code class="computeroutput"><span class="identifier">null_type</span></code> and the
<code class="computeroutput"><span class="identifier">get_tail</span><span class="special">()</span></code>
function returns an object of type <code class="computeroutput"><span class="identifier">null_type</span></code>.
</p>
<p>
The empty tuple (<code class="computeroutput"><span class="identifier">null_type</span></code>)
has no head or tail, hence the <code class="computeroutput"><span class="identifier">get_head</span></code>
and <code class="computeroutput"><span class="identifier">get_tail</span></code> functions
are not provided.
</p>
<p>
Treating tuples as cons lists gives a convenient means to define generic
functions to manipulate tuples. For example, the following pair of function
templates assign <code class="computeroutput"><span class="number">0</span></code> to each
element of a tuple (obviously, the assignments must be valid operations
for the element types):
</p>
<pre class="programlisting"><span class="keyword">inline</span> <span class="keyword">void</span> <span class="identifier">set_to_zero</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">null_type</span><span class="special">&amp;)</span> <span class="special">{};</span>
<span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">H</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">T</span><span class="special">&gt;</span>
<span class="keyword">inline</span> <span class="keyword">void</span> <span class="identifier">set_to_zero</span><span class="special">(</span><span class="identifier">cons</span><span class="special">&lt;</span><span class="identifier">H</span><span class="special">,</span> <span class="identifier">T</span><span class="special">&gt;&amp;</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">{</span> <span class="identifier">x</span><span class="special">.</span><span class="identifier">get_head</span><span class="special">()</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="identifier">set_to_zero</span><span class="special">(</span><span class="identifier">x</span><span class="special">.</span><span class="identifier">get_tail</span><span class="special">());</span> <span class="special">}</span>
</pre>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="tuple_advanced_interface.cons_lists.constructing_cons_lists"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.cons_lists.constructing_cons_lists" title="Constructing cons lists">Constructing
cons lists</a>
</h4></div></div></div>
<p>
A cons list can be default constructed provided that all its elements can
be default constructed.
</p>
<p>
A cons list can be constructed from its head and tail. The prototype of
the constructor is:
</p>
<pre class="programlisting"><span class="identifier">cons</span><span class="special">(</span><span class="keyword">typename</span> <span class="identifier">access_traits</span><span class="special">&lt;</span><span class="identifier">head_type</span><span class="special">&gt;::</span><span class="identifier">parameter_type</span> <span class="identifier">h</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">tail_type</span><span class="special">&amp;</span> <span class="identifier">t</span><span class="special">)</span>
</pre>
<p>
The traits template for the head parameter selects correct parameter types
for different kinds of element types (for reference elements the parameter
type equals the element type, for non-reference types the parameter type
is a reference to const non-volatile element type).
</p>
<p>
For a one-element cons list the tail argument (<code class="computeroutput"><span class="identifier">null_type</span></code>)
can be omitted.
</p>
</div>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="tuple_advanced_interface.traits_classes_for_tuple_element"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element" title="Traits classes for tuple element types">Traits
classes for tuple element types</a>
</h3></div></div></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="tuple_advanced_interface.traits_classes_for_tuple_element.access_traits"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element.access_traits" title="access_traits">access_traits</a>
</h4></div></div></div>
<p>
The template <code class="computeroutput"><span class="identifier">access_traits</span></code>
defines three type functions. Let <code class="computeroutput"><span class="identifier">T</span></code>
be a type of an element in a tuple:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<code class="computeroutput"><span class="identifier">access_traits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">non_const_type</span></code> maps <code class="computeroutput"><span class="identifier">T</span></code> to the return type of the no n-const
access functions (nonmember and member <code class="computeroutput"><span class="identifier">get</span></code>
functions, and the <code class="computeroutput"><span class="identifier">get_head</span></code>
function).
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">access_traits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">const_type</span></code> maps <code class="computeroutput"><span class="identifier">T</span></code>
to the return type of the const access functions.
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">access_traits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">parameter_type</span></code> maps <code class="computeroutput"><span class="identifier">T</span></code> to the parameter type of the tuple
constructor.
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="tuple_advanced_interface.traits_classes_for_tuple_element.make_tuple_traits"></a><a class="link" href="tuple_advanced_interface.html#tuple_advanced_interface.traits_classes_for_tuple_element.make_tuple_traits" title="make_tuple_traits">make_tuple_traits</a>
</h4></div></div></div>
<p>
The element types of the tuples that are created with the <code class="computeroutput"><span class="identifier">make_tuple</span></code> functions are computed with
the type function <code class="computeroutput"><span class="identifier">make_tuple_traits</span></code>.
The type function call <code class="computeroutput"><span class="identifier">make_tuple_traits</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;::</span><span class="identifier">type</span></code>
implements the following type mapping:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
<span class="emphasis"><em>any reference type</em></span> -&gt; <span class="emphasis"><em>compile time
error</em></span>
</li>
<li class="listitem">
<span class="emphasis"><em>any array type</em></span> -&gt; <span class="emphasis"><em>constant reference
to the array type</em></span>
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">reference_wrapper</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
-&gt; <code class="computeroutput"><span class="identifier">T</span><span class="special">&amp;</span></code>
</li>
<li class="listitem">
<code class="computeroutput"><span class="identifier">T</span></code> -&gt; <code class="computeroutput"><span class="identifier">T</span></code>
</li>
</ul></div>
<p>
Objects of type <code class="computeroutput"><span class="identifier">reference_wrapper</span></code>
are created with the <code class="computeroutput"><span class="identifier">ref</span></code>
and <code class="computeroutput"><span class="identifier">cref</span></code> functions (see
<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>).
</p>
<p>
Reference wrappers were originally part of the tuple library, but they
are now a general utility of boost. The <code class="computeroutput"><span class="identifier">reference_wrapper</span></code>
template and the <code class="computeroutput"><span class="identifier">ref</span></code> and
<code class="computeroutput"><span class="identifier">cref</span></code> functions are defined
in a separate file <a href="../../../../libs/core/doc/html/core/ref.html" target="_top"><code class="computeroutput"><span class="identifier">ref</span><span class="special">.</span><span class="identifier">hpp</span></code></a> in the main boost include
directory; and directly in the <code class="computeroutput"><span class="identifier">boost</span></code>
namespace.
</p>
</div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"><p><small>Last revised: April 13, 2021 at 16:25:09 GMT</small></p></td>
<td align="right"><div class="copyright-footer">Copyright © 2001 Jaakko Järvi<p>
Distributed under the <a href="http://boost.org/LICENSE_1_0.txt" target="_top">Boost
Software License, Version 1.0</a>.
</p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="tuple_users_guide.html"><img src="../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="tuple_users_guide.html"><img src="../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="tuple_users_guide.html"><img src="../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="design_decisions_rationale.html"><img src="../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink