1[/ 2 / Copyright (c) 2001 Jaakko J�rvi 3 / 4 / Distributed under the Boost Software License, Version 1.0. (See 5 / accompanying file LICENSE_1_0.txt or copy at 6 / http://www.boost.org/LICENSE_1_0.txt) 7 /] 8 9[article Tuple library advanced features 10 [quickbook 1.6] 11 [id tuple_advanced_interface] 12 [copyright 2001 Jaakko J\u00E4rvi] 13 [license Distributed under the 14 [@http://boost.org/LICENSE_1_0.txt Boost Software License, 15 Version 1.0]. 16 ] 17] 18 19[template simplesect[title] 20[block '''<simplesect><title>'''[title]'''</title>''']] 21 22[template endsimplesect[] 23[block '''</simplesect>''']] 24 25The advanced features described in this document are all under namespace 26`::boost::tuples` 27 28[section Metafunctions for tuple types] 29 30Suppose `T` is a tuple type, and `N` is a constant integral expression. 31 32 element<N, T>::type 33 34gives the type of the `N`-th element in the tuple type `T`. If `T` is `const`, 35the resulting type is `const` qualified as well. Note that the constness of `T` 36does not affect reference type elements. 37 38 length<T>::value 39 40gives the length of the tuple type `T`. 41 42[endsect] 43 44[section Cons lists] 45 46Tuples are internally represented as /cons lists/. For example, the tuple 47 48 tuple<A, B, C, D> 49 50inherits from the type 51 52 cons<A, cons<B, cons<C, cons<D, null_type> > > > 53 54The tuple template provides the typedef inherited to access the cons list 55representation. E.g.: `tuple<A>::inherited` is the type `cons<A, null_type>`. 56 57[section Empty tuple] 58 59The internal representation of the empty tuple `tuple<>` is `null_type`. 60 61[endsect] 62 63[section Head and tail] 64 65Both tuple template and the cons templates provide the typedefs `head_type` 66and `tail_type`. The `head_type` typedef gives the type of the first element 67of the tuple (or the cons list). The `tail_type` typedef gives the remaining 68cons list after removing the first element. The head element is stored in the 69member variable `head` and the tail list in the member variable `tail`. Cons 70lists provide the member function `get_head()` for getting a reference to the 71head of a cons list, and `get_tail()` for getting a reference to the tail. 72There are const and non-const versions of both functions. 73 74Note that in a one element tuple, `tail_type` equals `null_type` and the 75`get_tail()` function returns an object of type `null_type`. 76 77The empty tuple (`null_type`) has no head or tail, hence the `get_head` and 78`get_tail` functions are not provided. 79 80Treating tuples as cons lists gives a convenient means to define generic 81functions to manipulate tuples. For example, the following pair of function 82templates assign `0` to each element of a tuple (obviously, the assignments 83must be valid operations for the element types): 84 85 inline void set_to_zero(const null_type&) {}; 86 87 template <class H, class T> 88 inline void set_to_zero(cons<H, T>& x) { x.get_head() = 0; set_to_zero(x.get_tail()); } 89 90[endsect] 91 92[section Constructing cons lists] 93 94A cons list can be default constructed provided that all its elements can be 95default constructed. 96 97A cons list can be constructed from its head and tail. The prototype of the 98constructor is: 99 100 cons(typename access_traits<head_type>::parameter_type h, const tail_type& t) 101 102The traits template for the head parameter selects correct parameter types for 103different kinds of element types (for reference elements the parameter type 104equals the element type, for non-reference types the parameter type is a 105reference to const non-volatile element type). 106 107For a one-element cons list the tail argument (`null_type`) can be omitted. 108 109[endsect] 110 111[endsect] 112 113[section Traits classes for tuple element types] 114 115[section access_traits] 116 117The template `access_traits` defines three type functions. Let `T` be a type 118of an element in a tuple: 119 120* `access_traits<T>::non_const_type` maps `T` to the return type of the no 121 n-const access functions (nonmember and member `get` functions, and the 122 `get_head` function). 123 124* `access_traits<T>::const_type` maps `T` to the return type of the const 125 access functions. 126 127* `access_traits<T>::parameter_type` maps `T` to the parameter type of the 128 tuple constructor. 129 130[endsect] 131 132[section make_tuple_traits] 133 134The element types of the tuples that are created with the `make_tuple` 135functions are computed with the type function `make_tuple_traits`. The type 136function call `make_tuple_traits<T>::type` implements the following type 137mapping: 138 139* /any reference type/ -> /compile time error/ 140 141* /any array type/ -> /constant reference to the array type/ 142 143* `reference_wrapper<T>` -> `T&` 144 145* `T` -> `T` 146 147Objects of type `reference_wrapper` are created with the `ref` and `cref` 148functions (see [link tuple.constructing_tuples.make_tuple The `make_tuple` 149function]). 150 151Reference wrappers were originally part of the tuple library, but they are now 152a general utility of boost. The `reference_wrapper` template and the `ref` and 153`cref` functions are defined in a separate file 154[@boost:/libs/core/doc/html/core/ref.html `ref.hpp`] in the main boost include 155directory; and directly in the `boost` namespace. 156 157[endsect] 158 159[endsect] 160