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

blob: cfe3c0a60c9608f09fa72cbfc0902d550084f22a [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	5dd52ac	2010-04-09 01:07:07 +0000	[diff] [blame]	28	<li><a href="#bad_templates">Templates with no valid instantiations</a></li>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	29	<li><a href="#default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</a></li>
				30	</ul>
				31
				32	<!-- ======================================================================= -->
				33	<h2 id="intro">Introduction</h2>
				34	<!-- ======================================================================= -->
				35
				36	<p>Clang strives to strictly conform to the C++ standard. That means
				37	it will reject invalid C++ code that another compiler may accept.
				38	This page helps you decide whether a Clang error message means a
				39	C++-conformance bug in your code and how you can fix it.</p>
				40
				41	<!-- ======================================================================= -->
				42	<h2 id="vla">Variable-length arrays</h2>
				43	<!-- ======================================================================= -->
				44
Douglas Gregor	0fddb97	2010-05-22 16:17:30 +0000	[diff] [blame^]	45	<p>GCC and C99 allow an array's size to be determined at run
				46	time. This extension is not permitted in standard C++. However, Clang
				47	supports such variable length arrays in very limited circumstances for
				48	compatibility with GNU C and C99 programs:</p>
				49
				50	<ul>
				51	<li>The element type of a variable length array must be a POD
				52	("plain old data") type, which means that it cannot have any
				53	user-declared constructors or destructors, base classes, or any
				54	members if non-POD type. All C types are POD types.</li>
				55
				56	<li>Variable length arrays cannot be used in conjunction with
				57	templates. For example, one cannot use a variable length array
				58	inside a template or use a variable length array type in a template
				59	argument.</li>
				60	</ul>
				61
				62	<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]	63
				64	<ol>
Douglas Gregor	0fddb97	2010-05-22 16:17:30 +0000	[diff] [blame^]	65	<li>replace the variable length array with a fixed-size array if you can
				66	determine a
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	67	reasonable upper bound at compile time; sometimes this is as
				68	simple as changing <tt>int size = ...;</tt> to <tt>const int size
				69	= ...;</tt> (if the definition of <tt>size</tt> is a compile-time
				70	integral constant);</li>
				71	<li>use an <tt>std::string</tt> instead of a <tt>char []</tt>;</li>
				72	<li>use <tt>std::vector</tt> or some other suitable container type;
				73	or</li>
				74	<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]	75	just remember to <tt>delete[]</tt> it.</li>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	76	</ol>
				77
				78	<!-- ======================================================================= -->
				79	<h2 id="init_static_const">Initialization of non-integral static const data members within a class definition</h2>
				80	<!-- ======================================================================= -->
				81
				82	The following code is ill-formed in C++'03:
				83
				84	<pre>
				85	class SomeClass {
				86	public:
				87	static const double SomeConstant = 0.5;
				88	};
				89
				90	const double SomeClass::SomeConstant;
				91	</pre>
				92
				93	Clang errors with something similar to:
				94
				95	<pre>
				96	.../your_file.h:42:42: error: 'SomeConstant' can only be initialized if it is a static const integral data member
				97	static const double SomeConstant = 0.5;
				98	^ ~~~
				99	</pre>
				100
				101	Only <i>integral</i> constant expressions are allowed as initializers
				102	within the class definition. See C++'03 [class.static.data] p4 for the
				103	details of this restriction. The fix here is straightforward: move
				104	the initializer to the definition of the static data member, which
				105	must exist outside of the class definition:
				106
				107	<pre>
				108	class SomeClass {
				109	public:
				110	static const double SomeConstant;
				111	};
				112
				113	const double SomeClass::SomeConstant<b> = 0.5</b>;
				114	</pre>
				115
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	116	Note that the forthcoming C++0x standard will allow this.
				117
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	118	<!-- ======================================================================= -->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	119	<h2 id="dep_lookup">Unqualified lookup in templates</h2>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	120	<!-- ======================================================================= -->
				121
				122	Some versions of GCC accept the following invalid code:
				123
				124	<pre>
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	125	template <typename T> struct Foo {
				126	void Work(T x) {
				127	func(x);
				128	}
				129	};
				130	...
				131	void func(int x);
				132	...
				133	template struct Foo<int>; // or anything else that instantiates Foo<int>::Work
				134	</pre>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	135
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	136	The standard says that unqualified names like <tt>func</tt> are looked up
				137	when the template is defined, not when it's instantiated. Since
				138	<tt>void func(int)</tt> was not declared yet when <tt>Foo</tt> was
				139	defined, it's not considered. The fix is usually to
				140	declare <tt>func</tt> before <tt>Foo</tt>.
				141
				142	<p>This is complicated by <i>argument-dependent lookup</i> (ADL),
				143	which is done when unqualified names are called as functions,
				144	like <tt>func(x)</tt> above. The standard says that ADL is performed
				145	in both places if any of the arguments are type-dependent, like
				146	<tt>x</tt> is in this example. However, ADL does nothing for builtin
				147	types like <tt>int</tt>, so the example is still invalid. See
				148	[basic.lookup.argdep] for more information.
				149
				150	<!-- ======================================================================= -->
				151	<h2 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h2>
				152	<!-- ======================================================================= -->
				153
				154	Some versions of GCC accept the following invalid code:
				155
				156	<pre>
				157	template <typename T> struct Base {
				158	void DoThis(T x) {}
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	159	static void DoThat(T x) {}
				160	};
				161
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	162	template <typename T> struct Derived : public Base<T> {
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	163	void Work(T x) {
				164	DoThis(x); // Invalid!
				165	DoThat(x); // Invalid!
				166	}
				167	};
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	168	</pre>
				169
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	170	Clang correctly rejects it with the following errors
				171	(when <tt>Derived</tt> is eventually instantiated):
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	172
				173	<pre>
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	174	my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	175	DoThis(x);
				176	^
				177	this->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	178	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]	179	void DoThis(T x) {}
				180	^
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	181	my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	182	DoThat(x);
				183	^
				184	this->
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	185	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]	186	static void DoThat(T x) {}
				187	</pre>
				188
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	189	Like we said <a href="#dep_lookup">above</a>, unqualified names like
				190	<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
				191	<tt>Derived</tt> is defined, not when it's instantiated. When we look
				192	up a name used in a class, we usually look into the base classes.
				193	However, we can't look into the base class <tt>Base<T></tt>
				194	because its type depends on the template argument <tt>T</tt>, so the
				195	standard says we should just ignore it. See [temp.dep]p3 for details.
				196
				197	<p>The fix, as Clang tells you, is to tell the compiler that we want a
				198	class member by prefixing the calls with <tt>this-></tt>:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	199
				200	<pre>
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	201	void Work(T x) {
				202	<b>this-></b>DoThis(x);
				203	<b>this-></b>DoThat(x);
				204	}
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	205	</pre>
				206
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	207	Alternatively, you can tell the compiler exactly where to look:
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	208
				209	<pre>
				210	void Work(T x) {
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	211	<b>Base<T></b>::DoThis(x);
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	212	<b>Base<T></b>::DoThat(x);
				213	}
				214	</pre>
				215
John McCall	489722f	2010-03-17 07:10:56 +0000	[diff] [blame]	216	This works whether the methods are static or not, but be careful:
				217	if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
				218	dispatch!
				219
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	220	<!-- ======================================================================= -->
John McCall	5dd52ac	2010-04-09 01:07:07 +0000	[diff] [blame]	221	<h2 id="bad_templates">Templates with no valid instantiations</h2>
				222	<!-- ======================================================================= -->
				223
				224	The following code contains a typo: the programmer
				225	meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
				226
				227	<pre>
				228	template <class T> class Processor {
				229	...
				230	void init();
				231	...
				232	};
				233	...
				234	template <class T> void process() {
				235	Processor<T> processor;
				236	processor.innit(); // <-- should be 'init()'
				237	...
				238	}
				239	</pre>
				240
				241	Unfortunately, we can't flag this mistake as soon as we see it: inside
				242	a template, we're not allowed to make assumptions about "dependent
				243	types" like <tt>Processor<T></tt>. Suppose that later on in
				244	this file the programmer adds an explicit specialization
				245	of <tt>Processor</tt>, like so:
				246
				247	<pre>
				248	template <> class Processor<char*> {
				249	void innit();
				250	};
				251	</pre>
				252
				253	Now the program will work — as long as the programmer only ever
				254	instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
				255	it's hard, and sometimes impossible, to diagnose mistakes in a
				256	template definition before it's instantiated.
				257
				258	<p>The standard says that a template with no valid instantiations is
				259	ill-formed. Clang tries to do as much checking as possible at
				260	definition-time instead of instantiation-time: not only does this
				261	produce clearer diagnostics, but it also substantially improves
				262	compile times when using pre-compiled headers. The downside to this
				263	philosophy is that Clang sometimes fails to process files because they
				264	contain broken templates that are no longer used. The solution is
				265	simple: since the code is unused, just remove it.
				266
				267	<!-- ======================================================================= -->
Rafael Espindola	9b2fc95	2010-03-17 04:31:53 +0000	[diff] [blame]	268	<h2 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h2>
				269	<!-- ======================================================================= -->
				270
				271	If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
				272	constructor, C++ doesn't allow you to default construct a <tt>const</tt>
				273	instance of it like this ([dcl.init], p9):
				274
				275	<pre>
				276	class Foo {
				277	public:
				278	// The compiler-supplied default constructor works fine, so we
				279	// don't bother with defining one.
				280	...
				281	};
				282
				283	void Bar() {
				284	const Foo foo; // Error!
				285	...
				286	}
				287	</pre>
				288
				289	To fix this, you can define a default constructor for the class:
				290
				291	<pre>
				292	class Foo {
				293	public:
				294	Foo() {}
				295	...
				296	};
				297
				298	void Bar() {
				299	const Foo foo; // Now the compiler is happy.
				300	...
				301	}
				302	</pre>
				303
				304	</div>
				305	</body>
				306	</html>