Beyond the C++ Standard Library: An Introduction to Boost [Electronic resources] نسخه متنی

Tuple

Header: "boost/tuple/tuple.hpp"

This includes the tuple class template and the core of the library.

Header: "boost/tuple/tuple_io.hpp"

includes input and output operations for tuples.

Header: "boost/tuple/tuple_comparison.hpp"

includes relational operators for tuples.

The Tuple library resides in a nested namespace within boost called boost::tuples. To use tuples, include "boost/tuple/tuple.hpp", which contains the core library. For input and output operations, include "boost/tuple/tuple_io.hpp", and to include support for tuple comparisons, include "boost/tuple/tuple_comparison.hpp". Some Boost libraries have a convenience header that includes all of the library; Boost.Tuple doesn't. The reason for separating the library into different headers is to reduce compile times; if you won't be using relational operators, you shouldn't need to pay for them in terms of time and dependencies. For convenience, some of the names from the Tuple library are present in namespace boost: tuple, make_tuple, tie, and get. The following is a partial synopsis for Boost.Tuple, showing and briefly discussing the most important functions.

namespace boost {
template <class T1,class T2,...,class TM> class tuple {
public:
tuple();
template <class P1,class P2...,class PM> 
tuple(class P1,class P2,...,PN); 
template <class U1,class U2,...,class UN>
tuple(const tuple<U1,U2,...,UN>&);
tuple& operator=(const tuple&);
};
template<class T1,class T2,...,class TN> tuple<V1,V2,...,VN> 
make_tuple(const T1& t1,const T2& t2,...,const TN& tn);
template<class T1,class T2,...,class TN> tuple<T1&,T2&,...,TN> 
tie(T1& t1,T2& t2,...,TN& tn);
template <int I,class T1,class T2,...,class TN> 
RI get(tuple<T1,T2,...,TN>& t);
template <int I,class T1,class T2,...,class TN> 
PI get(const tuple<T1,T2,...,TN>& t);
template <class T1,class T2,...,class TM,
class U1,class U2,...,class UM>
bool operator==(const tuple<T1,T2,...,TM>& t,
const tuple<U1,U2,...,UM>& u);
template <class T1,class T2,...,class TM,
class U1,class U2,...,class UM>
bool operator!=(const tuple<T1,T2,...,TM>& t,
const tuple<U1,U2,...,UM>& u);
template <class T1,class T2,...,class TN,
class U1,class U2,...,class UN>
bool operator<(const tuple<T1,T2,...,TN>&, 
const tuple<U1,U2,...,UN>&);
}

Members

tuple();

The default constructor of tuple initializes all elements, which implies that they must also be default constructiblethey must have a public default constructor. Any exceptions from the constructors of the contained elements are propagated.

template <class P1,class P2...,class PM> 
tuple(class P1,class P2,...,PN); 

This constructor accepts arguments that are used to initialize the corresponding elements of the tuple. For some tuple types, with non-default constructible types, this form of construction is a requirement; there's no way to default-construct a tuple without also constructing its elements. For example, reference type elements must be initialized at construction. Note that the number of arguments doesn't need to be the same as the number of elements of the tuple type. It is possible to supply values for some of the elements, leaving the remaining elements to be default initialized. Any exceptions from the elements' constructors are propagated.

template <class U1,class U2,...,class UN>
tuple(const tuple<U1,U2,...,UN>&);

This constructor initializes the elements using the elements from another tuple, where each of the elements from the other tuple (T1, T2,…,TM) must be constructible from (U1,U2,…,UN). Any exceptions from constructing the elements are propagated.

TIndex & get<int Index>();
const TIndex & get<int Index>() const;

Returns a reference to the element at the indicated Index. Index must be a constant integral expression; a compile-time error is produced if the index is greater than or equal to the number of elements in the tuple. The result has the type given by the corresponding template argument, indicated above by TIndex.

tuple& operator=(const tuple& other);

Copy assignment of tuples requires that the two tuples have the same length and element types. Each element in *this is assigned the corresponding element in other. Any exceptions from assigning the elements are propagated.

Free Functions

template<class T1,class T2,...,class TN> tuple<V1,V2,...,VN> 
make_tuple(const T1& t1,const T2& t2,...,const TN& tn);

The function template make_tuple is the tuple analogue of std::make_pair. It uses function template argument deduction to determine the element types for a tuple containing the arguments. The top-level cv-qualifications of the arguments are not used in creating the tuple element types. To control the type deduction for reference types, the Boost.Ref utilities ref and cref can be used to wrap the arguments and thus affect the resulting type in the returned tuple. (We'll see more about ref and cref shortly.)

template<class T1,class T2,...,class TN> tuple<T1&,T2&,...,TN> 
tie(T1& t1,T2& t2,...,TN& tn);

The function template tie is similar to make_tuple. The function call tie(t1,t2,...,tn) is equivalent to make_tuple(ref(t1),ref(t2)... ref(tn))that is, it creates a tuple of references to the function arguments. The net effect is that assigning a tuple to one created by tie copies the source tuple's elements to tie's arguments. Thus, tie makes it easy to copy the values from a tuple returned from a function to existing variables. You can also assign to a 2-tuple created by tie from a std::pair.

template <int I,class T1,class T2,...,class TN> 
RI get(tuple<T1,T2,...,TN>& t);

This overload of the function get is used to retrieve one of the elements of the tuple t. Index I must be in the range [0..N), where N is the number of elements in the tuple. If TI is a reference type, RI is TI; otherwise, RI is TI&.

template <int I,class T1,class T2,...,class TN> 
PI get(const tuple<T1,T2,...,TN>& t);

This function get is used to retrieve one of the elements of the tuple t. Index I must be in the range [0..N), where N is the number of elements in the tuple. If TI is a reference type, RI is TI; otherwise, RI is const TI&.

Relational Operators

bool operator==(
const tuple<T1,T2,...,TN>& lhs, 
const tuple<U1,U2,...,UN>& rhs);

The equality operator returns true if get<i>(lhs)==get<i>(rhs) for all i in the range [0..N), where N is the number of elements. The two tuples must have the same number of elements. Always returns true for empty tuples, where N=0.

bool operator!=(
const tuple<T1,T2,...,TN>& lhs, 
const tuple<U1,U2...,...,>& rhs);

The inequality operator returns true if get<i>(lhs)!=get<i>(rhs) for any i in the range [0..N), where N is the number of elements. The two tuples must have the same number of elements. Always returns false for empty tuples, where N=0.

bool operator<(
const tuple<T1,T2,...,TN>& lhs, 
const tuple<U1,U2,...,UN>& rhs);

The less than operator returns true if get<i>(lhs)<get<i>(rhs) for any i in the range [0..N), where N is the number of elements, assuming that for each such comparison returning false, the expression !(get<i>(rhs)<get<i>(lhs)) is true; otherwise, it returns false. The two tuples must have the same number of elements. Always returns TRue for empty tuplesthat is, where N=0.

It's worth noting that for all of the supported relational operators (operators ==, !=, <, >, <=, and >=), the two tuples must meet a couple of constraints. First, they both must be of the same length. Second, each element pair (first with first, second with second, and so on) between the two tuples must support the same relational operator. When these constraints are met, the tuple operator is implemented such that it compares each element pair, in turnthat is, the operators are short-circuited, returning as soon as the answer is obvious. The <, >, <=, and >= operators perform lexicographical comparisons, and expect the same of the element pair operators they invoke. Any exceptions emitted by the element pair operators are propagated, but the tuple operators do not throw any exceptions of their own.