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

blob: 02dabbe8e3da6f16f533e581fba9b108f318db12 [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
				120	Some versions of GCC accept the following invalid code:
				121
				122	<pre>
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	123	template <typename T> struct Foo {
				124	void Work(T x) {
				125	func(x);
				126	}
				127	};
				128	...
				129	void func(int x);
				130	...
				131	template struct Foo<int>; // or anything else that instantiates Foo<int>::Work
				132	</pre>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	133
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	134	The standard says that unqualified names like <tt>func</tt> are looked up
				135	when the template is defined, not when it's instantiated. Since
				136	<tt>void func(int)</tt> was not declared yet when <tt>Foo</tt> was
				137	defined, it's not considered. The fix is usually to
				138	declare <tt>func</tt> before <tt>Foo</tt>.
				139
				140	<p>This is complicated by <i>argument-dependent lookup</i> (ADL),
				141	which is done when unqualified names are called as functions,
				142	like <tt>func(x)</tt> above. The standard says that ADL is performed
				143	in both places if any of the arguments are type-dependent, like
				144	<tt>x</tt> is in this example. However, ADL does nothing for builtin
				145	types like <tt>int</tt>, so the example is still invalid. See
				146	[basic.lookup.argdep] for more information.
				147
				148	<!-- ======================================================================= -->
				149	<h2 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h2>
				150	<!-- ======================================================================= -->
				151
				152	Some versions of GCC accept the following invalid code:
				153
				154	<pre>
				155	template <typename T> struct Base {
				156	void DoThis(T x) {}
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	157	static void DoThat(T x) {}
				158	};
				159
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	160	template <typename T> struct Derived : public Base<T> {
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	161	void Work(T x) {
				162	DoThis(x); // Invalid!
				163	DoThat(x); // Invalid!
				164	}
				165	};
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	166	</pre>
				167
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	168	Clang correctly rejects it with the following errors
				169	(when <tt>Derived</tt> is eventually instantiated):
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	170
				171	<pre>
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	172	my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	173	DoThis(x);
				174	^
				175	this->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	176	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]	177	void DoThis(T x) {}
				178	^
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	179	my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	180	DoThat(x);
				181	^
				182	this->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	183	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]	184	static void DoThat(T x) {}
				185	</pre>
				186
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	187	Like we said <a href="#dep_lookup">above</a>, unqualified names like
				188	<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
				189	<tt>Derived</tt> is defined, not when it's instantiated. When we look
				190	up a name used in a class, we usually look into the base classes.
				191	However, we can't look into the base class <tt>Base<T></tt>
				192	because its type depends on the template argument <tt>T</tt>, so the
				193	standard says we should just ignore it. See [temp.dep]p3 for details.
				194
				195	<p>The fix, as Clang tells you, is to tell the compiler that we want a
				196	class member by prefixing the calls with <tt>this-></tt>:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	197
				198	<pre>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	199	void Work(T x) {
				200	<b>this-></b>DoThis(x);
				201	<b>this-></b>DoThat(x);
				202	}
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	203	</pre>
				204
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	205	Alternatively, you can tell the compiler exactly where to look:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	206
				207	<pre>
				208	void Work(T x) {
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	209	<b>Base<T></b>::DoThis(x);
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	210	<b>Base<T></b>::DoThat(x);
				211	}
				212	</pre>
				213
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	214	This works whether the methods are static or not, but be careful:
				215	if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
				216	dispatch!
				217
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	218	<!-- ======================================================================= -->
John McCall	4a40a2f	2010-06-02 01:26:32 +0000	[diff] [blame^]	219	<h2 id="undep_incomplete">Incomplete types in templates</h2>
				220	<!-- ======================================================================= -->
				221
				222	The following code is invalid, but compilers are allowed to accept it:
				223
				224	<pre>
				225	class IOOptions;
				226	template <class T> bool read(T &value) {
				227	IOOptions opts;
				228	return read(opts, value);
				229	}
				230
				231	class IOOptions { bool ForceReads; };
				232	bool read(const IOOptions &opts, int &x);
				233	template bool read<>(int &);
				234	</pre>
				235
				236	The standard says that types which don't depend on template parameters
				237	must be complete when a template is defined if they affect the
				238	program's behavior. However, the standard also says that compilers
				239	are free to not enforce this rule. Most compilers enforce it to some
				240	extent; for example, it would be an error in GCC to
				241	write <tt>opts.ForceReads</tt> in the code above. In Clang, we feel
				242	that enforcing the rule consistently lets us provide a better
				243	experience, but unfortunately it also means we reject some code that
				244	other compilers accept.
				245
				246	<p>We've explained the rule here in very imprecise terms; see
				247	[temp.res]p8 for details.
				248
				249	<!-- ======================================================================= -->
John McCall	5dd52ac	2010-04-09 01:07:07 +0000	[diff] [blame]	250	<h2 id="bad_templates">Templates with no valid instantiations</h2>
				251	<!-- ======================================================================= -->
				252
				253	The following code contains a typo: the programmer
				254	meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
				255
				256	<pre>
				257	template <class T> class Processor {
				258	...
				259	void init();
				260	...
				261	};
				262	...
				263	template <class T> void process() {
				264	Processor<T> processor;
				265	processor.innit(); // <-- should be 'init()'
				266	...
				267	}
				268	</pre>
				269
				270	Unfortunately, we can't flag this mistake as soon as we see it: inside
				271	a template, we're not allowed to make assumptions about "dependent
				272	types" like <tt>Processor<T></tt>. Suppose that later on in
				273	this file the programmer adds an explicit specialization
				274	of <tt>Processor</tt>, like so:
				275
				276	<pre>
				277	template <> class Processor<char*> {
				278	void innit();
				279	};
				280	</pre>
				281
				282	Now the program will work — as long as the programmer only ever
				283	instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
				284	it's hard, and sometimes impossible, to diagnose mistakes in a
				285	template definition before it's instantiated.
				286
				287	<p>The standard says that a template with no valid instantiations is
				288	ill-formed. Clang tries to do as much checking as possible at
				289	definition-time instead of instantiation-time: not only does this
				290	produce clearer diagnostics, but it also substantially improves
				291	compile times when using pre-compiled headers. The downside to this
				292	philosophy is that Clang sometimes fails to process files because they
				293	contain broken templates that are no longer used. The solution is
				294	simple: since the code is unused, just remove it.
				295
				296	<!-- ======================================================================= -->
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	297	<h2 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h2>
				298	<!-- ======================================================================= -->
				299
				300	If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
				301	constructor, C++ doesn't allow you to default construct a <tt>const</tt>
				302	instance of it like this ([dcl.init], p9):
				303
				304	<pre>
				305	class Foo {
				306	public:
				307	// The compiler-supplied default constructor works fine, so we
				308	// don't bother with defining one.
				309	...
				310	};
				311
				312	void Bar() {
				313	const Foo foo; // Error!
				314	...
				315	}
				316	</pre>
				317
				318	To fix this, you can define a default constructor for the class:
				319
				320	<pre>
				321	class Foo {
				322	public:
				323	Foo() {}
				324	...
				325	};
				326
				327	void Bar() {
				328	const Foo foo; // Now the compiler is happy.
				329	...
				330	}
				331	</pre>
				332
				333	</div>
				334	</body>
				335	</html>