Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / f44ea727c0f632f9b6a262cf36dd5c9323c2467f / . / www / cxx_compatibility.html
blob: 46e3a9f909146f43d629647c949ed963e78f0678 [file] [log] [blame]
Rafael Espindola9b2fc952010-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 McCall489722f2010-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 McCall4a40a2f2010-06-02 01:26:32 +0000[diff] [blame]28<li><a href="#undep_incomplete">Incomplete types in templates</a></li>
John McCall5dd52ac2010-04-09 01:07:07 +0000[diff] [blame]29<li><a href="#bad_templates">Templates with no valid instantiations</a></li>
Rafael Espindola9b2fc952010-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
38it will reject invalid C++ code that another compiler may accept.
39This page helps you decide whether a Clang error message means a
40C++-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 Gregor0fddb972010-05-22 16:17:30 +0000[diff] [blame]46<p>GCC and C99 allow an array's size to be determined at run
47time. This extension is not permitted in standard C++. However, Clang
48supports such variable length arrays in very limited circumstances for
49compatibility 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 Gregora481ec42010-05-23 19:57:01 +0000[diff] [blame]57 <li>Variable length arrays cannot be used as the type of a non-type
58template parameter.</li> </ul>
Douglas Gregor0fddb972010-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 Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]61
62<ol>
Douglas Gregor0fddb972010-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 Espindola9b2fc952010-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 Carruth6243e332010-03-17 05:46:21 +0000[diff] [blame]73 just remember to <tt>delete[]</tt> it.</li>
Rafael Espindola9b2fc952010-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
80The following code is ill-formed in C++'03:
81
82<pre>
83class SomeClass {
84 public:
85 static const double SomeConstant = 0.5;
86};
87
88const double SomeClass::SomeConstant;
89</pre>
90
91Clang 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
99Only <i>integral</i> constant expressions are allowed as initializers
100within the class definition. See C++'03 [class.static.data] p4 for the
101details of this restriction. The fix here is straightforward: move
102the initializer to the definition of the static data member, which
103must exist outside of the class definition:
104
105<pre>
106class SomeClass {
107 public:
108 static const double SomeConstant;
109};
110
111const double SomeClass::SomeConstant<b> = 0.5</b>;
112</pre>
113
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]114Note that the forthcoming C++0x standard will allow this.
115
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]116<!-- ======================================================================= -->
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]117<h2 id="dep_lookup">Unqualified lookup in templates</h2>
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]118<!-- ======================================================================= -->
119
Jeffrey Yasskinf44ea722010-06-16 01:12:12 +0000[diff] [blame^]120<p>Some versions of GCC accept the following invalid code:
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]121
122<pre>
Jeffrey Yasskinf44ea722010-06-16 01:12:12 +0000[diff] [blame^]123#include &lt;iostream>
124#include &lt;utility>
125
126template&lt;typename T>
127void Dump(const T& value) {
128 std::cout &lt;&lt; value &lt;&lt; "\n";
129}
130
131namespace ns {
132 struct Data {};
133}
134
135std::ostream& operator&lt;&lt;(std::ostream& out, ns::Data) {
136 return out &lt;&lt; "Some data";
137}
138
139void Use() {
140 Dump(std::make_pair(3, 4.5));
141 Dump(ns::Data());
142}
143
144template&lt;typename T, typename U>
145std::ostream& operator&lt;&lt;(std::ostream& out, const std::pair&lt;T, U>& p) {
146 return out &lt;&lt; '(' &lt;&lt; p.first &lt;&lt; ", " &lt;&lt; p.second &lt;&lt; ")";
147}
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]148</pre>
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]149
Jeffrey Yasskinf44ea722010-06-16 01:12:12 +0000[diff] [blame^]150<p>Clang complains:</p>
151
152<pre>
153<b>test.cc:6:13: <span class=error>error:</span> invalid operands to binary expression ('ostream' (aka 'basic_ostream&lt;char>') and 'std::pair&lt;int, double> const')</b>
154 std::cout &lt;&lt; value &lt;&lt; "\n";
155 <span class=caret>~~~~~~~~~ ^ ~~~~~</span>
156<b>test.cc:18:3: note:</b> in instantiation of function template specialization 'Dump&lt;std::pair&lt;int, double> >' requested here
157 Dump(std::make_pair(3, 4.5));
158 <span class=caret>^</span>
159<b>test.cc:6:13: <span class=error>error:</span> invalid operands to binary expression ('ostream' (aka 'basic_ostream&lt;char>') and 'ns::Data const')</b>
160 std::cout &lt;&lt; value &lt;&lt; "\n";
161 <span class=caret>~~~~~~~~~ ^ ~~~~~</span>
162<b>test.cc:19:3: note:</b> in instantiation of function template specialization 'Dump&lt;ns::Data>' requested here
163 Dump(ns::Data());
164 <span class=caret>^</span>
1652 errors generated.
166</pre>
167
168<p>The standard, in [temp.dep.candidate], says that unqualified names
169like <tt>operator&lt;&lt;</tt> are looked up when the template is
170defined, not when it's instantiated. Since
171<tt>operator&lt;&lt;(std::ostream&, const std::pair&lt;>&)</tt>
172and <tt>operator&lt;&lt;(std::ostream&, ns::Data)</tt> were not
173declared yet when <tt>Dump</tt> was defined, they're not considered.
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]174
175<p>This is complicated by <i>argument-dependent lookup</i> (ADL),
176which is done when unqualified names are called as functions,
Jeffrey Yasskinf44ea722010-06-16 01:12:12 +0000[diff] [blame^]177like <tt>operator&lt;&lt;</tt> above. The standard says that ADL is
178performed in both places if any of the arguments are type-dependent,
179like <tt>value</tt> and <tt>p</tt> are in this example.
180
181<p>The fix is usually to</p>
182<ol><li>Add a declaration before the use of the function,
183<li>Move the definition to before the use of the function, or
184<li>Move the function into the same namespace as one of its arguments
185so that ADL applies. (Note that it still needs to be declared before
186the template is <i>instantiated</i>, and that ADL doesn't apply to
187built-in types.)
188</ol>
189
190<pre>
191#include &lt;iostream>
192#include &lt;utility>
193
194template&lt;typename T, typename U> // Fix 2
195std::ostream& operator&lt;&lt;(std::ostream& out, const std::pair&lt;T, U>& p) {
196 return out &lt;&lt; '(' &lt;&lt; p.first &lt;&lt; ", " &lt;&lt; p.second &lt;&lt; ")";
197}
198
199template&lt;typename T>
200void Dump(const T& value) {
201 std::cout &lt;&lt; value &lt;&lt; "\n";
202}
203
204namespace ns {
205 struct Data {};
206
207 std::ostream& operator&lt;&lt;(std::ostream& out, Data) { // Fix 3
208 return out &lt;&lt; "Some data";
209 }
210}
211
212void Use() {
213 Dump(std::make_pair(3, 4.5));
214 Dump(ns::Data());
215}
216</pre>
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]217
218<!-- ======================================================================= -->
219<h2 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h2>
220<!-- ======================================================================= -->
221
222Some versions of GCC accept the following invalid code:
223
224<pre>
225template &lt;typename T&gt; struct Base {
226 void DoThis(T x) {}
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]227 static void DoThat(T x) {}
228};
229
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]230template &lt;typename T&gt; struct Derived : public Base&lt;T&gt; {
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]231 void Work(T x) {
232 DoThis(x); // Invalid!
233 DoThat(x); // Invalid!
234 }
235};
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]236</pre>
237
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]238Clang correctly rejects it with the following errors
239(when <tt>Derived</tt> is eventually instantiated):
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]240
241<pre>
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]242my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]243 DoThis(x);
244 ^
245 this-&gt;
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]246my_file.cpp:2:8: note: must qualify identifier to find this declaration in dependent base class
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]247 void DoThis(T x) {}
248 ^
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]249my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]250 DoThat(x);
251 ^
252 this-&gt;
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]253my_file.cpp:3:15: note: must qualify identifier to find this declaration in dependent base class
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]254 static void DoThat(T x) {}
255</pre>
256
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]257Like we said <a href="#dep_lookup">above</a>, unqualified names like
258<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
259<tt>Derived</tt> is defined, not when it's instantiated. When we look
260up a name used in a class, we usually look into the base classes.
261However, we can't look into the base class <tt>Base&lt;T&gt;</tt>
262because its type depends on the template argument <tt>T</tt>, so the
263standard says we should just ignore it. See [temp.dep]p3 for details.
264
265<p>The fix, as Clang tells you, is to tell the compiler that we want a
266class member by prefixing the calls with <tt>this-&gt;</tt>:
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]267
268<pre>
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]269 void Work(T x) {
270 <b>this-&gt;</b>DoThis(x);
271 <b>this-&gt;</b>DoThat(x);
272 }
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]273</pre>
274
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]275Alternatively, you can tell the compiler exactly where to look:
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]276
277<pre>
278 void Work(T x) {
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]279 <b>Base&lt;T&gt;</b>::DoThis(x);
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]280 <b>Base&lt;T&gt;</b>::DoThat(x);
281 }
282</pre>
283
John McCall489722f2010-03-17 07:10:56 +0000[diff] [blame]284This works whether the methods are static or not, but be careful:
285if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
286dispatch!
287
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]288<!-- ======================================================================= -->
John McCall4a40a2f2010-06-02 01:26:32 +0000[diff] [blame]289<h2 id="undep_incomplete">Incomplete types in templates</h2>
290<!-- ======================================================================= -->
291
292The following code is invalid, but compilers are allowed to accept it:
293
294<pre>
295 class IOOptions;
296 template &lt;class T&gt; bool read(T &amp;value) {
297 IOOptions opts;
298 return read(opts, value);
299 }
300
301 class IOOptions { bool ForceReads; };
302 bool read(const IOOptions &amp;opts, int &amp;x);
303 template bool read&lt;&gt;(int &amp;);
304</pre>
305
306The standard says that types which don't depend on template parameters
307must be complete when a template is defined if they affect the
308program's behavior. However, the standard also says that compilers
309are free to not enforce this rule. Most compilers enforce it to some
310extent; for example, it would be an error in GCC to
311write <tt>opts.ForceReads</tt> in the code above. In Clang, we feel
312that enforcing the rule consistently lets us provide a better
313experience, but unfortunately it also means we reject some code that
314other compilers accept.
315
316<p>We've explained the rule here in very imprecise terms; see
317[temp.res]p8 for details.
318
319<!-- ======================================================================= -->
John McCall5dd52ac2010-04-09 01:07:07 +0000[diff] [blame]320<h2 id="bad_templates">Templates with no valid instantiations</h2>
321<!-- ======================================================================= -->
322
323The following code contains a typo: the programmer
324meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
325
326<pre>
327 template &lt;class T&gt; class Processor {
328 ...
329 void init();
330 ...
331 };
332 ...
333 template &lt;class T&gt; void process() {
334 Processor&lt;T&gt; processor;
335 processor.innit(); // <-- should be 'init()'
336 ...
337 }
338</pre>
339
340Unfortunately, we can't flag this mistake as soon as we see it: inside
341a template, we're not allowed to make assumptions about "dependent
342types" like <tt>Processor&lt;T&gt;</tt>. Suppose that later on in
343this file the programmer adds an explicit specialization
344of <tt>Processor</tt>, like so:
345
346<pre>
347 template &lt;&gt; class Processor&lt;char*&gt; {
348 void innit();
349 };
350</pre>
351
352Now the program will work &mdash; as long as the programmer only ever
353instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
354it's hard, and sometimes impossible, to diagnose mistakes in a
355template definition before it's instantiated.
356
357<p>The standard says that a template with no valid instantiations is
358ill-formed. Clang tries to do as much checking as possible at
359definition-time instead of instantiation-time: not only does this
360produce clearer diagnostics, but it also substantially improves
361compile times when using pre-compiled headers. The downside to this
362philosophy is that Clang sometimes fails to process files because they
363contain broken templates that are no longer used. The solution is
364simple: since the code is unused, just remove it.
365
366<!-- ======================================================================= -->
Rafael Espindola9b2fc952010-03-17 04:31:53 +0000[diff] [blame]367<h2 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h2>
368<!-- ======================================================================= -->
369
370If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
371constructor, C++ doesn't allow you to default construct a <tt>const</tt>
372instance of it like this ([dcl.init], p9):
373
374<pre>
375class Foo {
376 public:
377 // The compiler-supplied default constructor works fine, so we
378 // don't bother with defining one.
379 ...
380};
381
382void Bar() {
383 const Foo foo; // Error!
384 ...
385}
386</pre>
387
388To fix this, you can define a default constructor for the class:
389
390<pre>
391class Foo {
392 public:
393 Foo() {}
394 ...
395};
396
397void Bar() {
398 const Foo foo; // Now the compiler is happy.
399 ...
400}
401</pre>
402
403</div>
404</body>
405</html>