Blame - www/cxx_compatibility.html - fp2-dev/platform/external/clang

blob: 1273ed3a8c305cb898ada5d05316bfb9a37a9fe1 [file] [log] [blame]

Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
				2	"http://www.w3.org/TR/html4/strict.dtd">
				3	<html>
				4	<head>
				5	<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
				6	<title>Clang - C++ Compatibility</title>
				7	<link type="text/css" rel="stylesheet" href="menu.css" />
				8	<link type="text/css" rel="stylesheet" href="content.css" />
				9	<style type="text/css">
				10	</style>
				11	</head>
				12	<body>
				13
				14	<!--#include virtual="menu.html.incl"-->
				15
				16	<div id="content">
				17
				18	<!-- ======================================================================= -->
				19	<h1>Clang's C++ Compatibility</h1>
				20	<!-- ======================================================================= -->
				21
				22	<ul>
				23	<li><a href="#intro">Introduction</a></li>
				24	<li><a href="#vla">Variable-length arrays</a></li>
				25	<li><a href="#init_static_const">Initialization of non-integral static const data members within a class definition</a></li>
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	26	<li><a href="#dep_lookup">Unqualified lookup in templates</a></li>
				27	<li><a href="#dep_lookup_bases">Unqualified lookup into dependent bases of class templates</a></li>
John McCall	4a40a2f	2010-06-02 01:26:32 +0000	[diff] [blame]	28	<li><a href="#undep_incomplete">Incomplete types in templates</a></li>
John McCall	5dd52ac	2010-04-09 01:07:07 +0000	[diff] [blame]	29	<li><a href="#bad_templates">Templates with no valid instantiations</a></li>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	30	<li><a href="#default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</a></li>
				31	</ul>
				32
				33	<!-- ======================================================================= -->
				34	<h2 id="intro">Introduction</h2>
				35	<!-- ======================================================================= -->
				36
				37	<p>Clang strives to strictly conform to the C++ standard. That means
				38	it will reject invalid C++ code that another compiler may accept.
				39	This page helps you decide whether a Clang error message means a
				40	C++-conformance bug in your code and how you can fix it.</p>
				41
				42	<!-- ======================================================================= -->
				43	<h2 id="vla">Variable-length arrays</h2>
				44	<!-- ======================================================================= -->
				45
Douglas Gregor	0fddb97	2010-05-22 16:17:30 +0000	[diff] [blame]	46	<p>GCC and C99 allow an array's size to be determined at run
				47	time. This extension is not permitted in standard C++. However, Clang
				48	supports such variable length arrays in very limited circumstances for
				49	compatibility with GNU C and C99 programs:</p>
				50
				51	<ul>
				52	<li>The element type of a variable length array must be a POD
				53	("plain old data") type, which means that it cannot have any
				54	user-declared constructors or destructors, base classes, or any
				55	members if non-POD type. All C types are POD types.</li>
				56
Douglas Gregor	a481ec4	2010-05-23 19:57:01 +0000	[diff] [blame]	57	<li>Variable length arrays cannot be used as the type of a non-type
				58	template parameter.</li> </ul>
Douglas Gregor	0fddb97	2010-05-22 16:17:30 +0000	[diff] [blame]	59
				60	<p>If your code uses variable length arrays in a manner that Clang doesn't support, there are several ways to fix your code:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	61
				62	<ol>
Douglas Gregor	0fddb97	2010-05-22 16:17:30 +0000	[diff] [blame]	63	<li>replace the variable length array with a fixed-size array if you can
				64	determine a
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	65	reasonable upper bound at compile time; sometimes this is as
				66	simple as changing <tt>int size = ...;</tt> to <tt>const int size
				67	= ...;</tt> (if the definition of <tt>size</tt> is a compile-time
				68	integral constant);</li>
				69	<li>use an <tt>std::string</tt> instead of a <tt>char []</tt>;</li>
				70	<li>use <tt>std::vector</tt> or some other suitable container type;
				71	or</li>
				72	<li>allocate the array on the heap instead using <tt>new Type[]</tt> -
Chandler Carruth	6243e33	2010-03-17 05:46:21 +0000	[diff] [blame]	73	just remember to <tt>delete[]</tt> it.</li>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	74	</ol>
				75
				76	<!-- ======================================================================= -->
				77	<h2 id="init_static_const">Initialization of non-integral static const data members within a class definition</h2>
				78	<!-- ======================================================================= -->
				79
				80	The following code is ill-formed in C++'03:
				81
				82	<pre>
				83	class SomeClass {
				84	public:
				85	static const double SomeConstant = 0.5;
				86	};
				87
				88	const double SomeClass::SomeConstant;
				89	</pre>
				90
				91	Clang errors with something similar to:
				92
				93	<pre>
				94	.../your_file.h:42:42: error: 'SomeConstant' can only be initialized if it is a static const integral data member
				95	static const double SomeConstant = 0.5;
				96	^ ~~~
				97	</pre>
				98
				99	Only <i>integral</i> constant expressions are allowed as initializers
				100	within the class definition. See C++'03 [class.static.data] p4 for the
				101	details of this restriction. The fix here is straightforward: move
				102	the initializer to the definition of the static data member, which
				103	must exist outside of the class definition:
				104
				105	<pre>
				106	class SomeClass {
				107	public:
				108	static const double SomeConstant;
				109	};
				110
				111	const double SomeClass::SomeConstant<b> = 0.5</b>;
				112	</pre>
				113
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	114	Note that the forthcoming C++0x standard will allow this.
				115
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	116	<!-- ======================================================================= -->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	117	<h2 id="dep_lookup">Unqualified lookup in templates</h2>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	118	<!-- ======================================================================= -->
				119
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	120	<p>Some versions of GCC accept the following invalid code:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	121
				122	<pre>
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	123	template <typename T> T Squared(T x) {
				124	return Multiply(x, x);
				125	}
				126
				127	int Multiply(int x, int y) {
				128	return x * y;
				129	}
				130
				131	int main() {
				132	Squared(5);
				133	}
				134	</pre>
				135
				136	<p>Clang complains:
				137
				138	<pre> <b>my_file.cpp:2:10: <span class="error">error:</span> use of undeclared identifier 'Multiply'</b>
				139	return Multiply(x, x);
				140	<span class="caret"> ^</span>
				141
				142	<b>my_file.cpp:10:3: <span class="note">note:</span> in instantiation of function template specialization 'Squared<int>' requested here</b>
				143	Squared(5);
				144	<span class="caret"> ^</span>
				145	</pre>
				146
				147	<p>The C++ standard says that unqualified names like <q>Multiply</q>
				148	are looked up in two ways.
				149
				150	<p>First, the compiler does <i>unqualified lookup</i> in the scope
				151	where the name was written. For a template, this means the lookup is
				152	done at the point where the template is defined, not where it's
				153	instantiated. Since <tt>Multiply</tt> hasn't been declared yet at
				154	this point, unqualified lookup won't find it.
				155
				156	<p>Second, if the name is called like a function, then the compiler
				157	also does <i>argument-dependent lookup</i> (ADL). (Sometimes
				158	unqualified lookup can suppress ADL; see [basic.lookup.argdep]p3 for
				159	more information.) In ADL, the compiler looks at the types of all the
				160	arguments to the call. When it finds a class type, it looks up the
				161	name in that class's namespace; the result is all the declarations it
				162	finds in those namespaces, plus the declarations from unqualified
				163	lookup. However, the compiler doesn't do ADL until it knows all the
				164	argument types.
				165
				166	<p>In our example, <tt>Multiply</tt> is called with dependent
				167	arguments, so ADL isn't done until the template is instantiated. At
				168	that point, the arguments both have type <tt>int</tt>, which doesn't
				169	contain any class types, and so ADL doesn't look in any namespaces.
				170	Since neither form of lookup found the declaration
				171	of <tt>Multiply</tt>, the code doesn't compile.
				172
				173	<p>Here's another example, this time using overloaded operators,
				174	which obey very similar rules.
				175
				176	<pre>#include <iostream>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	177
John McCall	d45c93c	2010-06-16 08:48:08 +0000	[diff] [blame]	178	template<typename T>
				179	void Dump(const T& value) {
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	180	std::cout << value << "\n";
				181	}
				182
				183	namespace ns {
				184	struct Data {};
				185	}
				186
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	187	std::ostream& operator<<(std::ostream& out, ns::Data data) {
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	188	return out << "Some data";
				189	}
				190
				191	void Use() {
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	192	Dump(ns::Data());
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	193	}</pre>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	194
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	195	<p>Again, Clang complains about not finding a matching function:</p>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	196
				197	<pre>
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	198	<b>my_file.cpp:5:13: <span class="error">error:</span> invalid operands to binary expression ('ostream' (aka 'basic_ostream<char>') and 'ns::Data const')</b>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	199	std::cout << value << "\n";
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	200	<span class="caret">~~~~~~~~~ ^ ~~~~~</span>
				201	<b>my_file.cpp:17:3: <span class="note">note:</span> in instantiation of function template specialization 'Dump<ns::Data>' requested here</b>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	202	Dump(ns::Data());
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	203	<span class="caret">^</span>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	204	</pre>
				205
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	206	<p>Just like before, unqualified lookup didn't find any declarations
				207	with the name <tt>operator<<</tt>. Unlike before, the argument
				208	types both contain class types: one of them is an instance of the
				209	class template type <tt>std::basic_ostream</tt>, and the other is the
				210	type <tt>ns::Data</tt> that we declared above. Therefore, ADL will
				211	look in the namespaces <tt>std</tt> and <tt>ns</tt> for
				212	an <tt>operator<<</tt>. Since one of the argument types was
				213	still dependent during the template definition, ADL isn't done until
				214	the template is instantiated during <tt>Use</tt>, which means that
				215	the <tt>operator<<</tt> we want it to find has already been
				216	declared. Unfortunately, it was declared in the global namespace, not
				217	in either of the namespaces that ADL will look in!
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	218
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	219	<p>There are two ways to fix this problem:</p>
				220	<ol><li>Make sure the function you want to call is declared before the
				221	template that might call it. This is the only option if none of its
				222	argument types contain classes. You can do this either by moving the
				223	template definition, or by moving the function definition, or by
				224	adding a forward declaration of the function before the template.</li>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	225	<li>Move the function into the same namespace as one of its arguments
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	226	so that ADL applies.</li></ol>
Jeffrey Yasskin	f44ea72	2010-06-16 01:12:12 +0000	[diff] [blame]	227
John McCall	5016300	2010-06-16 10:48:16 +0000	[diff] [blame]	228	<p>For more information about argument-dependent lookup, see
				229	[basic.lookup.argdep]. For more information about the ordering of
				230	lookup in templates, see [temp.dep.candidate].
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	231
				232	<!-- ======================================================================= -->
				233	<h2 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h2>
				234	<!-- ======================================================================= -->
				235
				236	Some versions of GCC accept the following invalid code:
				237
				238	<pre>
				239	template <typename T> struct Base {
				240	void DoThis(T x) {}
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	241	static void DoThat(T x) {}
				242	};
				243
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	244	template <typename T> struct Derived : public Base<T> {
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	245	void Work(T x) {
				246	DoThis(x); // Invalid!
				247	DoThat(x); // Invalid!
				248	}
				249	};
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	250	</pre>
				251
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	252	Clang correctly rejects it with the following errors
				253	(when <tt>Derived</tt> is eventually instantiated):
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	254
				255	<pre>
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	256	my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	257	DoThis(x);
				258	^
				259	this->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	260	my_file.cpp:2:8: note: must qualify identifier to find this declaration in dependent base class
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	261	void DoThis(T x) {}
				262	^
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	263	my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	264	DoThat(x);
				265	^
				266	this->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	267	my_file.cpp:3:15: note: must qualify identifier to find this declaration in dependent base class
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	268	static void DoThat(T x) {}
				269	</pre>
				270
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	271	Like we said <a href="#dep_lookup">above</a>, unqualified names like
				272	<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
				273	<tt>Derived</tt> is defined, not when it's instantiated. When we look
				274	up a name used in a class, we usually look into the base classes.
				275	However, we can't look into the base class <tt>Base<T></tt>
				276	because its type depends on the template argument <tt>T</tt>, so the
				277	standard says we should just ignore it. See [temp.dep]p3 for details.
				278
				279	<p>The fix, as Clang tells you, is to tell the compiler that we want a
				280	class member by prefixing the calls with <tt>this-></tt>:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	281
				282	<pre>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	283	void Work(T x) {
				284	<b>this-></b>DoThis(x);
				285	<b>this-></b>DoThat(x);
				286	}
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	287	</pre>
				288
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	289	Alternatively, you can tell the compiler exactly where to look:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	290
				291	<pre>
				292	void Work(T x) {
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	293	<b>Base<T></b>::DoThis(x);
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	294	<b>Base<T></b>::DoThat(x);
				295	}
				296	</pre>
				297
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	298	This works whether the methods are static or not, but be careful:
				299	if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
				300	dispatch!
				301
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	302	<!-- ======================================================================= -->
John McCall	4a40a2f	2010-06-02 01:26:32 +0000	[diff] [blame]	303	<h2 id="undep_incomplete">Incomplete types in templates</h2>
				304	<!-- ======================================================================= -->
				305
				306	The following code is invalid, but compilers are allowed to accept it:
				307
				308	<pre>
				309	class IOOptions;
				310	template <class T> bool read(T &value) {
				311	IOOptions opts;
				312	return read(opts, value);
				313	}
				314
				315	class IOOptions { bool ForceReads; };
				316	bool read(const IOOptions &opts, int &x);
				317	template bool read<>(int &);
				318	</pre>
				319
				320	The standard says that types which don't depend on template parameters
				321	must be complete when a template is defined if they affect the
				322	program's behavior. However, the standard also says that compilers
				323	are free to not enforce this rule. Most compilers enforce it to some
				324	extent; for example, it would be an error in GCC to
				325	write <tt>opts.ForceReads</tt> in the code above. In Clang, we feel
				326	that enforcing the rule consistently lets us provide a better
				327	experience, but unfortunately it also means we reject some code that
				328	other compilers accept.
				329
				330	<p>We've explained the rule here in very imprecise terms; see
				331	[temp.res]p8 for details.
				332
				333	<!-- ======================================================================= -->
John McCall	5dd52ac	2010-04-09 01:07:07 +0000	[diff] [blame]	334	<h2 id="bad_templates">Templates with no valid instantiations</h2>
				335	<!-- ======================================================================= -->
				336
				337	The following code contains a typo: the programmer
				338	meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
				339
				340	<pre>
				341	template <class T> class Processor {
				342	...
				343	void init();
				344	...
				345	};
				346	...
				347	template <class T> void process() {
				348	Processor<T> processor;
				349	processor.innit(); // <-- should be 'init()'
				350	...
				351	}
				352	</pre>
				353
				354	Unfortunately, we can't flag this mistake as soon as we see it: inside
				355	a template, we're not allowed to make assumptions about "dependent
				356	types" like <tt>Processor<T></tt>. Suppose that later on in
				357	this file the programmer adds an explicit specialization
				358	of <tt>Processor</tt>, like so:
				359
				360	<pre>
				361	template <> class Processor<char*> {
				362	void innit();
				363	};
				364	</pre>
				365
				366	Now the program will work — as long as the programmer only ever
				367	instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
				368	it's hard, and sometimes impossible, to diagnose mistakes in a
				369	template definition before it's instantiated.
				370
				371	<p>The standard says that a template with no valid instantiations is
				372	ill-formed. Clang tries to do as much checking as possible at
				373	definition-time instead of instantiation-time: not only does this
				374	produce clearer diagnostics, but it also substantially improves
				375	compile times when using pre-compiled headers. The downside to this
				376	philosophy is that Clang sometimes fails to process files because they
				377	contain broken templates that are no longer used. The solution is
				378	simple: since the code is unused, just remove it.
				379
				380	<!-- ======================================================================= -->
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	381	<h2 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h2>
				382	<!-- ======================================================================= -->
				383
				384	If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
				385	constructor, C++ doesn't allow you to default construct a <tt>const</tt>
				386	instance of it like this ([dcl.init], p9):
				387
				388	<pre>
				389	class Foo {
				390	public:
				391	// The compiler-supplied default constructor works fine, so we
				392	// don't bother with defining one.
				393	...
				394	};
				395
				396	void Bar() {
				397	const Foo foo; // Error!
				398	...
				399	}
				400	</pre>
				401
				402	To fix this, you can define a default constructor for the class:
				403
				404	<pre>
				405	class Foo {
				406	public:
				407	Foo() {}
				408	...
				409	};
				410
				411	void Bar() {
				412	const Foo foo; // Now the compiler is happy.
				413	...
				414	}
				415	</pre>
				416
				417	</div>
				418	</body>
				419	</html>