[ceph.git] / ceph / src / boost / libs / tuple / doc / tuple_advanced_interface.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title>Tuple library advanced features</title>
  </head>

<body bgcolor="#FFFFFF" text="#000000">

<IMG SRC="../../../boost.png" 
     ALT="C++ Boost" width="277" height="86">

    <h1>Tuple library advanced features</h1>

The advanced features described in this document are all under namespace <code>::boost::tuples</code>

<h2>Metafunctions for tuple types</h2>
<p>
Suppose <code>T</code> is a tuple type, and <code>N</code> is a constant integral expression.</p>

<pre><code>element&lt;N, T&gt;::type</code></pre>

<p>gives the type of the <code>N</code>th element in the tuple type <code>T</code>. If <code>T</code> is const, the resulting type is const qualified as well. 
Note that the constness of <code>T</code> does not affect reference type
elements.
</p>

<pre><code>length&lt;T&gt;::value</code></pre>

<p>gives the length of the tuple type <code>T</code>.
</p>

<h2>Cons lists</h2>

<p>
Tuples are internally represented as <i>cons lists</i>.
For example, the tuple </p>

<pre><code>tuple&lt;A, B, C, D&gt;</code></pre>

<p>inherits from the type</p>
<pre><code>cons&lt;A, cons&lt;B, cons&lt;C, cons&lt;D, null_type&gt; &gt; &gt; &gt;
</code></pre>

<p>The tuple template provides the typedef <code>inherited</code> to access the cons list representation. E.g.:
<code>tuple&lt;A&gt;::inherited</code> is the type <code>cons&lt;A, null_type&gt;</code>.
</p>

<h4>Empty tuple</h4>
<p>
The internal representation of the empty tuple <code>tuple&lt;&gt;</code> is <code>null_type</code>.
</p>

<h4>Head and tail</h4>
<p>
Both tuple template and the cons templates provide the typedefs <code>head_type</code> and <code>tail_type</code>.
The <code>head_type</code> typedef gives the type of the first element of the tuple (or the cons list).
The 
<code>tail_type</code> typedef gives the remaining cons list after removing the first element.
The head element is stored in the member variable <code>head</code> and the tail list in the member variable <code>tail</code>.
Cons lists provide the member function <code>get_head()</code> for getting a reference to the head of a cons list, and <code>get_tail()</code> for getting a reference to the tail.
There are const and non-const versions of both functions.
</p>
<p>
Note that in a one element tuple, <code>tail_type</code> equals <code>null_type</code> and the <code>get_tail()</code> function returns an object of type <code>null_type</code>.
</p>
<p>
The empty tuple (<code>null_type</code>) has no head or tail, hence the <code>get_head</code> and <code>get_tail</code> functions are not provided.
</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 0 to each element of a tuple (obviously, the assignments must be valid operations for the element types):

<pre><code>inline void set_to_zero(const null_type&amp;) {};

template &lt;class H, class T&gt;
inline void set_to_zero(cons&lt;H, T&gt;&amp; x) { x.get_head() = 0; set_to_zero(x.get_tail()); }
</code></pre>
<p>

<h4>Constructing cons lists</h4>

<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><code>cons(typename access_traits&lt;head_type&gt;::parameter_type h,
     const tail_type&amp; t)
</code></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>null_type</code>) can be omitted.
</p>


<h2>Traits classes for tuple element types</h2>

<h4><code>access_traits</code></h4>
<p>
The template <code>access_traits</code> defines three type functions. Let <code>T</code> be a type of an element in a tuple:</p>
<ol>
<li><code>access_traits&lt;T&gt;::non_const_type</code> maps <code>T</code> to the return type of the non-const access functions (nonmember and member <code>get</code> functions, and the <code>get_head</code> function).</li>
<li><code>access_traits&lt;T&gt;::const_type</code> maps <code>T</code> to the return type of the const access functions.</li>
<li><code>access_traits&lt;T&gt;::parameter_type</code> maps <code>T</code> to the parameter type of the tuple constructor.</li>
</ol>
<h4><code>make_tuple_traits</code></h4>

<p>The element types of the tuples that are created with the <code>make_tuple</code> functions are computed with the type function <code>make_tuple_traits</code>. 
The type function call <code>make_tuple_traits&lt;T&gt;::type</code> implements the following type mapping:</p>
<ul>
<li><i>any reference type</i> -&gt; <i>compile time error</i>
</li>
<li><i>any array type</i> -&gt; <i>constant reference to the array type</i>
</li>
<li><code>reference_wrapper&lt;T&gt;</code> -&gt; <code>T&amp;</code>
</li>
<li><code>T</code> -&gt; <code>T</code>
</li>
</ul>

<p>Objects of type <code>reference_wrapper</code> are created with the <code>ref</code> and <code>cref</code> functions (see <A href="tuple_users_guide.html#make_tuple">The <code>make_tuple</code> function</A>.)
</p>

<p>Reference wrappers were originally part of the tuple library, but they are now a general utility of boost. 
The <code>reference_wrapper</code> template and the <code>ref</code> and <code>cref</code> functions are defined in a separate file <code>ref.hpp</code> in the main boost include directory; and directly in the <code>boost</code> namespace.
</p>

<A href="tuple_users_guide.html">Back to the user's guide</A>
<hr>

<p>&copy; Copyright Jaakko J&auml;rvi 2001.</p>
  </body>
</html>
Commit	Line	Data
7c673cae FG	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	2	<html>
	3	<head>
	4	<title>Tuple library advanced features</title>
	5	</head>
	6
	7	<body bgcolor="#FFFFFF" text="#000000">
	8
	9	<IMG SRC="../../../boost.png"
	10	ALT="C++ Boost" width="277" height="86">
	11
	12	<h1>Tuple library advanced features</h1>
	13
	14	The advanced features described in this document are all under namespace <code>::boost::tuples</code>
	15
	16	<h2>Metafunctions for tuple types</h2>
	17	<p>
	18	Suppose <code>T</code> is a tuple type, and <code>N</code> is a constant integral expression.</p>
	19
	20	<pre><code>element<N, T>::type</code></pre>
	21
	22	<p>gives the type of the <code>N</code>th element in the tuple type <code>T</code>. If <code>T</code> is const, the resulting type is const qualified as well.
	23	Note that the constness of <code>T</code> does not affect reference type
	24	elements.
	25	</p>
	26
	27	<pre><code>length<T>::value</code></pre>
	28
	29	<p>gives the length of the tuple type <code>T</code>.
	30	</p>
	31
	32	<h2>Cons lists</h2>
	33
	34	<p>
	35	Tuples are internally represented as <i>cons lists</i>.
	36	For example, the tuple </p>
	37
	38	<pre><code>tuple<A, B, C, D></code></pre>
	39
	40	<p>inherits from the type</p>
	41	<pre><code>cons<A, cons<B, cons<C, cons<D, null_type> > > >
	42	</code></pre>
	43
	44	<p>The tuple template provides the typedef <code>inherited</code> to access the cons list representation. E.g.:
	45	<code>tuple<A>::inherited</code> is the type <code>cons<A, null_type></code>.
	46	</p>
	47
	48	<h4>Empty tuple</h4>
	49	<p>
	50	The internal representation of the empty tuple <code>tuple<></code> is <code>null_type</code>.
	51	</p>
	52
	53	<h4>Head and tail</h4>
	54	<p>
	55	Both tuple template and the cons templates provide the typedefs <code>head_type</code> and <code>tail_type</code>.
	56	The <code>head_type</code> typedef gives the type of the first element of the tuple (or the cons list).
	57	The
	58	<code>tail_type</code> typedef gives the remaining cons list after removing the first element.
	59	The head element is stored in the member variable <code>head</code> and the tail list in the member variable <code>tail</code>.
	60	Cons lists provide the member function <code>get_head()</code> for getting a reference to the head of a cons list, and <code>get_tail()</code> for getting a reference to the tail.
	61	There are const and non-const versions of both functions.
	62	</p>
	63	<p>
	64	Note that in a one element tuple, <code>tail_type</code> equals <code>null_type</code> and the <code>get_tail()</code> function returns an object of type <code>null_type</code>.
65	</p>
66	<p>
67	The empty tuple (<code>null_type</code>) has no head or tail, hence the <code>get_head</code> and <code>get_tail</code> functions are not provided.
68	</p>
69
70	<p>
71	Treating tuples as cons lists gives a convenient means to define generic functions to manipulate tuples. For example, the following pair of function templates assign 0 to each element of a tuple (obviously, the assignments must be valid operations for the element types):
72
73	<pre><code>inline void set_to_zero(const null_type&) {};
74
75	template <class H, class T>
76	inline void set_to_zero(cons<H, T>& x) { x.get_head() = 0; set_to_zero(x.get_tail()); }
77	</code></pre>
78	<p>
79
80	<h4>Constructing cons lists</h4>
81
82	<p>
83	A cons list can be default constructed provided that all its elements can be default constructed.
84	</p>
85	<p>
86	A cons list can be constructed from its head and tail. The prototype of the constructor is:</p>
87	<pre><code>cons(typename access_traits<head_type>::parameter_type h,
88	const tail_type& t)
89	</code></pre>
90	<p>The traits template for the head parameter selects correct parameter types for different kinds of element types (for reference elements the parameter type equals the element type, for non-reference types the parameter type is a reference to const non-volatile element type).
91	</p>
92	<p>
93	For a one-element cons list the tail argument (<code>null_type</code>) can be omitted.
94	</p>
95
96
97	<h2>Traits classes for tuple element types</h2>
98
99	<h4><code>access_traits</code></h4>
100	<p>
101	The template <code>access_traits</code> defines three type functions. Let <code>T</code> be a type of an element in a tuple:</p>
102	<ol>
103	<li><code>access_traits<T>::non_const_type</code> maps <code>T</code> to the return type of the non-const access functions (nonmember and member <code>get</code> functions, and the <code>get_head</code> function).</li>
104	<li><code>access_traits<T>::const_type</code> maps <code>T</code> to the return type of the const access functions.</li>
105	<li><code>access_traits<T>::parameter_type</code> maps <code>T</code> to the parameter type of the tuple constructor.</li>
106	</ol>
107	<h4><code>make_tuple_traits</code></h4>
108
109	<p>The element types of the tuples that are created with the <code>make_tuple</code> functions are computed with the type function <code>make_tuple_traits</code>.
110	The type function call <code>make_tuple_traits<T>::type</code> implements the following type mapping:</p>
111	<ul>
112	<li><i>any reference type</i> -> <i>compile time error</i>
113	</li>
114	<li><i>any array type</i> -> <i>constant reference to the array type</i>
115	</li>
116	<li><code>reference_wrapper<T></code> -> <code>T&</code>
117	</li>
118	<li><code>T</code> -> <code>T</code>
119	</li>
120	</ul>
121
122	<p>Objects of type <code>reference_wrapper</code> are created with the <code>ref</code> and <code>cref</code> functions (see <A href="tuple_users_guide.html#make_tuple">The <code>make_tuple</code> function</A>.)
123	</p>
124
125	<p>Reference wrappers were originally part of the tuple library, but they are now a general utility of boost.
126	The <code>reference_wrapper</code> template and the <code>ref</code> and <code>cref</code> functions are defined in a separate file <code>ref.hpp</code> in the main boost include directory; and directly in the <code>boost</code> namespace.
127	</p>
128
129	<A href="tuple_users_guide.html">Back to the user's guide</A>
130	<hr>
131
132	<p>© Copyright Jaakko Järvi 2001.</p>
133	</body>
134	</html>