Gitiles
Code Review Sign In
gerrit-public.fairphone.software / toolchain / llvm-project / be829868e1846179135ff394acba4ef29b0b44d7 / . / clang / www / cxx_compatibility.html
blob: 1273ed3a8c305cb898ada5d05316bfb9a37a9fe1 [file] [log] [blame]
Rafael Espindolafcc47392010-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 McCallcb816252010-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 McCall58ec0482010-06-02 01:26:32 +0000[diff] [blame]28<li><a href="#undep_incomplete">Incomplete types in templates</a></li>
John McCall81a4a722010-04-09 01:07:07 +0000[diff] [blame]29<li><a href="#bad_templates">Templates with no valid instantiations</a></li>
Rafael Espindolafcc47392010-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 Gregor959d5a02010-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 Gregora09387d2010-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 Gregor959d5a02010-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 Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]61
62<ol>
Douglas Gregor959d5a02010-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 Espindolafcc47392010-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 Carruth7b621ea2010-03-17 05:46:21 +0000[diff] [blame]73 just remember to <tt>delete[]</tt> it.</li>
Rafael Espindolafcc47392010-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 McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]114Note that the forthcoming C++0x standard will allow this.
115
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]116<!-- ======================================================================= -->
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]117<h2 id="dep_lookup">Unqualified lookup in templates</h2>
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]118<!-- ======================================================================= -->
119
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]120<p>Some versions of GCC accept the following invalid code:
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]121
122<pre>
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]123template &lt;typename T&gt; T Squared(T x) {
124 return Multiply(x, x);
125}
126
127int Multiply(int x, int y) {
128 return x * y;
129}
130
131int main() {
132 Squared(5);
133}
134</pre>
135
136<p>Clang complains:
137
138<pre> <b>my_file.cpp:2:10: <span class="error">error:</span> use of undeclared identifier 'Multiply'</b>
139 return Multiply(x, x);
140 <span class="caret"> ^</span>
141
142 <b>my_file.cpp:10:3: <span class="note">note:</span> in instantiation of function template specialization 'Squared&lt;int&gt;' requested here</b>
143 Squared(5);
144 <span class="caret"> ^</span>
145</pre>
146
147<p>The C++ standard says that unqualified names like <q>Multiply</q>
148are looked up in two ways.
149
150<p>First, the compiler does <i>unqualified lookup</i> in the scope
151where the name was written. For a template, this means the lookup is
152done at the point where the template is defined, not where it's
153instantiated. Since <tt>Multiply</tt> hasn't been declared yet at
154this point, unqualified lookup won't find it.
155
156<p>Second, if the name is called like a function, then the compiler
157also does <i>argument-dependent lookup</i> (ADL). (Sometimes
158unqualified lookup can suppress ADL; see [basic.lookup.argdep]p3 for
159more information.) In ADL, the compiler looks at the types of all the
160arguments to the call. When it finds a class type, it looks up the
161name in that class's namespace; the result is all the declarations it
162finds in those namespaces, plus the declarations from unqualified
163lookup. However, the compiler doesn't do ADL until it knows all the
164argument types.
165
166<p>In our example, <tt>Multiply</tt> is called with dependent
167arguments, so ADL isn't done until the template is instantiated. At
168that point, the arguments both have type <tt>int</tt>, which doesn't
169contain any class types, and so ADL doesn't look in any namespaces.
170Since neither form of lookup found the declaration
171of <tt>Multiply</tt>, the code doesn't compile.
172
173<p>Here's another example, this time using overloaded operators,
174which obey very similar rules.
175
176<pre>#include &lt;iostream&gt;
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]177
John McCall89d57ae2010-06-16 08:48:08 +0000[diff] [blame]178template&lt;typename T&gt;
179void Dump(const T&amp; value) {
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]180 std::cout &lt;&lt; value &lt;&lt; "\n";
181}
182
183namespace ns {
184 struct Data {};
185}
186
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]187std::ostream&amp; operator&lt;&lt;(std::ostream&amp; out, ns::Data data) {
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]188 return out &lt;&lt; "Some data";
189}
190
191void Use() {
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]192 Dump(ns::Data());
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]193}</pre>
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]194
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]195<p>Again, Clang complains about not finding a matching function:</p>
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]196
197<pre>
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]198<b>my_file.cpp:5:13: <span class="error">error:</span> invalid operands to binary expression ('ostream' (aka 'basic_ostream&lt;char&gt;') and 'ns::Data const')</b>
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]199 std::cout &lt;&lt; value &lt;&lt; "\n";
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]200 <span class="caret">~~~~~~~~~ ^ ~~~~~</span>
201<b>my_file.cpp:17:3: <span class="note">note:</span> in instantiation of function template specialization 'Dump&lt;ns::Data&gt;' requested here</b>
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]202 Dump(ns::Data());
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]203 <span class="caret">^</span>
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]204</pre>
205
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]206<p>Just like before, unqualified lookup didn't find any declarations
207with the name <tt>operator&lt;&lt;</tt>. Unlike before, the argument
208types both contain class types: one of them is an instance of the
209class template type <tt>std::basic_ostream</tt>, and the other is the
210type <tt>ns::Data</tt> that we declared above. Therefore, ADL will
211look in the namespaces <tt>std</tt> and <tt>ns</tt> for
212an <tt>operator&lt;&lt;</tt>. Since one of the argument types was
213still dependent during the template definition, ADL isn't done until
214the template is instantiated during <tt>Use</tt>, which means that
215the <tt>operator&lt;&lt;</tt> we want it to find has already been
216declared. Unfortunately, it was declared in the global namespace, not
217in either of the namespaces that ADL will look in!
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]218
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]219<p>There are two ways to fix this problem:</p>
220<ol><li>Make sure the function you want to call is declared before the
221template that might call it. This is the only option if none of its
222argument types contain classes. You can do this either by moving the
223template definition, or by moving the function definition, or by
224adding a forward declaration of the function before the template.</li>
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]225<li>Move the function into the same namespace as one of its arguments
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]226so that ADL applies.</li></ol>
Jeffrey Yasskinbabff2c2010-06-16 01:12:12 +0000[diff] [blame]227
John McCallbe829862010-06-16 10:48:16 +0000[diff] [blame^]228<p>For more information about argument-dependent lookup, see
229[basic.lookup.argdep]. For more information about the ordering of
230lookup in templates, see [temp.dep.candidate].
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]231
232<!-- ======================================================================= -->
233<h2 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h2>
234<!-- ======================================================================= -->
235
236Some versions of GCC accept the following invalid code:
237
238<pre>
239template &lt;typename T&gt; struct Base {
240 void DoThis(T x) {}
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]241 static void DoThat(T x) {}
242};
243
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]244template &lt;typename T&gt; struct Derived : public Base&lt;T&gt; {
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]245 void Work(T x) {
246 DoThis(x); // Invalid!
247 DoThat(x); // Invalid!
248 }
249};
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]250</pre>
251
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]252Clang correctly rejects it with the following errors
253(when <tt>Derived</tt> is eventually instantiated):
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]254
255<pre>
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]256my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]257 DoThis(x);
258 ^
259 this-&gt;
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]260my_file.cpp:2:8: note: must qualify identifier to find this declaration in dependent base class
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]261 void DoThis(T x) {}
262 ^
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]263my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]264 DoThat(x);
265 ^
266 this-&gt;
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]267my_file.cpp:3:15: note: must qualify identifier to find this declaration in dependent base class
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]268 static void DoThat(T x) {}
269</pre>
270
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]271Like we said <a href="#dep_lookup">above</a>, unqualified names like
272<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
273<tt>Derived</tt> is defined, not when it's instantiated. When we look
274up a name used in a class, we usually look into the base classes.
275However, we can't look into the base class <tt>Base&lt;T&gt;</tt>
276because its type depends on the template argument <tt>T</tt>, so the
277standard says we should just ignore it. See [temp.dep]p3 for details.
278
279<p>The fix, as Clang tells you, is to tell the compiler that we want a
280class member by prefixing the calls with <tt>this-&gt;</tt>:
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]281
282<pre>
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]283 void Work(T x) {
284 <b>this-&gt;</b>DoThis(x);
285 <b>this-&gt;</b>DoThat(x);
286 }
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]287</pre>
288
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]289Alternatively, you can tell the compiler exactly where to look:
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]290
291<pre>
292 void Work(T x) {
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]293 <b>Base&lt;T&gt;</b>::DoThis(x);
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]294 <b>Base&lt;T&gt;</b>::DoThat(x);
295 }
296</pre>
297
John McCallcb816252010-03-17 07:10:56 +0000[diff] [blame]298This works whether the methods are static or not, but be careful:
299if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
300dispatch!
301
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]302<!-- ======================================================================= -->
John McCall58ec0482010-06-02 01:26:32 +0000[diff] [blame]303<h2 id="undep_incomplete">Incomplete types in templates</h2>
304<!-- ======================================================================= -->
305
306The following code is invalid, but compilers are allowed to accept it:
307
308<pre>
309 class IOOptions;
310 template &lt;class T&gt; bool read(T &amp;value) {
311 IOOptions opts;
312 return read(opts, value);
313 }
314
315 class IOOptions { bool ForceReads; };
316 bool read(const IOOptions &amp;opts, int &amp;x);
317 template bool read&lt;&gt;(int &amp;);
318</pre>
319
320The standard says that types which don't depend on template parameters
321must be complete when a template is defined if they affect the
322program's behavior. However, the standard also says that compilers
323are free to not enforce this rule. Most compilers enforce it to some
324extent; for example, it would be an error in GCC to
325write <tt>opts.ForceReads</tt> in the code above. In Clang, we feel
326that enforcing the rule consistently lets us provide a better
327experience, but unfortunately it also means we reject some code that
328other compilers accept.
329
330<p>We've explained the rule here in very imprecise terms; see
331[temp.res]p8 for details.
332
333<!-- ======================================================================= -->
John McCall81a4a722010-04-09 01:07:07 +0000[diff] [blame]334<h2 id="bad_templates">Templates with no valid instantiations</h2>
335<!-- ======================================================================= -->
336
337The following code contains a typo: the programmer
338meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
339
340<pre>
341 template &lt;class T&gt; class Processor {
342 ...
343 void init();
344 ...
345 };
346 ...
347 template &lt;class T&gt; void process() {
348 Processor&lt;T&gt; processor;
349 processor.innit(); // <-- should be 'init()'
350 ...
351 }
352</pre>
353
354Unfortunately, we can't flag this mistake as soon as we see it: inside
355a template, we're not allowed to make assumptions about "dependent
356types" like <tt>Processor&lt;T&gt;</tt>. Suppose that later on in
357this file the programmer adds an explicit specialization
358of <tt>Processor</tt>, like so:
359
360<pre>
361 template &lt;&gt; class Processor&lt;char*&gt; {
362 void innit();
363 };
364</pre>
365
366Now the program will work &mdash; as long as the programmer only ever
367instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
368it's hard, and sometimes impossible, to diagnose mistakes in a
369template definition before it's instantiated.
370
371<p>The standard says that a template with no valid instantiations is
372ill-formed. Clang tries to do as much checking as possible at
373definition-time instead of instantiation-time: not only does this
374produce clearer diagnostics, but it also substantially improves
375compile times when using pre-compiled headers. The downside to this
376philosophy is that Clang sometimes fails to process files because they
377contain broken templates that are no longer used. The solution is
378simple: since the code is unused, just remove it.
379
380<!-- ======================================================================= -->
Rafael Espindolafcc47392010-03-17 04:31:53 +0000[diff] [blame]381<h2 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h2>
382<!-- ======================================================================= -->
383
384If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
385constructor, C++ doesn't allow you to default construct a <tt>const</tt>
386instance of it like this ([dcl.init], p9):
387
388<pre>
389class Foo {
390 public:
391 // The compiler-supplied default constructor works fine, so we
392 // don't bother with defining one.
393 ...
394};
395
396void Bar() {
397 const Foo foo; // Error!
398 ...
399}
400</pre>
401
402To fix this, you can define a default constructor for the class:
403
404<pre>
405class Foo {
406 public:
407 Foo() {}
408 ...
409};
410
411void Bar() {
412 const Foo foo; // Now the compiler is happy.
413 ...
414}
415</pre>
416
417</div>
418</body>
419</html>