Planet

navi

home

PPS

about

screenshots

download

development

forum

Context Navigation

source: downloads/boost_1_33_1/libs/utility/enable_if.html @ 14

Last change on this file since 14 was 12, checked in by landauf, 17 years ago
added boost
File size: 16.4 KB

Line
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2	"http://www.w3.org/TR/REC-html40/loose.dtd">
3	<HTML>
4	<HEAD><TITLE>enable_if</TITLE>
5
6	<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7	<META name="GENERATOR" content="Microsoft FrontPage 5.0">
8	</HEAD>
9	<BODY >
10	<!--HEVEA command line is: hevea -nosymb -noiso -pedantic -v enable_if_docs_for_boost.tex -->
11	<!--HTMLHEAD-->
12	<!--ENDHTML-->
13	<!--PREFIX <ARG ></ARG>-->
14	<!--CUT DEF section 1 -->
15	<BR>
16	<BR>
17
18
19	<h1>
20	<img border="0" src="../../boost.png" align="center" width="277" height="86">enable_if</h1>
21	<BR>
22	<BR>
23	Copyright 2003 Jaakko Järvi, Jeremiah Willcock, Andrew Lumsdaine.<BR>
24	<BR>
25	<!--TOC section Introduction-->
26
27	<H2><A NAME="htoc1">1</A>  Introduction</H2><!--SEC END -->
28
29	<A NAME="introduction"></A>
30	The <TT>enable_if</TT> family of templates is a set of tools to allow a function template or a class template specialization
31	to include or exclude itself from a set of matching functions or specializations
32	based on properties of its template arguments.
33	For example, one can define function templates that
34	are only enabled for, and thus only match, an arbitrary set of types
35	defined by a traits class. The <TT>enable_if</TT> templates can also be
36	applied to enable class template specializations. Applications of
37	<TT>enable_if</TT> are discussed in length
38	in [<A HREF="#jarvi:03:cuj_arbitrary_overloading"><CITE>1</CITE></A>] and [<A HREF="#jarvi:03:c++typeclasses"><CITE>2</CITE></A>].<BR>
39	<BR>
40	<!--TOC subsection Synopsis-->
41
42	<H3><A NAME="htoc2">1.1</A>  Synopsis</H3><!--SEC END -->
43
44	<A NAME="sec:synopsis"></A>
45	<PRE>namespace boost {
46	template <class Cond, class T = void> struct enable_if;
47	template <class Cond, class T = void> struct disable_if;
48	template <class Cond, class T> struct lazy_enable_if;
49	template <class Cond, class T> struct lazy_disable_if;
50
51	template <bool B, class T = void> struct enable_if_c;
52	template <bool B, class T = void> struct disable_if_c;
53	template <bool B, class T> struct lazy_enable_if_c;
54	template <bool B, class T> struct lazy_disable_if_c;
55	}
56	</PRE>
57	<!--TOC subsection Background-->
58
59	<H3><A NAME="htoc3">1.2</A>  Background</H3><!--SEC END -->
60
61	<A NAME="sec:background"></A>
62	Sensible operation of template function overloading in C++ relies
63	on the <EM>SFINAE</EM> (substitution-failure-is-not-an-error)
64	principle [<A HREF="#vandevoorde2002:templates"><CITE>3</CITE></A>]: if an invalid argument
65	or return type is formed during the instantiation of a function
66	template, the instantiation is removed from the overload resolution
67	set instead of causing a compilation error. The following example,
68	taken from [<A HREF="#jarvi:03:cuj_arbitrary_overloading"><CITE>1</CITE></A>],
69	demonstrates why this is important:
70	<PRE>int negate(int i) { return -i; }
71
72	template <class F>
73	typename F::result_type negate(const F& f) { return -f(); }
74
75	</PRE>
76	Suppose the compiler encounters the call <TT>negate(1)</TT>. The first
77	definition is obviously a better match, but the compiler must
78	nevertheless consider (and instantiate the prototypes) of both
79	definitions to find this out. Instantiating the latter definition with
80	<TT>F</TT> as <TT>int</TT> would result in:
81	<PRE>int::result_type negate(const int&);
82
83	</PRE>
84	where the return type is invalid. If this was an error, adding an unrelated function template
85	(that was never called) could break otherwise valid code.
86	Due to the SFINAE principle the above example is not, however, erroneous.
87	The latter definition of <TT>negate</TT> is simply removed from the overload resolution set.<BR>
88	<BR>
89	The <TT>enable_if</TT> templates are tools for controlled creation of the SFINAE
90	conditions.<BR>
91	<BR>
92	<!--TOC section The <TT>enable_if</TT> templates-->
93
94	<H2><A NAME="htoc4">2</A>  The <TT>enable_if</TT> templates</H2><!--SEC END -->
95
96	<A NAME="enable_if"></A>
97	The names of the <TT>enable_if</TT> templates have three parts: an optional <TT>lazy_</TT> tag,
98	either <TT>enable_if</TT> or <TT>disable_if</TT>, and an optional <TT>_c</TT> tag.
99	All eight combinations of these parts are supported.
100	The meaning of the <TT>lazy_</TT> tag is described in Section <A HREF="#sec:enable_if_lazy">3.3</A>.
101	The second part of the name indicates whether a true condition argument should
102	enable or disable the current overload.
103	The third part of the name indicates whether the condition argument is a <TT>bool</TT> value
104	(<TT>_c</TT> suffix), or a type containing a static <TT>bool</TT> constant named <TT>value</TT> (no suffix).
105	The latter version interoperates with Boost.MPL. <BR>
106	<BR>
107	The definitions of <TT>enable_if_c</TT> and <TT>enable_if</TT> are as follows (we use <TT>enable_if</TT> templates
108	unqualified but they are in the <TT>boost</TT> namespace).
109	<PRE>template <bool B, class T = void>
110	struct enable_if_c {
111	typedef T type;
112	};
113
114	template <class T>
115	struct enable_if_c<false, T> {};
116
117	template <class Cond, class T = void>
118	struct enable_if : public enable_if_c<Cond::value, T> {};
119
120	</PRE>
121	An instantiation of the <TT>enable_if_c</TT> template with the parameter
122	<TT>B</TT> as <TT>true</TT> contains a member type <TT>type</TT>, defined
123	to be <TT>T</TT>. If <TT>B</TT> is
124	<TT>false</TT>, no such member is defined. Thus
125	<TT>enable_if_c<B, T>::type</TT> is either a valid or an invalid type
126	expression, depending on the value of <TT>B</TT>.
127	When valid, <TT>enable_if_c<B, T>::type</TT> equals <TT>T</TT>.
128	The <TT>enable_if_c</TT> template can thus be used for controlling when functions are considered for
129	overload resolution and when they are not.
130	For example, the following function is defined for all arithmetic types (according to the
131	classification of the <A HREF="../type_traits/index.html">Boost type_traits library</A>):
132	<PRE>template <class T>
133	typename enable_if_c<boost::is_arithmetic<T>::value, T>::type
134	foo(T t) { return t; }
135
136	</PRE>
137	The <TT>disable_if_c</TT> template is provided as well, and has the
138	same functionality as <TT>enable_if_c</TT> except for the negated condition. The following
139	function is enabled for all non-arithmetic types.
140	<PRE>template <class T>
141	typename disable_if_c<boost::is_arithmetic<T>::value, T>::type
142	bar(T t) { return t; }
143
144	</PRE>
145	For easier syntax in some cases and interoperation with Boost.MPL we provide versions of
146	the <TT>enable_if</TT> templates taking any type with a <TT>bool</TT> member constant named
147	<TT>value</TT> as the condition argument.
148	The MPL <TT>bool_</TT>, <TT>and_</TT>, <TT>or_</TT>, and <TT>not_</TT> templates are likely to be
149	useful for creating such types. Also, the traits classes in the Boost.Type_traits library
150	follow this convention.
151	For example, the above example function <TT>foo</TT> can be alternatively written as:
152	<PRE>template <class T>
153	typename enable_if<boost::is_arithmetic<T>, T>::type
154	foo(T t) { return t; }
155
156	</PRE>
157	<!--TOC section Using <TT>enable_if</TT>-->
158
159	<H2><A NAME="htoc5">3</A>  Using <TT>enable_if</TT></H2><!--SEC END -->
160
161	<A NAME="sec:using_enable_if"></A>
162	The <TT>enable_if</TT> templates are defined in
163	<TT>boost/utility/enable_if.hpp</TT>, which is included by <TT>boost/utility.hpp</TT>.<BR>
164	<BR>
165	The <TT>enable_if</TT> template can be used either as the return type, or as an
166	extra argument. For example, the <TT>foo</TT> function in the previous section could also be written
167	as:
168	<PRE>template <class T>
169	T foo(T t, typename enable_if<boost::is_arithmetic<T> >::type* dummy = 0);
170
171	</PRE>Hence, an extra parameter of type <TT>void*</TT> is added, but it is given
172	a default value to keep the parameter hidden from client code.
173	Note that the second template argument was not given to <TT>enable_if</TT>, as the default
174	<TT>void</TT> gives the desired behavior.<BR>
175	<BR>
176	Whether to write the enabler as an argument or within the return type is
177	largely a matter of taste, but for certain functions, only one
178	alternative is possible:
179	<UL><LI>
180	Operators have a fixed number of arguments, thus <TT>enable_if</TT> must be used in the return type.
181	<LI>Constructors and destructors do not have a return type; an extra argument is the only option.
182	<LI>There does not seem to be a way to specify an enabler for a conversion operator. Converting constructors,
183	however, can have enablers as extra default arguments.
184	</UL>
185	<!--TOC subsection Enabling template class specializations-->
186
187	<H3><A NAME="htoc6">3.1</A>  Enabling template class specializations</H3><!--SEC END -->
188
189	<A NAME="sec:enable_if_classes"></A>
190	Class template specializations can be enabled or disabled with <TT>enable_if</TT>.
191	One extra template parameter needs to be added for the enabler expressions.
192	This parameter has the default value <TT>void</TT>.
193	For example:
194	<PRE>template <class T, class Enable = void>
195	class A { ... };
196
197	template <class T>
198	class A<T, typename enable_if<is_integral<T> >::type> { ... };
199
200	template <class T>
201	class A<T, typename enable_if<is_float<T> >::type> { ... };
202
203	</PRE>Instantiating <TT>A</TT> with any integral type matches the first specialization,
204	whereas any floating point type matches the second one. All other types
205	match the primary template.
206	The condition can be any compile-time boolean expression that depends on the
207	template arguments of the class.
208	Note that again, the second argument to <TT>enable_if</TT> is not needed; the default (<TT>void</TT>)
209	is the correct value.<BR>
210	<BR>
211	<!--TOC subsection Overlapping enabler conditions-->
212
213	<H3><A NAME="htoc7">3.2</A>  Overlapping enabler conditions</H3><!--SEC END -->
214
215	<A NAME="sec:overlapping_conditions"></A>
216	Once the compiler has examined the enabling conditions and included the
217	function into the overload resolution set, normal C++ overload resolution
218	rules are used to select the best matching function.
219	In particular, there is no ordering between enabling conditions.
220	Function templates with enabling conditions that are not mutually exclusive can
221	lead to ambiguities. For example:
222	<PRE>template <class T>
223	typename enable_if<boost::is_integral<T>, void>::type
224	foo(T t) {}
225
226	template <class T>
227	typename enable_if<boost::is_arithmetic<T>, void>::type
228	foo(T t) {}
229
230	</PRE>
231	All integral types are also arithmetic. Therefore, say, for the call <TT>foo(1)</TT>,
232	both conditions are true and both functions are thus in the overload resolution set.
233	They are both equally good matches and thus ambiguous.
234	Of course, more than one enabling condition can be simultaneously true as long as
235	other arguments disambiguate the functions.<BR>
236	<BR>
237	The above discussion applies to using <TT>enable_if</TT> in class template
238	partial specializations as well.<BR>
239	<BR>
240	<!--TOC subsection Lazy <TT>enable_if</TT>-->
241
242	<H3><A NAME="htoc8">3.3</A>  Lazy <TT>enable_if</TT></H3><!--SEC END -->
243
244	<A NAME="sec:enable_if_lazy"></A>
245	In some cases it is necessary to avoid instantiating part of a
246	function signature unless an enabling condition is true. For example:
247	<PRE>template <class T, class U> class mult_traits;
248
249	template <class T, class U>
250	typename enable_if<is_multipliable<T, U>, typename mult_traits<T, U>::type>::type
251	operator*(const T& t, const U& u) { ... }
252
253	</PRE>Assume the class template <TT>mult_traits</TT> is a traits class defining
254	the resulting type of a multiplication operator. The <TT>is_multipliable</TT> traits
255	class specifies for which types to enable the operator. Whenever
256	<TT>is_multipliable<A, B>::value</TT> is <TT>true</TT> for some types <TT>A</TT> and <TT>B</TT>,
257	then <TT>mult_traits<A, B>::type</TT> is defined.<BR>
258	<BR>
259	Now, trying to invoke (some other overload) of <TT>operator*</TT> with, say, operand types <TT>C</TT> and <TT>D</TT>
260	for which <TT>is_multipliable<C, D>::value</TT> is <TT>false</TT>
261	and <TT>mult_traits<C, D>::type</TT> is not defined is an error on some compilers.
262	The SFINAE principle is not applied because
263	the invalid type occurs as an argument to another template. The <TT>lazy_enable_if</TT>
264	and <TT>lazy_disable_if</TT> templates (and their <TT>_c</TT> versions) can be used in such
265	situations:
266	<PRE>template<class T, class U>
267	typename lazy_enable_if<is_multipliable<T, U>, mult_traits<T, U> >::type
268	operator*(const T& t, const U& u) { ... }
269
270	</PRE>The second argument of <TT>lazy_enable_if</TT> must be a class type
271	that defines a nested type named <TT>type</TT> whenever the first
272	parameter (the condition) is true.<BR>
273	<BR>
274	<!--TOC paragraph Note-->
275
276	<H5>Note</H5><!--SEC END -->
277
278	Referring to one member type or static constant in a traits class
279	causes all of the members (type and static constant) of that
280	specialization to be instantiated. Therefore, if your traits classes
281	can sometimes contain invalid types, you should use two distinct
282	templates for describing the conditions and the type mappings. In the
283	above example, <TT>is_multipliable<T, U>::value</TT> defines when
284	<TT>mult_traits<T, U>::type</TT> is valid.<BR>
285	<BR>
286	<!--TOC subsection Compiler workarounds-->
287
288	<H3><A NAME="htoc9">3.4</A>  Compiler workarounds</H3><!--SEC END -->
289
290	<A NAME="sec:workarounds"></A>
291	Some compilers flag functions as ambiguous if the only distinguishing factor is a different
292	condition in an enabler (even though the functions could never be ambiguous). For example,
293	some compilers (e.g. GCC 3.2) diagnose the following two functions as ambiguous:
294	<PRE>template <class T>
295	typename enable_if<boost::is_arithmetic<T>, T>::type
296	foo(T t);
297
298	template <class T>
299	typename disable_if<boost::is_arithmetic<T>, T>::type
300	foo(T t);
301
302	</PRE>Two workarounds can be applied:
303	<UL><LI>
304	Use an extra dummy parameter which disambiguates the functions. Use a default value for
305	it to hide the parameter from the caller. For example:
306	<PRE>template <int> struct dummy { dummy(int) {} };
307
308	template <class T>
309	typename enable_if<boost::is_arithmetic<T>, T>::type
310	foo(T t, dummy<0> = 0);
311
312	template <class T>
313	typename disable_if<boost::is_arithmetic<T>, T>::type
314	foo(T t, dummy<1> = 0);
315	</PRE><BR>
316	<BR>
317	<LI>Define the functions in different namespaces and bring them into a common
318	namespace with <TT>using</TT> declarations:
319	<PRE>namespace A {
320	template <class T>
321	typename enable_if<boost::is_arithmetic<T>, T>::type
322	foo(T t);
323	}
324
325	namespace B {
326	template <class T>
327	typename disable_if<boost::is_arithmetic<T>, T>::type
328	foo(T t);
329	}
330
331	using A::foo;
332	using B::foo;
333
334	</PRE>
335	Note that the second workaround above cannot be used for member
336	templates. On the other hand, operators do not accept extra arguments,
337	which makes the first workaround unusable. As the net effect,
338	neither of the workarounds are of assistance for templated operators that
339	need to be defined as member functions (assignment and
340	subscript operators).
341	</UL>
342	<!--TOC section Acknowledgements-->
343
344	<H2><A NAME="htoc10">4</A>  Acknowledgements</H2><!--SEC END -->
345
346	We are grateful to Howard Hinnant, Jason Shirk, Paul Mensonides, and Richard
347	Smith whose findings have influenced the library.<BR>
348	<BR>
349	<!--TOC section References-->
350
351	<H2>References</H2><!--SEC END -->
352	<DL COMPACT=compact><DT><A NAME="jarvi:03:cuj_arbitrary_overloading"><FONT COLOR=purple>[1]</FONT></A><DD>
353	Jaakko Järvi, Jeremiah Willcock, Howard Hinnant, and Andrew Lumsdaine.
354	Function overloading based on arbitrary properties of types.
355	<EM>C/C++ Users Journal</EM>, 21(6):25--32, June 2003.<BR>
356	<BR>
357	<DT><A NAME="jarvi:03:c++typeclasses"><FONT COLOR=purple>[2]</FONT></A><DD>
358	Jaakko Järvi, Jeremiah Willcock, and Andrew Lumsdaine.
359	Concept-controlled polymorphism.
360	In Frank Pfennig and Yannis Smaragdakis, editors, <EM>Generative
361	Programming and Component Engineering</EM>, volume 2830 of <EM>LNCS</EM>, pages
362	228--244. Springer Verlag, September 2003.<BR>
363	<BR>
364	<DT><A NAME="vandevoorde2002:templates"><FONT COLOR=purple>[3]</FONT></A><DD>
365	David Vandevoorde and Nicolai M. Josuttis.
366	<EM>C++ Templates: The Complete Guide</EM>.
367	Addison-Wesley, 2002.</DL>
368
369
370
371
372
373	<hr></hr>
374
375	<B>Contributed by:</B> <BR>
376	Jaakko Järvi, Jeremiah Willcock and Andrew Lumsdaine<BR>
377	<EM>{jajarvi\|jewillco\|lums}@osl.iu.edu</EM><BR>
378	Indiana University<BR>
379	Open Systems Lab
380	<!--HTMLFOOT-->
381	<!--ENDHTML-->
382	<!--FOOTER-->
383	<HR SIZE=2>
384	<BLOCKQUOTE><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
385	</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.
386	</EM></BLOCKQUOTE>
387	</BODY>
388	</HTML>

Note: See TracBrowser for help on using the repository browser.

Download in other formats: