[/============================================================================== Copyright (C) 2001-2011 Joel de Guzman Copyright (C) 2006 Dan Marsden Use, modification and distribution is subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) ===============================================================================/] [section Tuple] The TR1 technical report describes extensions to the C++ standard library. Many of these extensions will be considered for the next iteration of the C++ standard. TR1 describes a tuple type, and support for treating `std::pair` as a type of tuple. Fusion provides full support for the __tr1__tuple__ interface, and the extended uses of `std::pair` described in the TR1 document. [section Class template tuple] Fusion's implementation of the __tr1__tuple__ is also a fusion __forward_sequence__. As such the fusion tuple type provides a lot of functionality beyond that required by TR1. Currently tuple is basically a synonym for __vector__, although this may be changed in future releases of fusion. [heading Header] #include #include #include #include #include // for creation function #include #include #include #include [heading Synopsis] template< typename T1 = __unspecified__, typename T2 = __unspecified__, ... typename TN = __unspecified__> class tuple; [section Construction] [heading Description] The __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. [heading Specification] [variablelist Notation [[`T1 ... TN`, `U1 ... UN`][Tuple element types]] [[`P1 ... PN`] [Parameter types]] [[`Ti`, `Ui`] [The type of the `i`th element of a tuple]] [[`Pi`] [The type of the `i`th parameter]] ] tuple(); [*Requirements]: Each `Ti` is default-constructible. [*Semantics]: Default initializes each element of the tuple. tuple(P1,P2,...,PN); [*Requirements]: Each `Pi` is `Ti` if `Ti` is a reference type, `const Ti&` otherwise. [*Semantics]: Copy initializes each element with the corresponding parameter. tuple(const tuple& t); [*Requirements]: Each `Ti` should be copy-constructible. [*Semantics]: Copy constructs each element of `*this` with the corresponding element of `t`. template tuple(const tuple& t); [*Requirements]: Each `Ti` shall be constructible from the corresponding `Ui`. [*Semantics]: Constructs each element of `*this` with the corresponding element of `t`. [endsect] [section Tuple creation functions] [heading Description] TR1 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. [heading Specification] template tuple make_tuple(const T1& t1, const T2& t2, ..., const TN& tn); Where `Vi` is `X&` if the cv-unqualified type `Ti` is `reference_wrapper`, otherwise `Vi` is `Ti`. [*Returns]: `tuple(t1, t2, ..., tN)` template tuple tie(T1& t1, T2& t2, ..., TN& tn); [*Returns]: tuple(t1, t2, ..., tN). When argument `ti` is `ignore`, assigning any value to the corresponding tuple element has no effect. [endsect] [section Tuple helper classes] [heading Description] The __tr1__tuple__ provides 2 helper traits, for compile time access to the tuple size, and the element types. [heading Specification] tuple_size::value [*Requires]: `T` is any fusion sequence type, including `tuple`. [*Type]: __mpl_integral_constant__ [*Value]: The number of elements in the sequence. Equivalent to `__result_of_size__::type`. tuple_element::type [*Requires]: `T` is any fusion sequence type, including `tuple`. `0 <= I < N` or the program is ill formed. [*Value]: The type of the `I`th element of `T`. Equivalent to `__result_of_value_at__::type`. [endsect] [section Element access] [heading Description] The __tr1__tuple__ provides the `get` function to provide access to it's elements by zero based numeric index. [heading Specification] template RJ get(T& t); [*Requires]: `0 < I <= N`. The program is ill formed if `I` is out of bounds. `T` is any fusion sequence type, including `tuple`. [*Return type]: `RJ` is equivalent to `__result_of_at_c__::type`. [*Returns]: A reference to the `I`th element of `T`. template PJ get(T const& t); [*Requires]: `0 < I <= N`. The program is ill formed if `I` is out of bounds. `T` is any fusion sequence type, including `tuple`. [*Return type]: `PJ` is equivalent to `__result_of_at_c__::type`. [*Returns]: A const reference to the `I`th element of `T`. [endsect] [section Relational operators] [heading Description] The __tr1__tuple__ provides the standard boolean relational operators. [heading Specification] [variablelist Notation [[`T1 ... TN`, `U1 ... UN`][Tuple element types]] [[`P1 ... PN`] [Parameter types]] [[`Ti`, `Ui`] [The type of the `i`th element of a tuple]] [[`Pi`] [The type of the `i`th parameter]] ] template bool operator==( const tuple& lhs, const tuple& rhs); [*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__(lhs) == __tuple_get__(rhs)` is a valid expression returning a type that is convertible to `bool`. [*Semantics]: Returns `true` if and only if `__tuple_get__(lhs) == __tuple_get__(rhs)` for all `i`. For any 2 zero length tuples `e` and `f`, `e == f` returns `true`. template bool operator<( const tuple& lhs, const tuple& rhs); [*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__(lhs) < __tuple_get__(rhs)` is a valid expression returning a type that is convertible to `bool`. [*Semantics]: Returns the lexicographical comparison of between `lhs` and `rhs`. template bool operator!=( const tuple& lhs, const tuple& rhs); [*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__(lhs) == __tuple_get__(rhs)` is a valid expression returning a type that is convertible to `bool`. [*Semantics]: Returns `!(lhs == rhs)`. template bool operator<=( const tuple& lhs, const tuple& rhs); [*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__(rhs) < __tuple_get__(lhs)` is a valid expression returning a type that is convertible to `bool`. [*Semantics]: Returns `!(rhs < lhs)` template bool operator>( const tuple& lhs, const tuple& rhs); [*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__(rhs) < __tuple_get__(lhs)` is a valid expression returning a type that is convertible to `bool`. [*Semantics]: Returns `rhs < lhs`. template bool operator>=( const tuple& lhs, const tuple& rhs); [*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__(lhs) < __tuple_get__(rhs)` is a valid expression returning a type that is convertible to `bool`. [*Semantics]: Returns `!(lhs < rhs)`. [endsect] [endsect] [section Pairs] [heading Description] The __tr1__tuple__ interface is specified to provide uniform access to `std::pair` as if it were a 2 element tuple. [heading Specification] tuple_size >::value [*Type]: An __mpl_integral_constant__ [*Value]: Returns 2, the number of elements in a pair. tuple_element<0, std::pair >::type [*Type]: `T1` [*Value]: Returns the type of the first element of the pair tuple_element<1, std::pair >::type [*Type]: `T2` [*Value]: Returns the type of the second element of the pair template P& get(std::pair& pr); template const P& get(const std::pair& pr); [*Type]: If `I == 0` `P` is `T1`, else if `I == 1` `P` is `T2` else the program is ill-formed. [*Returns: `pr.first` if `I == 0` else `pr.second`. [endsect] [endsect]