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

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