New language-compatibility page, including language-compatibility information for the various language dialects Clang supports in a single, easy-to-find page
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@107325 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/www/cxx_compatibility.html b/www/cxx_compatibility.html
index 1273ed3..6aa0bbf 100644
--- a/www/cxx_compatibility.html
+++ b/www/cxx_compatibility.html
@@ -2,6 +2,7 @@
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
+<meta HTTP-EQUIV="REFRESH" content="5; url=compatibility.html#c++">
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<title>Clang - C++ Compatibility</title>
<link type="text/css" rel="stylesheet" href="menu.css" />
@@ -19,401 +20,8 @@
<h1>Clang's C++ Compatibility</h1>
<!-- ======================================================================= -->
-<ul>
-<li><a href="#intro">Introduction</a></li>
-<li><a href="#vla">Variable-length arrays</a></li>
-<li><a href="#init_static_const">Initialization of non-integral static const data members within a class definition</a></li>
-<li><a href="#dep_lookup">Unqualified lookup in templates</a></li>
-<li><a href="#dep_lookup_bases">Unqualified lookup into dependent bases of class templates</a></li>
-<li><a href="#undep_incomplete">Incomplete types in templates</a></li>
-<li><a href="#bad_templates">Templates with no valid instantiations</a></li>
-<li><a href="#default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</a></li>
-</ul>
-
-<!-- ======================================================================= -->
-<h2 id="intro">Introduction</h2>
-<!-- ======================================================================= -->
-
-<p>Clang strives to strictly conform to the C++ standard. That means
-it will reject invalid C++ code that another compiler may accept.
-This page helps you decide whether a Clang error message means a
-C++-conformance bug in your code and how you can fix it.</p>
-
-<!-- ======================================================================= -->
-<h2 id="vla">Variable-length arrays</h2>
-<!-- ======================================================================= -->
-
-<p>GCC and C99 allow an array's size to be determined at run
-time. This extension is not permitted in standard C++. However, Clang
-supports such variable length arrays in very limited circumstances for
-compatibility with GNU C and C99 programs:</p>
-
-<ul>
- <li>The element type of a variable length array must be a POD
- ("plain old data") type, which means that it cannot have any
- user-declared constructors or destructors, base classes, or any
- members if non-POD type. All C types are POD types.</li>
-
- <li>Variable length arrays cannot be used as the type of a non-type
-template parameter.</li> </ul>
-
-<p>If your code uses variable length arrays in a manner that Clang doesn't support, there are several ways to fix your code:
-
-<ol>
-<li>replace the variable length array with a fixed-size array if you can
- determine a
- reasonable upper bound at compile time; sometimes this is as
- simple as changing <tt>int size = ...;</tt> to <tt>const int size
- = ...;</tt> (if the definition of <tt>size</tt> is a compile-time
- integral constant);</li>
-<li>use an <tt>std::string</tt> instead of a <tt>char []</tt>;</li>
-<li>use <tt>std::vector</tt> or some other suitable container type;
- or</li>
-<li>allocate the array on the heap instead using <tt>new Type[]</tt> -
- just remember to <tt>delete[]</tt> it.</li>
-</ol>
-
-<!-- ======================================================================= -->
-<h2 id="init_static_const">Initialization of non-integral static const data members within a class definition</h2>
-<!-- ======================================================================= -->
-
-The following code is ill-formed in C++'03:
-
-<pre>
-class SomeClass {
- public:
- static const double SomeConstant = 0.5;
-};
-
-const double SomeClass::SomeConstant;
-</pre>
-
-Clang errors with something similar to:
-
-<pre>
-.../your_file.h:42:42: error: 'SomeConstant' can only be initialized if it is a static const integral data member
- static const double SomeConstant = 0.5;
- ^ ~~~
-</pre>
-
-Only <i>integral</i> constant expressions are allowed as initializers
-within the class definition. See C++'03 [class.static.data] p4 for the
-details of this restriction. The fix here is straightforward: move
-the initializer to the definition of the static data member, which
-must exist outside of the class definition:
-
-<pre>
-class SomeClass {
- public:
- static const double SomeConstant;
-};
-
-const double SomeClass::SomeConstant<b> = 0.5</b>;
-</pre>
-
-Note that the forthcoming C++0x standard will allow this.
-
-<!-- ======================================================================= -->
-<h2 id="dep_lookup">Unqualified lookup in templates</h2>
-<!-- ======================================================================= -->
-
-<p>Some versions of GCC accept the following invalid code:
-
-<pre>
-template <typename T> T Squared(T x) {
- return Multiply(x, x);
-}
-
-int Multiply(int x, int y) {
- return x * y;
-}
-
-int main() {
- Squared(5);
-}
-</pre>
-
-<p>Clang complains:
-
-<pre> <b>my_file.cpp:2:10: <span class="error">error:</span> use of undeclared identifier 'Multiply'</b>
- return Multiply(x, x);
- <span class="caret"> ^</span>
-
- <b>my_file.cpp:10:3: <span class="note">note:</span> in instantiation of function template specialization 'Squared<int>' requested here</b>
- Squared(5);
- <span class="caret"> ^</span>
-</pre>
-
-<p>The C++ standard says that unqualified names like <q>Multiply</q>
-are looked up in two ways.
-
-<p>First, the compiler does <i>unqualified lookup</i> in the scope
-where the name was written. For a template, this means the lookup is
-done at the point where the template is defined, not where it's
-instantiated. Since <tt>Multiply</tt> hasn't been declared yet at
-this point, unqualified lookup won't find it.
-
-<p>Second, if the name is called like a function, then the compiler
-also does <i>argument-dependent lookup</i> (ADL). (Sometimes
-unqualified lookup can suppress ADL; see [basic.lookup.argdep]p3 for
-more information.) In ADL, the compiler looks at the types of all the
-arguments to the call. When it finds a class type, it looks up the
-name in that class's namespace; the result is all the declarations it
-finds in those namespaces, plus the declarations from unqualified
-lookup. However, the compiler doesn't do ADL until it knows all the
-argument types.
-
-<p>In our example, <tt>Multiply</tt> is called with dependent
-arguments, so ADL isn't done until the template is instantiated. At
-that point, the arguments both have type <tt>int</tt>, which doesn't
-contain any class types, and so ADL doesn't look in any namespaces.
-Since neither form of lookup found the declaration
-of <tt>Multiply</tt>, the code doesn't compile.
-
-<p>Here's another example, this time using overloaded operators,
-which obey very similar rules.
-
-<pre>#include <iostream>
-
-template<typename T>
-void Dump(const T& value) {
- std::cout << value << "\n";
-}
-
-namespace ns {
- struct Data {};
-}
-
-std::ostream& operator<<(std::ostream& out, ns::Data data) {
- return out << "Some data";
-}
-
-void Use() {
- Dump(ns::Data());
-}</pre>
-
-<p>Again, Clang complains about not finding a matching function:</p>
-
-<pre>
-<b>my_file.cpp:5:13: <span class="error">error:</span> invalid operands to binary expression ('ostream' (aka 'basic_ostream<char>') and 'ns::Data const')</b>
- std::cout << value << "\n";
- <span class="caret">~~~~~~~~~ ^ ~~~~~</span>
-<b>my_file.cpp:17:3: <span class="note">note:</span> in instantiation of function template specialization 'Dump<ns::Data>' requested here</b>
- Dump(ns::Data());
- <span class="caret">^</span>
-</pre>
-
-<p>Just like before, unqualified lookup didn't find any declarations
-with the name <tt>operator<<</tt>. Unlike before, the argument
-types both contain class types: one of them is an instance of the
-class template type <tt>std::basic_ostream</tt>, and the other is the
-type <tt>ns::Data</tt> that we declared above. Therefore, ADL will
-look in the namespaces <tt>std</tt> and <tt>ns</tt> for
-an <tt>operator<<</tt>. Since one of the argument types was
-still dependent during the template definition, ADL isn't done until
-the template is instantiated during <tt>Use</tt>, which means that
-the <tt>operator<<</tt> we want it to find has already been
-declared. Unfortunately, it was declared in the global namespace, not
-in either of the namespaces that ADL will look in!
-
-<p>There are two ways to fix this problem:</p>
-<ol><li>Make sure the function you want to call is declared before the
-template that might call it. This is the only option if none of its
-argument types contain classes. You can do this either by moving the
-template definition, or by moving the function definition, or by
-adding a forward declaration of the function before the template.</li>
-<li>Move the function into the same namespace as one of its arguments
-so that ADL applies.</li></ol>
-
-<p>For more information about argument-dependent lookup, see
-[basic.lookup.argdep]. For more information about the ordering of
-lookup in templates, see [temp.dep.candidate].
-
-<!-- ======================================================================= -->
-<h2 id="dep_lookup_bases">Unqualified lookup into dependent bases of class templates</h2>
-<!-- ======================================================================= -->
-
-Some versions of GCC accept the following invalid code:
-
-<pre>
-template <typename T> struct Base {
- void DoThis(T x) {}
- static void DoThat(T x) {}
-};
-
-template <typename T> struct Derived : public Base<T> {
- void Work(T x) {
- DoThis(x); // Invalid!
- DoThat(x); // Invalid!
- }
-};
-</pre>
-
-Clang correctly rejects it with the following errors
-(when <tt>Derived</tt> is eventually instantiated):
-
-<pre>
-my_file.cpp:8:5: error: use of undeclared identifier 'DoThis'
- DoThis(x);
- ^
- this->
-my_file.cpp:2:8: note: must qualify identifier to find this declaration in dependent base class
- void DoThis(T x) {}
- ^
-my_file.cpp:9:5: error: use of undeclared identifier 'DoThat'
- DoThat(x);
- ^
- this->
-my_file.cpp:3:15: note: must qualify identifier to find this declaration in dependent base class
- static void DoThat(T x) {}
-</pre>
-
-Like we said <a href="#dep_lookup">above</a>, unqualified names like
-<tt>DoThis</tt> and <tt>DoThat</tt> are looked up when the template
-<tt>Derived</tt> is defined, not when it's instantiated. When we look
-up a name used in a class, we usually look into the base classes.
-However, we can't look into the base class <tt>Base<T></tt>
-because its type depends on the template argument <tt>T</tt>, so the
-standard says we should just ignore it. See [temp.dep]p3 for details.
-
-<p>The fix, as Clang tells you, is to tell the compiler that we want a
-class member by prefixing the calls with <tt>this-></tt>:
-
-<pre>
- void Work(T x) {
- <b>this-></b>DoThis(x);
- <b>this-></b>DoThat(x);
- }
-</pre>
-
-Alternatively, you can tell the compiler exactly where to look:
-
-<pre>
- void Work(T x) {
- <b>Base<T></b>::DoThis(x);
- <b>Base<T></b>::DoThat(x);
- }
-</pre>
-
-This works whether the methods are static or not, but be careful:
-if <tt>DoThis</tt> is virtual, calling it this way will bypass virtual
-dispatch!
-
-<!-- ======================================================================= -->
-<h2 id="undep_incomplete">Incomplete types in templates</h2>
-<!-- ======================================================================= -->
-
-The following code is invalid, but compilers are allowed to accept it:
-
-<pre>
- class IOOptions;
- template <class T> bool read(T &value) {
- IOOptions opts;
- return read(opts, value);
- }
-
- class IOOptions { bool ForceReads; };
- bool read(const IOOptions &opts, int &x);
- template bool read<>(int &);
-</pre>
-
-The standard says that types which don't depend on template parameters
-must be complete when a template is defined if they affect the
-program's behavior. However, the standard also says that compilers
-are free to not enforce this rule. Most compilers enforce it to some
-extent; for example, it would be an error in GCC to
-write <tt>opts.ForceReads</tt> in the code above. In Clang, we feel
-that enforcing the rule consistently lets us provide a better
-experience, but unfortunately it also means we reject some code that
-other compilers accept.
-
-<p>We've explained the rule here in very imprecise terms; see
-[temp.res]p8 for details.
-
-<!-- ======================================================================= -->
-<h2 id="bad_templates">Templates with no valid instantiations</h2>
-<!-- ======================================================================= -->
-
-The following code contains a typo: the programmer
-meant <tt>init()</tt> but wrote <tt>innit()</tt> instead.
-
-<pre>
- template <class T> class Processor {
- ...
- void init();
- ...
- };
- ...
- template <class T> void process() {
- Processor<T> processor;
- processor.innit(); // <-- should be 'init()'
- ...
- }
-</pre>
-
-Unfortunately, we can't flag this mistake as soon as we see it: inside
-a template, we're not allowed to make assumptions about "dependent
-types" like <tt>Processor<T></tt>. Suppose that later on in
-this file the programmer adds an explicit specialization
-of <tt>Processor</tt>, like so:
-
-<pre>
- template <> class Processor<char*> {
- void innit();
- };
-</pre>
-
-Now the program will work — as long as the programmer only ever
-instantiates <tt>process()</tt> with <tt>T = char*</tt>! This is why
-it's hard, and sometimes impossible, to diagnose mistakes in a
-template definition before it's instantiated.
-
-<p>The standard says that a template with no valid instantiations is
-ill-formed. Clang tries to do as much checking as possible at
-definition-time instead of instantiation-time: not only does this
-produce clearer diagnostics, but it also substantially improves
-compile times when using pre-compiled headers. The downside to this
-philosophy is that Clang sometimes fails to process files because they
-contain broken templates that are no longer used. The solution is
-simple: since the code is unused, just remove it.
-
-<!-- ======================================================================= -->
-<h2 id="default_init_const">Default initialization of const variable of a class type requires user-defined default constructor</h2>
-<!-- ======================================================================= -->
-
-If a <tt>class</tt> or <tt>struct</tt> has no user-defined default
-constructor, C++ doesn't allow you to default construct a <tt>const</tt>
-instance of it like this ([dcl.init], p9):
-
-<pre>
-class Foo {
- public:
- // The compiler-supplied default constructor works fine, so we
- // don't bother with defining one.
- ...
-};
-
-void Bar() {
- const Foo foo; // Error!
- ...
-}
-</pre>
-
-To fix this, you can define a default constructor for the class:
-
-<pre>
-class Foo {
- public:
- Foo() {}
- ...
-};
-
-void Bar() {
- const Foo foo; // Now the compiler is happy.
- ...
-}
-</pre>
-
+ <p>The Clang C++ compatibility page has moved. You will be directed <a href="compatibility.html#c++">to its new home</a> in 5 seconds.</p>
+
</div>
</body>
</html>