Blame - www/compatibility.html - platform/external/clang

blob: 783758f3ac80207e83e9011bc3290ca6971aacaa [file] [log] [blame]

Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +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>Language 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>Language Compatibility</h1>
				20	<!-- ======================================================================= -->
				21
				22	<p>Clang strives to both conform to current language standards (C99,
				23	C++98) and also to implement many widely-used extensions available
				24	in other compilers, so that most correct code will "just work" when
				25	compiler with Clang. However, Clang is more strict than other
				26	popular compilers, and may reject incorrect code that other
				27	compilers allow. This page documents common compatibility and
				28	portability issues with Clang to help you understand and fix the
				29	problem in your code when Clang emits an error message.</p>
				30
				31	<ul>
				32	<li><a href="#c">C compatibility</a>
				33	<ul>
				34	<li><a href="#inline">C99 inline functions</a></li>
Chris Lattner	a02d183	2010-09-16 18:17:55 +0000	[diff] [blame]	35	<li><a href="#vector_builtins">"missing" vector __builtin functions</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	36	<li><a href="#lvalue-cast">Lvalue casts</a></li>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	37	<li><a href="#blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</a></li>
Daniel Dunbar	15952c9	2010-11-09 22:45:16 +0000	[diff] [blame]	38	<li><a href="#block-variable-initialization">Non-initialization of <tt>__block</tt> variables</a></li>
Chris Lattner	9b743f4	2010-11-10 23:51:50 +0000	[diff] [blame]	39	<li><a href="#inline-asm">Inline assembly</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	40	</ul>
				41	</li>
				42	<li><a href="#objective-c">Objective-C compatibility</a>
				43	<ul>
				44	<li><a href="#super-cast">Cast of super</a></li>
				45	<li><a href="#sizeof-interface">Size of interfaces</a></li>
Argyrios Kyrtzidis	3b5b92a	2010-09-13 17:48:07 +0000	[diff] [blame]	46	<li><a href="#objc_objs-cast">Internal Objective-C types</a></li>
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	47	<li><a href="#c_variables-class">C variables in @class or @protocol</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	48	</ul>
				49	</li>
				50	<li><a href="#c++">C++ compatibility</a>
				51	<ul>
				52	<li><a href="#vla">Variable-length arrays</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	53	<li><a href="#dep_lookup">Unqualified lookup in templates</a></li>
				54	<li><a href="#dep_lookup_bases">Unqualified lookup into dependent bases of class templates</a></li>
				55	<li><a href="#undep_incomplete">Incomplete types in templates</a></li>
				56	<li><a href="#bad_templates">Templates with no valid instantiations</a></li>
				57	<li><a href="#default_init_const">Default initialization of const
				58	variable of a class type requires user-defined default
				59	constructor</a></li>
Douglas Gregor	a66d3bb	2010-11-10 20:24:21 +0000	[diff] [blame]	60	<li><a href="#param_name_lookup">Parameter name lookup</a></li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	61	</ul>
				62	</li>
				63	<li><a href="#objective-c++">Objective-C++ compatibility</a>
				64	<ul>
				65	<li><a href="#implicit-downcasts">Implicit downcasts</a></li>
				66	</ul>
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	67	<ul>
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	68	<li><a href="#class-as-property-name">Using <code>class</code> as a property name</a></li>
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	69	</ul>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	70	</li>
				71	</ul>
				72
				73	<!-- ======================================================================= -->
				74	<h2 id="c">C compatibility</h3>
				75	<!-- ======================================================================= -->
				76
				77	<!-- ======================================================================= -->
				78	<h3 id="inline">C99 inline functions</h3>
				79	<!-- ======================================================================= -->
				80	<p>By default, Clang builds C code according to the C99 standard,
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	81	which provides different semantics for the <code>inline</code> keyword
				82	than GCC's default behavior. For example, consider the following
				83	code:</p>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	84	<pre>
				85	inline int add(int i, int j) { return i + j; }
				86
				87	int main() {
				88	int i = add(4, 5);
				89	return i;
				90	}
				91	</pre>
				92
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	93	<p>In C99, <code>inline</code> means that a function's definition is
				94	provided only for inlining, and that there is another definition
				95	(without <code>inline</code>) somewhere else in the program. That
				96	means that this program is incomplete, because if <code>add</code>
				97	isn't inlined (for example, when compiling without optimization), then
				98	<code>main</code> will have an unresolved reference to that other
				99	definition. Therefore we'll get a (correct) link-time error like this:</p>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	100
				101	<pre>
				102	Undefined symbols:
				103	"_add", referenced from:
				104	_main in cc-y1jXIr.o
				105	</pre>
				106
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	107	<p>By contrast, GCC's default behavior follows the GNU89 dialect,
				108	which is the C89 standard plus a lot of extensions. C89 doesn't have
				109	an <code>inline</code> keyword, but GCC recognizes it as an extension
				110	and just treats it as a hint to the optimizer.</p>
				111
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	112	<p>There are several ways to fix this problem:</p>
				113
				114	<ul>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	115	<li>Change <code>add</code> to a <code>static inline</code>
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	116	function. This is usually the right solution if only one
				117	translation unit needs to use the function. <code>static
				118	inline</code> functions are always resolved within the translation
				119	unit, so you won't have to add a non-<code>inline</code> definition
				120	of the function elsewhere in your program.</li>
				121
				122	<li>Remove the <code>inline</code> keyword from this definition of
				123	<code>add</code>. The <code>inline</code> keyword is not required
				124	for a function to be inlined, nor does it guarantee that it will be.
				125	Some compilers ignore it completely. Clang treats it as a mild
				126	suggestion from the programmer.</li>
				127
				128	<li>Provide an external (non-<code>inline</code>) definition
				129	of <code>add</code> somewhere else in your program. The two
				130	definitions must be equivalent!</li>
				131
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	132	<li>Compile with the GNU89 dialect by adding
				133	<code>-std=gnu89</code> to the set of Clang options. This option is
				134	only recommended if the program source cannot be changed or if the
				135	program also relies on additional C89-specific behavior that cannot
				136	be changed.</li>
				137	</ul>
				138
John McCall	5ae84f2	2011-02-03 10:16:40 +0000	[diff] [blame]	139	<p>All of this only applies to C code; the meaning of <code>inline</code>
				140	in C++ is very different from its meaning in either GNU89 or C99.</p>
Chris Lattner	a02d183	2010-09-16 18:17:55 +0000	[diff] [blame]	141
				142	<!-- ======================================================================= -->
				143	<h3 id="vector_builtins">"missing" vector __builtin functions</h3>
				144	<!-- ======================================================================= -->
				145
				146	<p>The Intel and AMD manuals document a number "<tt><*mmintrin.h></tt>"
				147	header files, which define a standardized API for accessing vector operations
				148	on X86 CPUs. These functions have names like <tt>_mm_xor_ps</tt> and
				149	<tt>_mm256_addsub_pd</tt>. Compilers have leeway to implement these functions
				150	however they want. Since Clang supports an excellent set of <a
				151	href="../docs/LanguageExtensions.html#vectors">native vector operations</a>,
				152	the Clang headers implement these interfaces in terms of the native vector
				153	operations.
				154	</p>
				155
				156	<p>In contrast, GCC implements these functions mostly as a 1-to-1 mapping to
				157	builtin function calls, like <tt>__builtin_ia32_paddw128</tt>. These builtin
				158	functions are an internal implementation detail of GCC, and are not portable to
				159	the Intel compiler, the Microsoft compiler, or Clang. If you get build errors
				160	mentioning these, the fix is simple: switch to the *mmintrin.h functions.</p>
				161
				162	<p>The same issue occurs for NEON and Altivec for the ARM and PowerPC
				163	architectures respectively. For these, make sure to use the <arm_neon.h>
				164	and <altivec.h> headers.</p>
				165
Eric Christopher	a473c95	2010-10-25 21:17:59 +0000	[diff] [blame]	166	<p>For x86 architectures this <a href="builtins.py">script</a> should help with
				167	the manual migration process. It will rewrite your source files in place to
				168	use the APIs instead of builtin function calls. Just call it like this:</p>
				169
				170	<pre>
				171	builtins.py .c .h
				172	</pre>
				173
				174	<p>and it will rewrite all of the .c and .h files in the current directory to
				175	use the API calls instead of calls like <tt>__builtin_ia32_paddw128</tt>.</p>
Chris Lattner	a02d183	2010-09-16 18:17:55 +0000	[diff] [blame]	176
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	177	<!-- ======================================================================= -->
				178	<h3 id="lvalue-cast">Lvalue casts</h3>
				179	<!-- ======================================================================= -->
				180
Douglas Gregor	6f1adba	2010-06-30 22:38:37 +0000	[diff] [blame]	181	<p>Old versions of GCC permit casting the left-hand side of an assignment to a
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	182	different type. Clang produces an error on similar code, e.g.,</p>
				183
				184	<pre>
				185	lvalue.c:2:3: error: assignment to cast is illegal, lvalue casts are not
				186	supported
				187	(int*)addr = val;
				188	^~~~~~~~~~ ~
				189	</pre>
				190
				191	<p>To fix this problem, move the cast to the right-hand side. In this
				192	example, one could use:</p>
				193
				194	<pre>
				195	addr = (float *)val;
				196	</pre>
				197
				198	<!-- ======================================================================= -->
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	199	<h3 id="blocks-in-protected-scope">Jumps to within <tt>__block</tt> variable scope</h3>
				200	<!-- ======================================================================= -->
				201
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	202	<p>Clang disallows jumps into the scope of a <tt>__block</tt>
				203	variable. Variables marked with <tt>__block</tt> require special
				204	runtime initialization. A jump into the scope of a <tt>__block</tt>
				205	variable bypasses this initialization, leaving the variable's metadata
				206	in an invalid state. Consider the following code fragment:</p>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	207
				208	<pre>
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	209	int fetch_object_state(struct MyObject *c) {
				210	if (!c->active) goto error;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	211
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	212	__block int result;
				213	run_specially_somehow(^{ result = c->state; });
				214	return result;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	215
				216	error:
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	217	fprintf(stderr, "error while fetching object state");
				218	return -1;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	219	}
				220	</pre>
				221
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	222	<p>GCC accepts this code, but it produces code that will usually crash
				223	when <code>result</code> goes out of scope if the jump is taken. (It's
				224	possible for this bug to go undetected because it often won't crash if
				225	the stack is fresh, i.e. still zeroed.) Therefore, Clang rejects this
				226	code with a hard error:</p>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	227
				228	<pre>
				229	t.c:3:5: error: goto into protected scope
				230	goto error;
				231	^
				232	t.c:5:15: note: jump bypasses setup of __block variable
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	233	__block int result;
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	234	^
				235	</pre>
				236
John McCall	504b369	2011-02-03 10:56:31 +0000	[diff] [blame]	237	<p>The fix is to rewrite the code to not require jumping into a
				238	<tt>__block</tt> variable's scope, e.g. by limiting that scope:</p>
				239
				240	<pre>
				241	{
				242	__block int result;
				243	run_specially_somehow(^{ result = c->state; });
				244	return result;
				245	}
				246	</pre>
Daniel Dunbar	5a41021	2010-09-02 21:35:16 +0000	[diff] [blame]	247
				248	<!-- ======================================================================= -->
Daniel Dunbar	15952c9	2010-11-09 22:45:16 +0000	[diff] [blame]	249	<h3 id="block-variable-initialization">Non-initialization of <tt>__block</tt>
				250	variables</h3>
				251	<!-- ======================================================================= -->
				252
				253	<p>In the following example code, the <tt>x</tt> variable is used before it is
				254	defined:</p>
				255	<pre>
				256	int f0() {
				257	__block int x;
				258	return ^(){ return x; }();
				259	}
				260	</pre>
				261
				262	<p>By an accident of implementation, GCC and llvm-gcc unintentionally always
				263	zero initialized <tt>__block</tt> variables. However, any program which depends
				264	on this behavior is relying on unspecified compiler behavior. Programs must
				265	explicitly initialize all local block variables before they are used, as with
				266	other local variables.</p>
				267
				268	<p>Clang does not zero initialize local block variables, and programs which rely
				269	on such behavior will most likely break when built with Clang.</p>
				270
Chris Lattner	9b743f4	2010-11-10 23:51:50 +0000	[diff] [blame]	271
				272	<!-- ======================================================================= -->
				273	<h3 id="inline-asm">Inline assembly</h3>
				274	<!-- ======================================================================= -->
				275
				276	<p>In general, Clang is highly compatible with the GCC inline assembly
				277	extensions, allowing the same set of constraints, modifiers and operands as GCC
				278	inline assembly.</p>
				279
				280	<p>On targets that use the integrated assembler (such as most X86 targets),
				281	inline assembly is run through the integrated assembler instead of your system
				282	assembler (which is most commonly "gas", the GNU assembler). The LLVM
				283	integrated assembler is extremely compatible with GAS, but there are a couple of
				284	minor places where it is more picky, particularly due to outright GAS bugs.</p>
				285
				286	<p>One specific example is that the assembler rejects ambiguous X86 instructions
				287	that don't have suffixes. For example:</p>
				288
				289	<pre>
				290	asm("add %al, (%rax)");
				291	asm("addw $4, (%rax)");
				292	asm("add $4, (%rax)");
				293	</pre>
				294
				295	<p>Both clang and GAS accept the first instruction: because the first
				296	instruction uses the 8-bit <tt>%al</tt> register as an operand, it is clear that
				297	it is an 8-bit add. The second instruction is accepted by both because the "w"
				298	suffix indicates that it is a 16-bit add. The last instruction is accepted by
				299	GAS even though there is nothing that specifies the size of the instruction (and
				300	the assembler randomly picks a 32-bit add). Because it is ambiguous, Clang
				301	rejects the instruction with this error message:
				302	</p>
				303
				304	<pre>
				305	<inline asm>:3:1: error: ambiguous instructions require an explicit suffix (could be 'addb', 'addw', 'addl', or 'addq')
				306	add $4, (%rax)
				307	^
				308	1 error generated.
				309	</pre>
				310
				311	<p>To fix this compatibility issue, add an explicit suffix to the instruction:
				312	this makes your code more clear and is compatible with both GCC and Clang.</p>
				313
Daniel Dunbar	15952c9	2010-11-09 22:45:16 +0000	[diff] [blame]	314	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	315	<h2 id="objective-c">Objective-C compatibility</h3>
				316	<!-- ======================================================================= -->
				317
				318	<!-- ======================================================================= -->
				319	<h3 id="super-cast">Cast of super</h3>
				320	<!-- ======================================================================= -->
				321
				322	<p>GCC treats the <code>super</code> identifier as an expression that
				323	can, among other things, be cast to a different type. Clang treats
				324	<code>super</code> as a context-sensitive keyword, and will reject a
				325	type-cast of <code>super</code>:</p>
				326
				327	<pre>
				328	super.m:11:12: error: cannot cast 'super' (it isn't an expression)
				329	[(Super*)super add:4];
				330	~~~~~~~~^
				331	</pre>
				332
				333	<p>To fix this problem, remove the type cast, e.g.</p>
				334	<pre>
				335	[super add:4];
				336	</pre>
				337
				338	<!-- ======================================================================= -->
				339	<h3 id="sizeof-interface">Size of interfaces</h3>
				340	<!-- ======================================================================= -->
				341
				342	<p>When using the "non-fragile" Objective-C ABI in use, the size of an
				343	Objective-C class may change over time as instance variables are added
				344	(or removed). For this reason, Clang rejects the application of the
				345	<code>sizeof</code> operator to an Objective-C class when using this
				346	ABI:</p>
				347
				348	<pre>
				349	sizeof.m:4:14: error: invalid application of 'sizeof' to interface 'NSArray' in
				350	non-fragile ABI
				351	int size = sizeof(NSArray);
				352	^ ~~~~~~~~~
				353	</pre>
				354
				355	<p>Code that relies on the size of an Objective-C class is likely to
				356	be broken anyway, since that size is not actually constant. To address
				357	this problem, use the Objective-C runtime API function
Benjamin Kramer	e661750	2010-06-30 22:29:56 +0000	[diff] [blame]	358	<code>class_getInstanceSize()</code>:</p>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	359
				360	<pre>
				361	class_getInstanceSize([NSArray class])
				362	</pre>
				363
				364	<!-- ======================================================================= -->
Argyrios Kyrtzidis	3b5b92a	2010-09-13 17:48:07 +0000	[diff] [blame]	365	<h3 id="objc_objs-cast">Internal Objective-C types</h3>
				366	<!-- ======================================================================= -->
				367
				368	<p>GCC allows using pointers to internal Objective-C objects, <tt>struct objc_object*</tt>,
				369	<tt>struct objc_selector</tt>, and <tt>struct objc_class</tt> in place of the types
				370	<tt>id</tt>, <tt>SEL</tt>, and <tt>Class</tt> respectively. Clang treats the
				371	internal Objective-C structures as implementation detail and won't do implicit conversions:
				372
				373	<pre>
				374	t.mm:11:2: error: no matching function for call to 'f'
				375	f((struct objc_object *)p);
				376	^
				377	t.mm:5:6: note: candidate function not viable: no known conversion from 'struct objc_object *' to 'id' for 1st argument
				378	void f(id x);
				379	^
				380	</pre>
				381
				382	<p>Code should use types <tt>id</tt>, <tt>SEL</tt>, and <tt>Class</tt>
				383	instead of the internal types.</p>
				384
				385	<!-- ======================================================================= -->
John McCall	3cdbe44	2011-02-03 11:05:04 +0000	[diff] [blame]	386	<h3 id="c_variables-class">C variables in @interface or @protocol</h3>
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	387	<!-- ======================================================================= -->
				388
John McCall	3cdbe44	2011-02-03 11:05:04 +0000	[diff] [blame]	389	<p>GCC allows the declaration of C variables in
				390	an <code>@interface</code> or <code>@protocol</code>
				391	declaration. Clang does not allow variable declarations to appear
				392	within these declarations unless they are marked <code>extern</code>.</p>
				393
				394	<p>Variables may still be declared in an @implementation.</p>
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	395
				396	<pre>
				397	@interface XX
John McCall	3cdbe44	2011-02-03 11:05:04 +0000	[diff] [blame]	398	int a; // not allowed in clang
				399	int b = 1; // not allowed in clang
				400	extern int c; // allowed
Fariborz Jahanian	ddfa6c3	2010-10-22 22:35:51 +0000	[diff] [blame]	401	@end
				402
				403	</pre>
				404
				405	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	406	<h2 id="c++">C++ compatibility</h3>
				407	<!-- ======================================================================= -->
				408
				409	<!-- ======================================================================= -->
				410	<h3 id="vla">Variable-length arrays</h3>
				411	<!-- ======================================================================= -->
				412
				413	<p>GCC and C99 allow an array's size to be determined at run
				414	time. This extension is not permitted in standard C++. However, Clang
				415	supports such variable length arrays in very limited circumstances for
				416	compatibility with GNU C and C99 programs:</p>
				417
				418	<ul>
				419	<li>The element type of a variable length array must be a POD
				420	("plain old data") type, which means that it cannot have any
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	421	user-declared constructors or destructors, any base classes, or any
				422	members of non-POD type. All C types are POD types.</li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	423
				424	<li>Variable length arrays cannot be used as the type of a non-type
				425	template parameter.</li> </ul>
				426
				427	<p>If your code uses variable length arrays in a manner that Clang doesn't support, there are several ways to fix your code:
				428
				429	<ol>
				430	<li>replace the variable length array with a fixed-size array if you can
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	431	determine a reasonable upper bound at compile time; sometimes this is as
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	432	simple as changing <tt>int size = ...;</tt> to <tt>const int size
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	433	= ...;</tt> (if the initializer is a compile-time constant);</li>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	434	<li>use <tt>std::vector</tt> or some other suitable container type;
				435	or</li>
				436	<li>allocate the array on the heap instead using <tt>new Type[]</tt> -
				437	just remember to <tt>delete[]</tt> it.</li>
				438	</ol>
				439
				440	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	441	<h3 id="dep_lookup">Unqualified lookup in templates</h3>
				442	<!-- ======================================================================= -->
				443
				444	<p>Some versions of GCC accept the following invalid code:
				445
				446	<pre>
				447	template <typename T> T Squared(T x) {
				448	return Multiply(x, x);
				449	}
				450
				451	int Multiply(int x, int y) {
				452	return x * y;
				453	}
				454
				455	int main() {
				456	Squared(5);
				457	}
				458	</pre>
				459
				460	<p>Clang complains:
				461
Jay Foad	2a00b83	2011-06-14 12:59:25 +0000	[diff] [blame^]	462	<pre> <b>my_file.cpp:2:10: <span class="error">error:</span> call to function 'Multiply' that is neither visible in the template definition nor found by argument-dependent lookup</b>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	463	return Multiply(x, x);
				464	<span class="caret"> ^</span>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	465	<b>my_file.cpp:10:3: <span class="note">note:</span> in instantiation of function template specialization 'Squared<int>' requested here</b>
				466	Squared(5);
				467	<span class="caret"> ^</span>
Richard Smith	f50e88a	2011-06-05 22:42:48 +0000	[diff] [blame]	468	<b>my_file.cpp:5:5: <span class="note">note:</span> 'Multiply' should be declared prior to the call site</b>
				469	int Multiply(int x, int y) {
				470	<span class="caret"> ^</span>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	471	</pre>
				472
				473	<p>The C++ standard says that unqualified names like <q>Multiply</q>
				474	are looked up in two ways.
				475
				476	<p>First, the compiler does <i>unqualified lookup</i> in the scope
				477	where the name was written. For a template, this means the lookup is
				478	done at the point where the template is defined, not where it's
				479	instantiated. Since <tt>Multiply</tt> hasn't been declared yet at
				480	this point, unqualified lookup won't find it.
				481
				482	<p>Second, if the name is called like a function, then the compiler
				483	also does <i>argument-dependent lookup</i> (ADL). (Sometimes
				484	unqualified lookup can suppress ADL; see [basic.lookup.argdep]p3 for
				485	more information.) In ADL, the compiler looks at the types of all the
				486	arguments to the call. When it finds a class type, it looks up the
				487	name in that class's namespace; the result is all the declarations it
				488	finds in those namespaces, plus the declarations from unqualified
				489	lookup. However, the compiler doesn't do ADL until it knows all the
				490	argument types.
				491
				492	<p>In our example, <tt>Multiply</tt> is called with dependent
				493	arguments, so ADL isn't done until the template is instantiated. At
				494	that point, the arguments both have type <tt>int</tt>, which doesn't
				495	contain any class types, and so ADL doesn't look in any namespaces.
				496	Since neither form of lookup found the declaration
				497	of <tt>Multiply</tt>, the code doesn't compile.
				498
				499	<p>Here's another example, this time using overloaded operators,
				500	which obey very similar rules.
				501
				502	<pre>#include <iostream>
				503
				504	template<typename T>
				505	void Dump(const T& value) {
				506	std::cout << value << "\n";
				507	}
				508
				509	namespace ns {
				510	struct Data {};
				511	}
				512
				513	std::ostream& operator<<(std::ostream& out, ns::Data data) {
				514	return out << "Some data";
				515	}
				516
				517	void Use() {
				518	Dump(ns::Data());
				519	}</pre>
				520
Richard Smith	f50e88a	2011-06-05 22:42:48 +0000	[diff] [blame]	521	<p>Again, Clang complains:</p>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	522
Jay Foad	2a00b83	2011-06-14 12:59:25 +0000	[diff] [blame^]	523	<pre> <b>my_file2.cpp:5:13: <span class="error">error:</span> call to function 'operator<<' that is neither visible in the template definition nor found by argument-dependent lookup</b>
Richard Smith	f50e88a	2011-06-05 22:42:48 +0000	[diff] [blame]	524	std::cout << value << "\n";
				525	<span class="caret"> ^</span>
				526	<b>my_file2.cpp:17:3: <span class="error">note:</span> in instantiation of function template specialization 'Dump<ns::Data>' requested here</b>
				527	Dump(ns::Data());
				528	<span class="caret"> ^</span>
				529	<b>my_file2.cpp:12:15: <span class="error">note:</span> 'operator<<' should be declared prior to the call site or in namespace 'ns'</b>
				530	std::ostream& operator<<(std::ostream& out, ns::Data data) {
				531	<span class="caret"> ^</span>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	532	</pre>
				533
				534	<p>Just like before, unqualified lookup didn't find any declarations
				535	with the name <tt>operator<<</tt>. Unlike before, the argument
				536	types both contain class types: one of them is an instance of the
				537	class template type <tt>std::basic_ostream</tt>, and the other is the
				538	type <tt>ns::Data</tt> that we declared above. Therefore, ADL will
				539	look in the namespaces <tt>std</tt> and <tt>ns</tt> for
				540	an <tt>operator<<</tt>. Since one of the argument types was
				541	still dependent during the template definition, ADL isn't done until
				542	the template is instantiated during <tt>Use</tt>, which means that
				543	the <tt>operator<<</tt> we want it to find has already been
				544	declared. Unfortunately, it was declared in the global namespace, not
				545	in either of the namespaces that ADL will look in!
				546
				547	<p>There are two ways to fix this problem:</p>
				548	<ol><li>Make sure the function you want to call is declared before the
				549	template that might call it. This is the only option if none of its
				550	argument types contain classes. You can do this either by moving the
				551	template definition, or by moving the function definition, or by
				552	adding a forward declaration of the function before the template.</li>
				553	<li>Move the function into the same namespace as one of its arguments
				554	so that ADL applies.</li></ol>
				555
				556	<p>For more information about argument-dependent lookup, see
				557	[basic.lookup.argdep]. For more information about the ordering of
				558	lookup in templates, see [temp.dep.candidate].
				559
				560	<!-- ======================================================================= -->
				561	<h3 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h3>
				562	<!-- ======================================================================= -->
				563
				564	Some versions of GCC accept the following invalid code:
				565
				566	<pre>
				567	template <typename T> struct Base {
				568	void DoThis(T x) {}
				569	static void DoThat(T x) {}
				570	};
				571
				572	template <typename T> struct Derived : public Base<T> {
				573	void Work(T x) {
				574	DoThis(x); // Invalid!
				575	DoThat(x); // Invalid!
				576	}
				577	};
				578	</pre>
				579
				580	Clang correctly rejects it with the following errors
				581	(when <tt>Derived</tt> is eventually instantiated):
				582
				583	<pre>
				584	my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
				585	DoThis(x);
				586	^
				587	this->
				588	my_file.cpp:2:8: note: must qualify identifier to find this declaration in dependent base class
				589	void DoThis(T x) {}
				590	^
				591	my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
				592	DoThat(x);
				593	^
				594	this->
				595	my_file.cpp:3:15: note: must qualify identifier to find this declaration in dependent base class
				596	static void DoThat(T x) {}
				597	</pre>
				598
				599	Like we said <a href="#dep_lookup">above</a>, unqualified names like
				600	<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
				601	<tt>Derived</tt> is defined, not when it's instantiated. When we look
				602	up a name used in a class, we usually look into the base classes.
				603	However, we can't look into the base class <tt>Base<T></tt>
				604	because its type depends on the template argument <tt>T</tt>, so the
				605	standard says we should just ignore it. See [temp.dep]p3 for details.
				606
				607	<p>The fix, as Clang tells you, is to tell the compiler that we want a
				608	class member by prefixing the calls with <tt>this-></tt>:
				609
				610	<pre>
				611	void Work(T x) {
				612	<b>this-></b>DoThis(x);
				613	<b>this-></b>DoThat(x);
				614	}
				615	</pre>
				616
				617	Alternatively, you can tell the compiler exactly where to look:
				618
				619	<pre>
				620	void Work(T x) {
				621	<b>Base<T></b>::DoThis(x);
				622	<b>Base<T></b>::DoThat(x);
				623	}
				624	</pre>
				625
				626	This works whether the methods are static or not, but be careful:
				627	if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
				628	dispatch!
				629
				630	<!-- ======================================================================= -->
				631	<h3 id="undep_incomplete">Incomplete types in templates</h3>
				632	<!-- ======================================================================= -->
				633
				634	The following code is invalid, but compilers are allowed to accept it:
				635
				636	<pre>
				637	class IOOptions;
				638	template <class T> bool read(T &value) {
				639	IOOptions opts;
				640	return read(opts, value);
				641	}
				642
				643	class IOOptions { bool ForceReads; };
				644	bool read(const IOOptions &opts, int &x);
				645	template bool read<>(int &);
				646	</pre>
				647
				648	The standard says that types which don't depend on template parameters
				649	must be complete when a template is defined if they affect the
				650	program's behavior. However, the standard also says that compilers
				651	are free to not enforce this rule. Most compilers enforce it to some
				652	extent; for example, it would be an error in GCC to
				653	write <tt>opts.ForceReads</tt> in the code above. In Clang, we feel
				654	that enforcing the rule consistently lets us provide a better
				655	experience, but unfortunately it also means we reject some code that
				656	other compilers accept.
				657
				658	<p>We've explained the rule here in very imprecise terms; see
				659	[temp.res]p8 for details.
				660
				661	<!-- ======================================================================= -->
				662	<h3 id="bad_templates">Templates with no valid instantiations</h3>
				663	<!-- ======================================================================= -->
				664
				665	The following code contains a typo: the programmer
				666	meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
				667
				668	<pre>
				669	template <class T> class Processor {
				670	...
				671	void init();
				672	...
				673	};
				674	...
				675	template <class T> void process() {
				676	Processor<T> processor;
				677	processor.innit(); // <-- should be 'init()'
				678	...
				679	}
				680	</pre>
				681
				682	Unfortunately, we can't flag this mistake as soon as we see it: inside
				683	a template, we're not allowed to make assumptions about "dependent
				684	types" like <tt>Processor<T></tt>. Suppose that later on in
				685	this file the programmer adds an explicit specialization
				686	of <tt>Processor</tt>, like so:
				687
				688	<pre>
				689	template <> class Processor<char*> {
				690	void innit();
				691	};
				692	</pre>
				693
				694	Now the program will work — as long as the programmer only ever
				695	instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
				696	it's hard, and sometimes impossible, to diagnose mistakes in a
				697	template definition before it's instantiated.
				698
				699	<p>The standard says that a template with no valid instantiations is
				700	ill-formed. Clang tries to do as much checking as possible at
				701	definition-time instead of instantiation-time: not only does this
				702	produce clearer diagnostics, but it also substantially improves
				703	compile times when using pre-compiled headers. The downside to this
				704	philosophy is that Clang sometimes fails to process files because they
				705	contain broken templates that are no longer used. The solution is
				706	simple: since the code is unused, just remove it.
				707
				708	<!-- ======================================================================= -->
				709	<h3 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h3>
				710	<!-- ======================================================================= -->
				711
				712	If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
				713	constructor, C++ doesn't allow you to default construct a <tt>const</tt>
				714	instance of it like this ([dcl.init], p9):
				715
				716	<pre>
				717	class Foo {
				718	public:
				719	// The compiler-supplied default constructor works fine, so we
				720	// don't bother with defining one.
				721	...
				722	};
				723
				724	void Bar() {
				725	const Foo foo; // Error!
				726	...
				727	}
				728	</pre>
				729
				730	To fix this, you can define a default constructor for the class:
				731
				732	<pre>
				733	class Foo {
				734	public:
				735	Foo() {}
				736	...
				737	};
				738
				739	void Bar() {
				740	const Foo foo; // Now the compiler is happy.
				741	...
				742	}
				743	</pre>
				744
				745	<!-- ======================================================================= -->
Douglas Gregor	a66d3bb	2010-11-10 20:24:21 +0000	[diff] [blame]	746	<h3 id="param_name_lookup">Parameter name lookup</h3>
				747	<!-- ======================================================================= -->
				748
				749	<p>Due to a bug in its implementation, GCC allows the redeclaration of function parameter names within a function prototype in C++ code, e.g.</p>
				750	<blockquote>
				751	<pre>
				752	void f(int a, int a);
				753	</pre>
				754	</blockquote>
				755	<p>Clang diagnoses this error (where the parameter name has been redeclared). To fix this problem, rename one of the parameters.</p>
				756
				757	<!-- ======================================================================= -->
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	758	<h2 id="objective-c++">Objective-C++ compatibility</h3>
				759	<!-- ======================================================================= -->
				760
				761	<!-- ======================================================================= -->
				762	<h3 id="implicit-downcasts">Implicit downcasts</h3>
				763	<!-- ======================================================================= -->
				764
				765	<p>Due to a bug in its implementation, GCC allows implicit downcasts
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	766	of Objective-C pointers (from a base class to a derived class) when
				767	calling functions. Such code is inherently unsafe, since the object
				768	might not actually be an instance of the derived class, and is
				769	rejected by Clang. For example, given this code:</p>
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	770
				771	<pre>
				772	@interface Base @end
				773	@interface Derived : Base @end
				774
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	775	void f(Derived *p);
				776	void g(Base *p) {
				777	f(p);
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	778	}
				779	</pre>
				780
				781	<p>Clang produces the following error:</p>
				782
				783	<pre>
				784	downcast.mm:6:3: error: no matching function for call to 'f'
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	785	f(p);
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	786	^
Douglas Gregor	92bc027	2010-07-01 03:50:01 +0000	[diff] [blame]	787	downcast.mm:4:6: note: candidate function not viable: cannot convert from
				788	superclass 'Base ' to subclass 'Derived ' for 1st argument
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	789	void f(Derived *p);
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	790	^
				791	</pre>
				792
				793	<p>If the downcast is actually correct (e.g., because the code has
				794	already checked that the object has the appropriate type), add an
				795	explicit cast:</p>
				796
				797	<pre>
				798	f((Derived *)base);
				799	</pre>
				800
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	801	<!-- ======================================================================= -->
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	802	<h3 id="class-as-property-name">Using <code>class</code> as a property name</h3>
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	803	<!-- ======================================================================= -->
				804
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	805	<p>In C and Objective-C, <code>class</code> is a normal identifier and
				806	can be used to name fields, ivars, methods, and so on. In
				807	C++, <code>class</code> is a keyword. For compatibility with existing
				808	code, Clang permits <code>class</code> to be used as part of a method
				809	selector in Objective-C++, but this does not extend to any other part
				810	of the language. In particular, it is impossible to use property dot
				811	syntax in Objective-C++ with the property name <code>class</code>, so
				812	the following code will fail to parse:</p>
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	813
				814	<pre>
				815	@interface I {
				816	int cls;
				817	}
				818	+ (int)class;
				819	@end
				820
				821	@implementation I
				822	- (int) Meth { return I.class; }
				823	@end
				824	<pre>
				825
John McCall	6966c67	2011-02-03 11:29:18 +0000	[diff] [blame]	826	<p>Use explicit message-send syntax instead, i.e. <code>[I class]</code>.</p>
Fariborz Jahanian	36e738a	2010-08-11 18:57:26 +0000	[diff] [blame]	827
Douglas Gregor	c41b6ff	2010-06-30 22:01:08 +0000	[diff] [blame]	828	</div>
				829	</body>
				830	</html>