[ceph.git] / ceph / src / boost / libs / fusion / doc / tuple.qbk

[/==============================================================================
    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 <boost/fusion/tuple.hpp>
    #include <boost/fusion/include/tuple.hpp>

    #include <boost/fusion/tuple/tuple.hpp>
    #include <boost/fusion/tuple/tuple_fwd.hpp>
    #include <boost/fusion/include/tuple_fwd.hpp>

    // for creation function
    #include <boost/fusion/tuple/tuple_tie.hpp>
    #include <boost/fusion/include/tuple_tie.hpp>
    #include <boost/fusion/tuple/make_tuple.hpp>
    #include <boost/fusion/include/make_tuple.hpp>

[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<typename U1, typename U2, ..., typename UN>
    tuple(const tuple<U1, U2, ..., UN>& 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<typename T1, typename T2, ..., typename TN>
    tuple<V1, V2, ..., VN>
    make_tuple(const T1& t1, const T2& t2, ..., const TN& tn);

Where `Vi` is `X&` if the cv-unqualified type `Ti` is `reference_wrapper<X>`, otherwise `Vi` is `Ti`.

[*Returns]: `tuple<V1, V2, ..., VN>(t1, t2, ..., tN)`

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

[*Returns]: tuple<T1&, T2&, ..., TN&>(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<T>::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__<T>::type`.

    tuple_element<I, T>::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__<I,T>::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<int I, T>
    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__<I,T>::type`.

[*Returns]: A reference to the `I`th element of `T`.

    template<int I, typename T>
    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__<I,T>::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<typename T1, typename T2, ..., typename TN,
             typename U1, typename U2, ..., typename UN>
    bool operator==(
        const tuple<T1, T2, ..., TN>& lhs,
        const tuple<U1, U2, ..., UN>& rhs);

[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) == __tuple_get__<i>(rhs)` is a valid
expression returning a type that is convertible to `bool`.

[*Semantics]: Returns `true` if and only if `__tuple_get__<i>(lhs) == __tuple_get__<i>(rhs)` for all `i`.
For any 2 zero length tuples `e` and `f`, `e == f` returns `true`.

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

[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) < __tuple_get__<i>(rhs)` is a valid
expression returning a type that is convertible to `bool`.

[*Semantics]: Returns the lexicographical comparison of between `lhs` and `rhs`.

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

[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) == __tuple_get__<i>(rhs)` is a valid
expression returning a type that is convertible to `bool`.

[*Semantics]: Returns `!(lhs == rhs)`.

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

[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(rhs) < __tuple_get__<i>(lhs)` is a valid
expression returning a type that is convertible to `bool`.

[*Semantics]: Returns `!(rhs < lhs)`

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

[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(rhs) < __tuple_get__<i>(lhs)` is a valid
expression returning a type that is convertible to `bool`.

[*Semantics]: Returns `rhs < lhs`.

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

[*Requirements]: For all `i`, `1 <= i < N`, `__tuple_get__<i>(lhs) < __tuple_get__<i>(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<std::pair<T1, T2> >::value

[*Type]: An __mpl_integral_constant__

[*Value]: Returns 2, the number of elements in a pair.

    tuple_element<0, std::pair<T1, T2> >::type

[*Type]: `T1`

[*Value]: Returns the type of the first element of the pair

    tuple_element<1, std::pair<T1, T2> >::type

[*Type]: `T2`

[*Value]: Returns the type of the second element of the pair

    template<int I, typename T1, typename T2>
    P& get(std::pair<T1, T2>& pr);

    template<int I, typename T1, typename T2>
    const P& get(const std::pair<T1, T2>& 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]
Commit	Line	Data
7c673cae FG	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
	11	The TR1 technical report describes extensions to the C++ standard library.
	12	Many of these extensions will be considered for the next
	13	iteration of the C++ standard. TR1 describes a tuple type, and
	14	support for treating `std::pair` as a type of tuple.
	15
	16	Fusion provides full support for the __tr1__tuple__ interface, and the extended
	17	uses of `std::pair` described in the TR1 document.
	18
	19	[section Class template tuple]
	20	Fusion's implementation of the __tr1__tuple__ is also a fusion __forward_sequence__.
	21	As such the fusion tuple type provides a lot of functionality beyond that required by TR1.
	22
	23	Currently tuple is basically a synonym for __vector__, although this may be changed
	24	in 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]
	52	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.
	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]
93	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.
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
101	Where `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]
116	The __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]
139	The __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]
167	The __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
185	expression 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`.
188	For 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
197	expression 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
208	expression 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
219	expression 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
230	expression 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
241	expression 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]
252	The __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