1[/============================================================================== 2 Copyright (C) 2001-2011 Joel de Guzman 3 Copyright (C) 2006 Dan Marsden 4 5 Use, modification and distribution is subject to the Boost Software 6 License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at 7 http://www.boost.org/LICENSE_1_0.txt) 8===============================================================================/] 9[section Tuple] 10 11The TR1 technical report describes extensions to the C++ standard library. 12Many of these extensions will be considered for the next 13iteration of the C++ standard. TR1 describes a tuple type, and 14support for treating `std::pair` as a type of tuple. 15 16Fusion provides full support for the __tr1__tuple__ interface, and the extended 17uses of `std::pair` described in the TR1 document. 18 19[section Class template tuple] 20Fusion's implementation of the __tr1__tuple__ is also a fusion __forward_sequence__. 21As such the fusion tuple type provides a lot of functionality beyond that required by TR1. 22 23Currently tuple is basically a synonym for __vector__, although this may be changed 24in future releases of fusion. 25 26[heading Header] 27 28 #include <boost/fusion/tuple.hpp> 29 #include <boost/fusion/include/tuple.hpp> 30 31 #include <boost/fusion/tuple/tuple.hpp> 32 #include <boost/fusion/tuple/tuple_fwd.hpp> 33 #include <boost/fusion/include/tuple_fwd.hpp> 34 35 // for creation function 36 #include <boost/fusion/tuple/tuple_tie.hpp> 37 #include <boost/fusion/include/tuple_tie.hpp> 38 #include <boost/fusion/tuple/make_tuple.hpp> 39 #include <boost/fusion/include/make_tuple.hpp> 40 41[heading Synopsis] 42 template< 43 typename T1 = __unspecified__, 44 typename T2 = __unspecified__, 45 ... 46 typename TN = __unspecified__> 47 class tuple; 48 49[section Construction] 50 51[heading Description] 52The __tr1__tuple__ type provides a default constructor, a constructor that takes initializers for all of its elements, a copy constructor, and a converting copy constructor. The details of the various constructors are described in this section. 53 54[heading Specification] 55 56[variablelist Notation 57 [[`T1 ... TN`, `U1 ... UN`][Tuple element types]] 58 [[`P1 ... PN`] [Parameter types]] 59 [[`Ti`, `Ui`] [The type of the `i`th element of a tuple]] 60 [[`Pi`] [The type of the `i`th parameter]] 61] 62 63 tuple(); 64 65[*Requirements]: Each `Ti` is default-constructible. 66 67[*Semantics]: Default initializes each element of the tuple. 68 69 tuple(P1,P2,...,PN); 70 71[*Requirements]: Each `Pi` is `Ti` if `Ti` is a reference type, `const Ti&` otherwise. 72 73[*Semantics]: Copy initializes each element with the corresponding parameter. 74 75 tuple(const tuple& t); 76 77[*Requirements]: Each `Ti` should be copy-constructible. 78 79[*Semantics]: Copy constructs each element of `*this` with the corresponding element of `t`. 80 81 template<typename U1, typename U2, ..., typename UN> 82 tuple(const tuple<U1, U2, ..., UN>& t); 83 84[*Requirements]: Each `Ti` shall be constructible from the corresponding `Ui`. 85 86[*Semantics]: Constructs each element of `*this` with the corresponding element of `t`. 87 88[endsect] 89 90[section Tuple creation functions] 91 92[heading Description] 93TR1 describes 2 utility functions for creating __tr1__tuple__. `make_tuple` builds a tuple out of it's argument list, and `tie` builds a tuple of references to it's arguments. The details of these creation functions are described in this section. 94 95[heading Specification] 96 97 template<typename T1, typename T2, ..., typename TN> 98 tuple<V1, V2, ..., VN> 99 make_tuple(const T1& t1, const T2& t2, ..., const TN& tn); 100 101Where `Vi` is `X&` if the cv-unqualified type `Ti` is `reference_wrapper<X>`, otherwise `Vi` is `Ti`. 102 103[*Returns]: `tuple<V1, V2, ..., VN>(t1, t2, ..., tN)` 104 105 template<typename T1, typename T2, ..., typename TN> 106 tuple<T1&, T2&, ..., TN&> 107 tie(T1& t1, T2& t2, ..., TN& tn); 108 109[*Returns]: tuple<T1&, T2&, ..., TN&>(t1, t2, ..., tN). When argument `ti` is `ignore`, assigning any value to the corresponding tuple element has no effect. 110 111[endsect] 112 113[section Tuple helper classes] 114 115[heading Description] 116The __tr1__tuple__ provides 2 helper traits, for compile time access to the tuple size, and the element types. 117 118[heading Specification] 119 120 tuple_size<T>::value 121 122[*Requires]: `T` is any fusion sequence type, including `tuple`. 123 124[*Type]: __mpl_integral_constant__ 125 126[*Value]: The number of elements in the sequence. Equivalent to `__result_of_size__<T>::type`. 127 128 tuple_element<I, T>::type 129 130[*Requires]: `T` is any fusion sequence type, including `tuple`. `0 <= I < N` or the program is ill formed. 131 132[*Value]: The type of the `I`th element of `T`. Equivalent to `__result_of_value_at__<I,T>::type`. 133 134[endsect] 135 136[section Element access] 137 138[heading Description] 139The __tr1__tuple__ provides the `get` function to provide access to it's elements by zero based numeric index. 140 141[heading Specification] 142 template<int I, T> 143 RJ get(T& t); 144 145[*Requires]: `0 < I <= N`. The program is ill formed if `I` is out of bounds. 146`T` is any fusion sequence type, including `tuple`. 147 148[*Return type]: `RJ` is equivalent to `__result_of_at_c__<I,T>::type`. 149 150[*Returns]: A reference to the `I`th element of `T`. 151 152 template<int I, typename T> 153 PJ get(T const& t); 154 155[*Requires]: `0 < I <= N`. The program is ill formed if `I` is out of bounds. 156`T` is any fusion sequence type, including `tuple`. 157 158[*Return type]: `PJ` is equivalent to `__result_of_at_c__<I,T>::type`. 159 160[*Returns]: A const reference to the `I`th element of `T`. 161 162[endsect] 163 164[section Relational operators] 165 166[heading Description] 167The __tr1__tuple__ provides the standard boolean relational operators. 168 169[heading Specification] 170 171[variablelist Notation 172 [[`T1 ... TN`, `U1 ... UN`][Tuple element types]] 173 [[`P1 ... PN`] [Parameter types]] 174 [[`Ti`, `Ui`] [The type of the `i`th element of a tuple]] 175 [[`Pi`] [The type of the `i`th parameter]] 176] 177 178 template<typename T1, typename T2, ..., typename TN, 179 typename U1, typename U2, ..., typename UN> 180 bool operator==( 181 const tuple<T1, T2, ..., TN>& lhs, 182 const tuple<U1, U2, ..., UN>& rhs); 183 184[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) == __tuple_get__<i>(rhs)` is a valid 185expression returning a type that is convertible to `bool`. 186 187[*Semantics]: Returns `true` if and only if `__tuple_get__<i>(lhs) == __tuple_get__<i>(rhs)` for all `i`. 188For any 2 zero length tuples `e` and `f`, `e == f` returns `true`. 189 190 template<typename T1, typename T2, ..., typename TN, 191 typename U1, typename U2, ..., typename UN> 192 bool operator<( 193 const tuple<T1, T2, ..., TN>& lhs, 194 const tuple<U1, U2, ..., UN>& rhs); 195 196[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) < __tuple_get__<i>(rhs)` is a valid 197expression returning a type that is convertible to `bool`. 198 199[*Semantics]: Returns the lexicographical comparison of between `lhs` and `rhs`. 200 201 template<typename T1, typename T2, ..., typename TN, 202 typename U1, typename U2, ..., typename UN> 203 bool operator!=( 204 const tuple<T1, T2, ..., TN>& lhs, 205 const tuple<U1, U2, ..., UN>& rhs); 206 207[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) == __tuple_get__<i>(rhs)` is a valid 208expression returning a type that is convertible to `bool`. 209 210[*Semantics]: Returns `!(lhs == rhs)`. 211 212 template<typename T1, typename T2, ..., typename TN, 213 typename U1, typename U2, ..., typename UN> 214 bool operator<=( 215 const tuple<T1, T2, ..., TN>& lhs, 216 const tuple<U1, U2, ..., UN>& rhs); 217 218[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(rhs) < __tuple_get__<i>(lhs)` is a valid 219expression returning a type that is convertible to `bool`. 220 221[*Semantics]: Returns `!(rhs < lhs)` 222 223 template<typename T1, typename T2, ..., typename TN, 224 typename U1, typename U2, ..., typename UN> 225 bool operator>( 226 const tuple<T1, T2, ..., TN>& lhs, 227 const tuple<U1, U2, ..., UN>& rhs); 228 229[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(rhs) < __tuple_get__<i>(lhs)` is a valid 230expression returning a type that is convertible to `bool`. 231 232[*Semantics]: Returns `rhs < lhs`. 233 234 template<typename T1, typename T2, ..., typename TN, 235 typename U1, typename U2, ..., typename UN> 236 bool operator>=( 237 const tuple<T1, T2, ..., TN>& lhs, 238 const tuple<U1, U2, ..., UN>& rhs); 239 240[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) < __tuple_get__<i>(rhs)` is a valid 241expression returning a type that is convertible to `bool`. 242 243[*Semantics]: Returns `!(lhs < rhs)`. 244 245[endsect] 246 247[endsect] 248 249[section Pairs] 250 251[heading Description] 252The __tr1__tuple__ interface is specified to provide uniform access to `std::pair` as if it were a 2 element tuple. 253 254[heading Specification] 255 256 tuple_size<std::pair<T1, T2> >::value 257 258[*Type]: An __mpl_integral_constant__ 259 260[*Value]: Returns 2, the number of elements in a pair. 261 262 tuple_element<0, std::pair<T1, T2> >::type 263 264[*Type]: `T1` 265 266[*Value]: Returns the type of the first element of the pair 267 268 tuple_element<1, std::pair<T1, T2> >::type 269 270[*Type]: `T2` 271 272[*Value]: Returns the type of the second element of the pair 273 274 template<int I, typename T1, typename T2> 275 P& get(std::pair<T1, T2>& pr); 276 277 template<int I, typename T1, typename T2> 278 const P& get(const std::pair<T1, T2>& pr); 279 280[*Type]: If `I == 0` `P` is `T1`, else if `I == 1` `P` is `T2` else the program is ill-formed. 281 282[*Returns: `pr.first` if `I == 0` else `pr.second`. 283 284[endsect] 285 286[endsect] 287 288