Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 926df6cfabf3eaa4afc990c097fa4619b76a9b57 / . / docs / LanguageExtensions.html
blob: 8f43725d82a2d4ad99321c16b8e06160244557ca [file] [log] [blame]
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1<html>
2<head>
3<title>Clang Language Extensions</title>
4<link type="text/css" rel="stylesheet" href="../menu.css" />
5<link type="text/css" rel="stylesheet" href="../content.css" />
6<style type="text/css">
7td {
8 vertical-align: top;
9}
10</style>
11</head>
12<body>
13
14<!--#include virtual="../menu.html.incl"-->
15
16<div id="content">
17
18<h1>Clang Language Extensions</h1>
19
20<ul>
21<li><a href="#intro">Introduction</a></li>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]22<li><a href="#feature_check">Feature Checking Macros</a></li>
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]23<li><a href="#has_include">Include File Checking Macros</a></li>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]24<li><a href="#builtinmacros">Builtin Macros</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]25<li><a href="#vectors">Vectors and Extended Vectors</a></li>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]26<li><a href="#deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> attributes</a></li>
27<li><a href="#attributes-on-enumerators">Attributes on enumerators</a></li>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]28<li><a href="#checking_language_features">Checks for Standard Language Features</a></li>
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]29 <ul>
30 <li><a href="#cxx_exceptions">C++ exceptions</a></li>
31 <li><a href="#cxx_rtti">C++ RTTI</a></li>
32 </ul>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]33<li><a href="#checking_upcoming_features">Checks for Upcoming Standard Language Features</a></li>
34 <ul>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]35 <li><a href="#cxx0x">C++0x</a>
36 <ul>
37 <li><a href="#cxx_decltype">C++0x <tt>decltype()</tt></a></li>
38 <li><a href="#cxx_access_control_sfinae">C++0x SFINAE includes access control</a></li>
39 <li><a href="#cxx_alias_templates">C++0x alias templates</a></li>
40 <li><a href="#cxx_attributes">C++0x attributes</a></li>
41 <li><a href="#cxx_default_function_template_args">C++0x default template arguments in function templates</a></li>
42 <li><a href="#cxx_deleted_functions">C++0x deleted functions</a></li>
43 <li><a href="#cxx_lambdas">C++0x lambdas</a></li>
44 <li><a href="#cxx_nullptr">C++0x nullptr</a></li>
45 <li><a href="#cxx_override_control">C++0x override control</a></li>
46 <li><a href="#cxx_range_for">C++0x range-based for loop</a></li>
47 <li><a href="#cxx_rvalue_references">C++0x rvalue references</a></li>
48 <li><a href="#cxx_reference_qualified_functions">C++0x reference-qualified functions</a></li>
49 <li><a href="#cxx_static_assert">C++0x <tt>static_assert()</tt></a></li>
50 <li><a href="#cxx_auto_type">C++0x type inference</a></li>
51 <li><a href="#cxx_variadic_templates">C++0x variadic templates</a></li>
52 <li><a href="#cxx_inline_namespaces">C++0x inline namespaces</a></li>
53 <li><a href="#cxx_strong_enums">C++0x strongly-typed enumerations</a></li>
54 <li><a href="#cxx_trailing_return">C++0x trailing return type</a></li>
55 <li><a href="#cxx_noexcept">C++0x noexcept specification</a></li>
56 </ul>
57 <li><a href="#c1x">C1X</a>
58 <ul>
59 <li><a href="#c_generic_selections">C1X generic selections</a></li>
60 <li><a href="#c_static_assert">C1X <tt>_Static_assert()</tt></a></li>
61 </ul>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]62 </ul>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]63<li><a href="#checking_type_traits">Checks for Type Traits</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]64<li><a href="#blocks">Blocks</a></li>
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame^]65<li><a href="#objc_features">Objective-C Features</a>
66 <ul>
67 <li><a href="#objc_instancetype">Related result types</a></li>
68 </ul>
69</li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]70<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]71<li><a href="#builtins">Builtin Functions</a>
72 <ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]73 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]74 <li><a href="#__builtin_unreachable">__builtin_unreachable</a></li>
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]75 <li><a href="#__sync_swap">__sync_swap</a></li>
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]76 </ul>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]77</li>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]78<li><a href="#targetspecific">Target-Specific Extensions</a>
79 <ul>
80 <li><a href="#x86-specific">X86/X86-64 Language Extensions</a></li>
81 </ul>
82</li>
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]83<li><a href="#analyzerspecific">Static Analysis-Specific Extensions</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]84</ul>
85
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]86<!-- ======================================================================= -->
87<h2 id="intro">Introduction</h2>
88<!-- ======================================================================= -->
89
90<p>This document describes the language extensions provided by Clang. In
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]91addition to the language extensions listed here, Clang aims to support a broad
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]92range of GCC extensions. Please see the <a
93href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
94more information on these extensions.</p>
95
96<!-- ======================================================================= -->
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]97<h2 id="feature_check">Feature Checking Macros</h2>
98<!-- ======================================================================= -->
99
100<p>Language extensions can be very useful, but only if you know you can depend
Chris Lattnerc70e1932011-03-21 16:25:11 +0000[diff] [blame]101on them. In order to allow fine-grain features checks, we support three builtin
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]102function-like macros. This allows you to directly test for a feature in your
103code without having to resort to something like autoconf or fragile "compiler
104version checks".</p>
105
106<!-- ======================================================================= -->
107<h3 id="__has_builtin">__has_builtin</h3>
108<!-- ======================================================================= -->
109
110<p>This function-like macro takes a single identifier argument that is the name
111of a builtin function. It evaluates to 1 if the builtin is supported or 0 if
112not. It can be used like this:</p>
113
114<blockquote>
115<pre>
116#ifndef __has_builtin // Optional of course.
117 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
118#endif
119
120...
121#if __has_builtin(__builtin_trap)
122 __builtin_trap();
123#else
124 abort();
125#endif
126...
127</pre>
128</blockquote>
129
130
131<!-- ======================================================================= -->
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]132<h3 id="__has_feature_extension">__has_feature and __has_extension</h3>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]133<!-- ======================================================================= -->
134
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]135<p>These function-like macros take a single identifier argument that is the
136name of a feature. <code>__has_feature</code> evaluates to 1 if the feature
137is both supported by Clang and standardized in the current language standard
138or 0 if not (but see <a href="#has_feature_back_compat">below</a>), while
139<code>__has_extension</code> evaluates to 1 if the feature is supported by
140Clang in the current language (either as a language extension or a standard
141language feature) or 0 if not. They can be used like this:</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]142
143<blockquote>
144<pre>
145#ifndef __has_feature // Optional of course.
146 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
147#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]148#ifndef __has_extension
149 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
150#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]151
152...
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]153#if __has_feature(cxx_rvalue_references)
154// This code will only be compiled with the -std=c++0x and -std=gnu++0x
155// options, because rvalue references are only standardized in C++0x.
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]156#endif
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]157
158#if __has_extension(cxx_rvalue_references)
159// This code will be compiled with the -std=c++0x, -std=gnu++0x, -std=c++98
160// and -std=gnu++98 options, because rvalue references are supported as a
161// language extension in C++98.
162#endif
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]163</pre>
164</blockquote>
165
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]166<p id="has_feature_back_compat">For backwards compatibility reasons,
167<code>__has_feature</code> can also be used to test for support for
168non-standardized features, i.e. features not prefixed <code>c_</code>,
169<code>cxx_</code> or <code>objc_</code>.</p>
170
171<p>If the <code>-pedantic-errors</code> option is given,
172<code>__has_extension</code> is equivalent to <code>__has_feature</code>.</p>
173
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]174<p>The feature tag is described along with the language feature below.</p>
175
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]176<!-- ======================================================================= -->
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]177<h3 id="__has_attribute">__has_attribute</h3>
178<!-- ======================================================================= -->
179
180<p>This function-like macro takes a single identifier argument that is the name
181of an attribute. It evaluates to 1 if the attribute is supported or 0 if not. It
182can be used like this:</p>
183
184<blockquote>
185<pre>
186#ifndef __has_attribute // Optional of course.
187 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
188#endif
189
190...
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]191#if __has_attribute(always_inline)
192#define ALWAYS_INLINE __attribute__((always_inline))
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]193#else
Anders Carlsson961003d2011-01-24 03:54:51 +0000[diff] [blame]194#define ALWAYS_INLINE
Anders Carlssoncae50952010-10-20 02:31:43 +0000[diff] [blame]195#endif
196...
197</pre>
198</blockquote>
199
200<!-- ======================================================================= -->
John Thompson92bd8c72009-11-02 22:28:12 +0000[diff] [blame]201<h2 id="has_include">Include File Checking Macros</h2>
202<!-- ======================================================================= -->
203
204<p>Not all developments systems have the same include files.
205The <a href="#__has_include">__has_include</a> and
206<a href="#__has_include_next">__has_include_next</a> macros allow you to
207check for the existence of an include file before doing
208a possibly failing #include directive.</p>
209
210<!-- ======================================================================= -->
211<h3 id="__has_include">__has_include</h3>
212<!-- ======================================================================= -->
213
214<p>This function-like macro takes a single file name string argument that
215is the name of an include file. It evaluates to 1 if the file can
216be found using the include paths, or 0 otherwise:</p>
217
218<blockquote>
219<pre>
220// Note the two possible file name string formats.
221#if __has_include("myinclude.h") && __has_include(&lt;stdint.h&gt;)
222# include "myinclude.h"
223#endif
224
225// To avoid problem with non-clang compilers not having this macro.
226#if defined(__has_include) && __has_include("myinclude.h")
227# include "myinclude.h"
228#endif
229</pre>
230</blockquote>
231
232<p>To test for this feature, use #if defined(__has_include).</p>
233
234<!-- ======================================================================= -->
235<h3 id="__has_include_next">__has_include_next</h3>
236<!-- ======================================================================= -->
237
238<p>This function-like macro takes a single file name string argument that
239is the name of an include file. It is like __has_include except that it
240looks for the second instance of the given file found in the include
241paths. It evaluates to 1 if the second instance of the file can
242be found using the include paths, or 0 otherwise:</p>
243
244<blockquote>
245<pre>
246// Note the two possible file name string formats.
247#if __has_include_next("myinclude.h") && __has_include_next(&lt;stdint.h&gt;)
248# include_next "myinclude.h"
249#endif
250
251// To avoid problem with non-clang compilers not having this macro.
252#if defined(__has_include_next) && __has_include_next("myinclude.h")
253# include_next "myinclude.h"
254#endif
255</pre>
256</blockquote>
257
258<p>Note that __has_include_next, like the GNU extension
259#include_next directive, is intended for use in headers only,
260and will issue a warning if used in the top-level compilation
261file. A warning will also be issued if an absolute path
262is used in the file argument.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]263
264<!-- ======================================================================= -->
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]265<h2 id="builtinmacros">Builtin Macros</h2>
266<!-- ======================================================================= -->
267
Douglas Gregor4290fbd2010-04-30 02:51:06 +0000[diff] [blame]268<dl>
269 <dt><code>__BASE_FILE__</code></dt>
270 <dd>Defined to a string that contains the name of the main input
271 file passed to Clang.</dd>
272
273 <dt><code>__COUNTER__</code></dt>
274 <dd>Defined to an integer value that starts at zero and is
275 incremented each time the <code>__COUNTER__</code> macro is
276 expanded.</dd>
277
278 <dt><code>__INCLUDE_LEVEL__</code></dt>
279 <dd>Defined to an integral value that is the include depth of the
280 file currently being translated. For the main file, this value is
281 zero.</dd>
282
283 <dt><code>__TIMESTAMP__</code></dt>
284 <dd>Defined to the date and time of the last modification of the
285 current source file.</dd>
286
287 <dt><code>__clang__</code></dt>
288 <dd>Defined when compiling with Clang</dd>
289
290 <dt><code>__clang_major__</code></dt>
291 <dd>Defined to the major version number of Clang (e.g., the 2 in
292 2.0.1).</dd>
293
294 <dt><code>__clang_minor__</code></dt>
295 <dd>Defined to the minor version number of Clang (e.g., the 0 in
296 2.0.1).</dd>
297
298 <dt><code>__clang_patchlevel__</code></dt>
299 <dd>Defined to the patch level of Clang (e.g., the 1 in 2.0.1).</dd>
300
301 <dt><code>__clang_version__</code></dt>
302 <dd>Defined to a string that captures the Clang version, including
303 the Subversion tag or revision number, e.g., "1.5 (trunk
304 102332)".</dd>
305</dl>
Chris Lattner81edc9f2009-04-13 02:45:46 +0000[diff] [blame]306
307<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]308<h2 id="vectors">Vectors and Extended Vectors</h2>
309<!-- ======================================================================= -->
310
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]311<p>Supports the GCC vector extensions, plus some stuff like V[1].</p>
312
313<p>Also supports <tt>ext_vector</tt>, which additionally support for V.xyzw
314syntax and other tidbits as seen in OpenCL. An example is:</p>
315
316<blockquote>
317<pre>
318typedef float float4 <b>__attribute__((ext_vector_type(4)))</b>;
319typedef float float2 <b>__attribute__((ext_vector_type(2)))</b>;
320
321float4 foo(float2 a, float2 b) {
322 float4 c;
323 c.xz = a;
324 c.yw = b;
325 return c;
326}
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]327</pre>
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]328</blockquote>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]329
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]330<p>Query for this feature with __has_extension(attribute_ext_vector_type).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]331
Owen Andersond2bf0cd2010-01-27 01:22:36 +0000[diff] [blame]332<p>See also <a href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
333
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]334<!-- ======================================================================= -->
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]335<h2 id="deprecated">Messages on <tt>deprecated</tt> and <tt>unavailable</tt> Attributes</h2>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]336<!-- ======================================================================= -->
337
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]338<p>An optional string message can be added to the <tt>deprecated</tt>
339and <tt>unavailable</tt> attributes. For example:</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]340
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]341<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]342<pre>void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));</pre>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]343</blockquote>
344
345<p>If the deprecated or unavailable declaration is used, the message
346will be incorporated into the appropriate diagnostic:</p>
347
348<blockquote>
Chris Lattner4836d6a2010-11-09 19:43:35 +0000[diff] [blame]349<pre>harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations]
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]350 explode();
351 ^</pre>
352</blockquote>
353
354<p>Query for this feature
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]355with <tt>__has_extension(attribute_deprecated_with_message)</tt>
356and <tt>__has_extension(attribute_unavailable_with_message)</tt>.</p>
John McCall48209082010-11-08 19:48:17 +0000[diff] [blame]357
358<!-- ======================================================================= -->
359<h2 id="attributes-on-enumerators">Attributes on Enumerators</h2>
360<!-- ======================================================================= -->
361
362<p>Clang allows attributes to be written on individual enumerators.
363This allows enumerators to be deprecated, made unavailable, etc. The
364attribute must appear after the enumerator name and before any
365initializer, like so:</p>
366
367<blockquote>
368<pre>enum OperationMode {
369 OM_Invalid,
370 OM_Normal,
371 OM_Terrified __attribute__((deprecated)),
372 OM_AbortOnError __attribute__((deprecated)) = 4
373};</pre>
374</blockquote>
375
376<p>Attributes on the <tt>enum</tt> declaration do not apply to
377individual enumerators.</p>
378
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]379<p>Query for this feature with <tt>__has_extension(enumerator_attributes)</tt>.</p>
Fariborz Jahanianc784dc12010-10-06 23:12:32 +0000[diff] [blame]380
381<!-- ======================================================================= -->
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]382<h2 id="checking_language_features">Checks for Standard Language Features</h2>
383<!-- ======================================================================= -->
384
385<p>The <tt>__has_feature</tt> macro can be used to query if certain standard language features are
386enabled. Those features are listed here.</p>
387
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]388<h3 id="cxx_exceptions">C++ exceptions</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]389
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]390<p>Use <tt>__has_feature(cxx_exceptions)</tt> to determine if C++ exceptions have been enabled. For
391example, compiling code with <tt>-fexceptions</tt> enables C++ exceptions.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]392
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]393<h3 id="cxx_rtti">C++ RTTI</h3>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]394
Ted Kremenek0eb95602009-12-03 02:06:43 +0000[diff] [blame]395<p>Use <tt>__has_feature(cxx_rtti)</tt> to determine if C++ RTTI has been enabled. For example,
Ted Kremenek22c34102009-12-03 02:05:57 +0000[diff] [blame]396compiling code with <tt>-fno-rtti</tt> disables the use of RTTI.</p>
Ted Kremenek87774fd2009-12-03 02:04:01 +0000[diff] [blame]397
398<!-- ======================================================================= -->
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]399<h2 id="checking_upcoming_features">Checks for Upcoming Standard Language Features</h2>
400<!-- ======================================================================= -->
401
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]402<p>The <tt>__has_feature</tt> or <tt>__has_extension</tt> macros can be used
403to query if certain upcoming standard language features are enabled. Those
404features are listed here. Features that are not yet implemented will be
405noted.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]406
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]407<h3 id="cxx0x">C++0x</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]408
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]409<p>The features listed below are slated for inclusion in the upcoming
410C++0x standard. As a result, all these features are enabled
411with the <tt>-std=c++0x</tt> option when compiling C++ code.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]412
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]413<h4 id="cxx_decltype">C++0x <tt>decltype()</tt></h3>
414
415<p>Use <tt>__has_feature(cxx_decltype)</tt> or
416<tt>__has_extension(cxx_decltype)</tt> to determine if support for the
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]417<tt>decltype()</tt> specifier is enabled.</p>
418
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]419<h4 id="cxx_access_control_sfinae">C++0x SFINAE includes access control</h3>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]420
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]421<p>Use <tt>__has_feature(cxx_access_control_sfinae)</tt> or <tt>__has_extension(cxx_access_control_sfinae)</tt> to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170">C++ DR1170</a>.</p>
Douglas Gregor7822ee32011-05-11 23:45:11 +0000[diff] [blame]422
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]423<h4 id="cxx_alias_templates">C++0x alias templates</h3>
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]424
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]425<p>Use <tt>__has_feature(cxx_alias_templates)</tt> or
426<tt>__has_extension(cxx_alias_templates)</tt> to determine if support for
Richard Smith3e4c6c42011-05-05 21:57:07 +0000[diff] [blame]427C++0x's alias declarations and alias templates is enabled.</p>
428
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]429<h4 id="cxx_attributes">C++0x attributes</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]430
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]431<p>Use <tt>__has_feature(cxx_attributes)</tt> or
432<tt>__has_extension(cxx_attributes)</tt> to determine if support for attribute
433parsing with C++0x's square bracket notation is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]434
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]435<h4 id="cxx_default_function_template_args">C++0x default template arguments in function templates</h3>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]436
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]437<p>Use <tt>__has_feature(cxx_default_function_template_args)</tt> or
438<tt>__has_extension(cxx_default_function_template_args)</tt> to determine
439if support for default template arguments in function templates is enabled.</p>
Douglas Gregor07508002011-02-05 20:35:30 +0000[diff] [blame]440
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]441<h4 id="cxx_deleted_functions">C++0x deleted functions</tt></h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]442
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]443<p>Use <tt>__has_feature(cxx_deleted_functions)</tt> or
444<tt>__has_extension(cxx_deleted_functions)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]445deleted function definitions (with <tt>= delete</tt>) is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]446
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]447<h4 id="cxx_lambdas">C++0x lambdas</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]448
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]449<p>Use <tt>__has_feature(cxx_lambdas)</tt> or
450<tt>__has_extension(cxx_lambdas)</tt> to determine if support for lambdas
451is enabled. clang does not currently implement this feature.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]452
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]453<h4 id="cxx_nullptr">C++0x <tt>nullptr</tt></h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]454
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]455<p>Use <tt>__has_feature(cxx_nullptr)</tt> or
456<tt>__has_extension(cxx_nullptr)</tt> to determine if support for
Douglas Gregor84ee2ee2011-05-21 23:15:46 +0000[diff] [blame]457<tt>nullptr</tt> is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]458
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]459<h4 id="cxx_override_control">C++0x <tt>override control</tt></h3>
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]460
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]461<p>Use <tt>__has_feature(cxx_override_control)</tt> or
462<tt>__has_extension(cxx_override_control)</tt> to determine if support for
Anders Carlssonc8b9f792011-03-25 15:04:23 +0000[diff] [blame]463the override control keywords is enabled.</p>
464
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]465<h4 id="cxx_reference_qualified_functions">C++0x reference-qualified functions</h3>
466<p>Use <tt>__has_feature(cxx_reference_qualified_functions)</tt> or
467<tt>__has_extension(cxx_reference_qualified_functions)</tt> to determine
468if support for reference-qualified functions (e.g., member functions with
469<code>&amp;</code> or <code>&amp;&amp;</code> applied to <code>*this</code>)
470is enabled.</p>
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]471
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]472<h4 id="cxx_range_for">C++0x range-based for loop</tt></h3>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]473
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]474<p>Use <tt>__has_feature(cxx_range_for)</tt> or
475<tt>__has_extension(cxx_range_for)</tt> to determine if support for the
476range-based for loop is enabled. </p>
Richard Smitha391a462011-04-15 15:14:40 +0000[diff] [blame]477
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]478<h4 id="cxx_rvalue_references">C++0x rvalue references</tt></h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]479
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]480<p>Use <tt>__has_feature(cxx_rvalue_references)</tt> or
481<tt>__has_extension(cxx_rvalue_references)</tt> to determine if support for
Douglas Gregor56209ff2011-01-26 21:25:54 +0000[diff] [blame]482rvalue references is enabled. </p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]483
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]484<h4 id="cxx_static_assert">C++0x <tt>static_assert()</tt></h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]485
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]486<p>Use <tt>__has_feature(cxx_static_assert)</tt> or
487<tt>__has_extension(cxx_static_assert)</tt> to determine if support for
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]488compile-time assertions using <tt>static_assert</tt> is enabled.</p>
489
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]490<h4 id="cxx_auto_type">C++0x type inference</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]491
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]492<p>Use <tt>__has_feature(cxx_auto_type)</tt> or
493<tt>__has_extension(cxx_auto_type)</tt> to determine C++0x type inference is
494supported using the <tt>auto</tt> specifier. If this is disabled, <tt>auto</tt>
495will instead be a storage class specifier, as in C or C++98.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]496
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]497<h4 id="cxx_variadic_templates">C++0x variadic templates</h3>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]498
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]499<p>Use <tt>__has_feature(cxx_variadic_templates)</tt> or
500<tt>__has_extension(cxx_variadic_templates)</tt> to determine if support
Douglas Gregor83d77812011-01-19 23:15:20 +0000[diff] [blame]501for variadic templates is enabled.</p>
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]502
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]503<h4 id="cxx_inline_namespaces">C++0x inline namespaces</h3>
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]504
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]505<p>Use <tt>__has_feature(cxx_inline_namespaces)</tt> or
506<tt>__has_extension(cxx_inline_namespaces)</tt> to determine if support for
Sebastian Redlf6c09772010-08-31 23:28:47 +0000[diff] [blame]507inline namespaces is enabled.</p>
508
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]509<h4 id="cxx_trailing_return">C++0x trailing return type</h3>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]510
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]511<p>Use <tt>__has_feature(cxx_trailing_return)</tt> or
512<tt>__has_extension(cxx_trailing_return)</tt> to determine if support for the
513alternate function declaration syntax with trailing return type is enabled.</p>
Douglas Gregordab60ad2010-10-01 18:44:50 +0000[diff] [blame]514
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]515<h4 id="cxx_noexcept">C++0x noexcept</h3>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]516
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]517<p>Use <tt>__has_feature(cxx_noexcept)</tt> or
518<tt>__has_extension(cxx_noexcept)</tt> to determine if support for noexcept
519exception specifications is enabled.</p>
Sebastian Redl4561ecd2011-03-15 21:17:12 +0000[diff] [blame]520
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]521<h4 id="cxx_strong_enums">C++0x strongly typed enumerations</h3>
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]522
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]523<p>Use <tt>__has_feature(cxx_strong_enums)</tt> or
524<tt>__has_extension(cxx_strong_enums)</tt> to determine if support for
Douglas Gregor1274ccd2010-10-08 23:50:27 +0000[diff] [blame]525strongly typed, scoped enumerations is enabled.</p>
526
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]527<h3 id="c1x">C1X</h3>
528
529<p>The features listed below are slated for inclusion in the upcoming
530C1X standard. As a result, all these features are enabled
531with the <tt>-std=c1x</tt> option when compiling C code.</p>
532
533<h4 id="c_generic_selections">C1X generic selections</h2>
534
535<p>Use <tt>__has_feature(c_generic_selections)</tt> or
536<tt>__has_extension(c_generic_selections)</tt> to determine if support for
537generic selections is enabled.</p>
538
539<p>As an extension, the C1X generic selection expression is available in all
540languages supported by Clang. The syntax is the same as that given in the
541C1X draft standard.</p>
542
543<p>In C, type compatibility is decided according to the rules given in the
544appropriate standard, but in C++, which lacks the type compatibility rules
545used in C, types are considered compatible only if they are equivalent.</p>
546
547<h4 id="c_static_assert">C1X <tt>_Static_assert()</tt></h3>
548
549<p>Use <tt>__has_feature(c_static_assert)</tt> or
550<tt>__has_extension(c_static_assert)</tt> to determine if support for
551compile-time assertions using <tt>_Static_assert</tt> is enabled.</p>
552
Sean Hunt4ef4c6b2010-01-13 08:31:49 +0000[diff] [blame]553<!-- ======================================================================= -->
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]554<h2 id="checking_type_traits">Checks for Type Traits</h2>
555<!-- ======================================================================= -->
556
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]557<p>Clang supports the <a hef="http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html">GNU C++ type traits</a> and a subset of the <a href="http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx">Microsoft Visual C++ Type traits</a>. For each supported type trait <code>__X</code>, <code>__has_extension(X)</code> indicates the presence of the type trait. For example:
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]558<blockquote>
559<pre>
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]560#if __has_extension(is_convertible_to)
Douglas Gregorafdf1372011-02-03 21:57:35 +0000[diff] [blame]561template&lt;typename From, typename To&gt;
562struct is_convertible_to {
563 static const bool value = __is_convertible_to(From, To);
564};
565#else
566// Emulate type trait
567#endif
568</pre>
569</blockquote>
570
571<p>The following type traits are supported by Clang:</p>
572<ul>
573 <li><code>__has_nothrow_assign</code> (GNU, Microsoft)</li>
574 <li><code>__has_nothrow_copy</code> (GNU, Microsoft)</li>
575 <li><code>__has_nothrow_constructor</code> (GNU, Microsoft)</li>
576 <li><code>__has_trivial_assign</code> (GNU, Microsoft)</li>
577 <li><code>__has_trivial_copy</code> (GNU, Microsoft)</li>
578 <li><code>__has_trivial_constructor</code> (GNU, Microsoft)</li>
579 <li><code>__has_trivial_destructor</code> (GNU, Microsoft)</li>
580 <li><code>__has_virtual_destructor</code> (GNU, Microsoft)</li>
581 <li><code>__is_abstract</code> (GNU, Microsoft)</li>
582 <li><code>__is_base_of</code> (GNU, Microsoft)</li>
583 <li><code>__is_class</code> (GNU, Microsoft)</li>
584 <li><code>__is_convertible_to</code> (Microsoft)</li>
585 <li><code>__is_empty</code> (GNU, Microsoft)</li>
586 <li><code>__is_enum</code> (GNU, Microsoft)</li>
587 <li><code>__is_pod</code> (GNU, Microsoft)</li>
588 <li><code>__is_polymorphic</code> (GNU, Microsoft)</li>
589 <li><code>__is_union</code> (GNU, Microsoft)</li>
590 <li><code>__is_literal(type)</code>: Determines whether the given type is a literal type</li>
591</ul>
592
593<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]594<h2 id="blocks">Blocks</h2>
595<!-- ======================================================================= -->
596
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame]597<p>The syntax and high level language feature description is in <a
598href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
599details for the clang implementation are in <a
Chris Lattner5d7650b2010-03-16 21:43:03 +0000[diff] [blame]600href="Block-ABI-Apple.txt">Block-ABI-Apple.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]601
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]602
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]603<p>Query for this feature with __has_extension(blocks).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]604
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]605<!-- ======================================================================= -->
Douglas Gregor926df6c2011-06-11 01:09:30 +0000[diff] [blame^]606<h2 id="objc_features">Objective-C Features</h2>
607<!-- ======================================================================= -->
608
609<h3 id="objc_instancetype">Related result types</h3>
610
611<p>According to Cocoa conventions, Objective-C methods with certain names ("init", "alloc", etc.) always return objects that are an instance of the receiving class's type. Such methods are said to have a "related result type", meaning that a message send to one of these methods will have the same static type as an instance of the receiver class. For example, given the following classes:</p>
612
613<blockquote>
614<pre>
615@interface NSObject
616+ (id)alloc;
617- (id)init;
618@end
619
620@interface NSArray : NSObject
621@end
622</pre>
623</blockquote>
624
625<p>and this common initialization pattern</p>
626
627<blockquote>
628<pre>
629NSArray *array = [[NSArray alloc] init];
630</pre>
631</blockquote>
632
633<p>the type of the expression <code>[NSArray alloc]</code> is
634<code>NSArray*</code> because <code>alloc</code> implicitly has a
635related result type. Similarly, the type of the expression
636<code>[[NSArray alloc] init]</code> is <code>NSArray*</code>, since
637<code>init</code> has a related result type and its receiver is known
638to have the type <code>NSArray *</code>. If neither <code>alloc</code> nor <code>init</code> had a related result type, the expressions would have had type <code>id</code>, as declared in the method signature.</p>
639
640<p>To determine whether a method has a related result type, the first
641word in the camel-case selector (e.g., "init" in "initWithObjects") is
642considered, and the method will a related result type if its return
643type is compatible with the type of its class and if
644
645<ul>
646
647 <li>the first word is "alloc" or "new", and the method is a class
648 method, or</li>
649
650 <li>the first word is "autorelease", "init", "retain", or "self",
651 and the method is an instance method.</li>
652
653</ul></p>
654
655<p>If a method with a related result type is overridden by a subclass
656method, the subclass method must also return a type that is compatible
657with the subclass type. For example:</p>
658
659<blockquote>
660<pre>
661@interface NSString : NSObject
662- (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
663@end
664</pre>
665</blockquote>
666
667<p>Related result types only affect the type of a message send or
668property access via the given method. In all other respects, a method
669with a related result type is treated the same way as method without a
670related result type.</p>
671
672<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]673<h2 id="overloading-in-c">Function Overloading in C</h2>
674<!-- ======================================================================= -->
675
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]676<p>Clang provides support for C++ function overloading in C. Function
677overloading in C is introduced using the <tt>overloadable</tt> attribute. For
678example, one might provide several overloaded versions of a <tt>tgsin</tt>
679function that invokes the appropriate standard function computing the sine of a
680value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
681precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]682
683<blockquote>
684<pre>
685#include &lt;math.h&gt;
686float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
687double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
688long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
689</pre>
690</blockquote>
691
692<p>Given these declarations, one can call <tt>tgsin</tt> with a
693<tt>float</tt> value to receive a <tt>float</tt> result, with a
694<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
695overloading in C follows the rules of C++ function overloading to pick
696the best overload given the call arguments, with a few C-specific
697semantics:</p>
698<ul>
699 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
700 double</tt> is ranked as a floating-point promotion (per C99) rather
701 than as a floating-point conversion (as in C++).</li>
702
703 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
704 <tt>U*</tt> is considered a pointer conversion (with conversion
705 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
706
707 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
708 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
709 conversion is given "conversion" rank.</li>
710</ul>
711
712<p>The declaration of <tt>overloadable</tt> functions is restricted to
713function declarations and definitions. Most importantly, if any
714function with a given name is given the <tt>overloadable</tt>
715attribute, then all function declarations and definitions with that
716name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]717attribute. This rule even applies to redeclarations of functions whose original
718declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]719
720<blockquote>
721<pre>
722int f(int) __attribute__((overloadable));
723float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
724
725int g(int) __attribute__((overloadable));
726int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
727</pre>
728</blockquote>
729
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]730<p>Functions marked <tt>overloadable</tt> must have
731prototypes. Therefore, the following code is ill-formed:</p>
732
733<blockquote>
734<pre>
735int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
736</pre>
737</blockquote>
738
739<p>However, <tt>overloadable</tt> functions are allowed to use a
740ellipsis even if there are no named parameters (as is permitted in C++). This feature is particularly useful when combined with the <tt>unavailable</tt> attribute:</p>
741
742<blockquote>
743<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]744void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]745</pre>
746</blockquote>
747
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]748<p>Functions declared with the <tt>overloadable</tt> attribute have
749their names mangled according to the same rules as C++ function
750names. For example, the three <tt>tgsin</tt> functions in our
751motivating example get the mangled names <tt>_Z5tgsinf</tt>,
Chris Lattner71b48d62010-11-28 18:19:13 +0000[diff] [blame]752<tt>_Z5tgsind</tt>, and <tt>_Z5tgsine</tt>, respectively. There are two
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]753caveats to this use of name mangling:</p>
754
755<ul>
756
757 <li>Future versions of Clang may change the name mangling of
758 functions overloaded in C, so you should not depend on an specific
759 mangling. To be completely safe, we strongly urge the use of
760 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
761
762 <li>The <tt>overloadable</tt> attribute has almost no meaning when
763 used in C++, because names will already be mangled and functions are
764 already overloadable. However, when an <tt>overloadable</tt>
765 function occurs within an <tt>extern "C"</tt> linkage specification,
766 it's name <i>will</i> be mangled in the same way as it would in
767 C.</li>
768</ul>
769
Peter Collingbournec1b5fa42011-05-13 20:54:45 +0000[diff] [blame]770<p>Query for this feature with __has_extension(attribute_overloadable).</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]771
772
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]773<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]774<h2 id="builtins">Builtin Functions</h2>
775<!-- ======================================================================= -->
776
777<p>Clang supports a number of builtin library functions with the same syntax as
778GCC, including things like <tt>__builtin_nan</tt>,
779<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
780<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
781addition to the GCC builtins, Clang supports a number of builtins that GCC does
782not, which are listed here.</p>
783
784<p>Please note that Clang does not and will not support all of the GCC builtins
785for vector operations. Instead of using builtins, you should use the functions
786defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
787define portable wrappers for these. Many of the Clang versions of these
788functions are implemented directly in terms of <a href="#vectors">extended
789vector support</a> instead of builtins, in order to reduce the number of
790builtins that we need to implement.</p>
791
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]792<!-- ======================================================================= -->
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]793<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]794<!-- ======================================================================= -->
795
Chris Lattneraad826b2009-09-16 18:56:12 +0000[diff] [blame]796<p><tt>__builtin_shufflevector</tt> is used to express generic vector
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]797permutation/shuffle/swizzle operations. This builtin is also very important for
798the implementation of various target-specific header files like
799<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]800</p>
801
802<p><b>Syntax:</b></p>
803
804<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]805__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]806</pre>
807
808<p><b>Examples:</b></p>
809
810<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]811 // Identity operation - return 4-element vector V1.
812 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
813
814 // "Splat" element 0 of V1 into a 4-element result.
815 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
816
817 // Reverse 4-element vector V1.
818 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
819
820 // Concatenate every other element of 4-element vectors V1 and V2.
821 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
822
823 // Concatenate every other element of 8-element vectors V1 and V2.
824 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]825</pre>
826
827<p><b>Description:</b></p>
828
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]829<p>The first two arguments to __builtin_shufflevector are vectors that have the
830same element type. The remaining arguments are a list of integers that specify
831the elements indices of the first two vectors that should be extracted and
832returned in a new vector. These element indices are numbered sequentially
833starting with the first vector, continuing into the second vector. Thus, if
834vec1 is a 4-element vector, index 5 would refer to the second element of vec2.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]835</p>
836
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]837<p>The result of __builtin_shufflevector is a vector
838with the same element type as vec1/vec2 but that has an element count equal to
839the number of indices specified.
840</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]841
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]842<p>Query for this feature with __has_builtin(__builtin_shufflevector).</p>
843
844<!-- ======================================================================= -->
845<h3 id="__builtin_unreachable">__builtin_unreachable</h3>
846<!-- ======================================================================= -->
847
848<p><tt>__builtin_unreachable</tt> is used to indicate that a specific point in
849the program cannot be reached, even if the compiler might otherwise think it
850can. This is useful to improve optimization and eliminates certain warnings.
851For example, without the <tt>__builtin_unreachable</tt> in the example below,
852the compiler assumes that the inline asm can fall through and prints a "function
853declared 'noreturn' should not return" warning.
854</p>
855
856<p><b>Syntax:</b></p>
857
858<pre>
859__builtin_unreachable()
860</pre>
861
862<p><b>Example of Use:</b></p>
863
864<pre>
865void myabort(void) __attribute__((noreturn));
866void myabort(void) {
867 asm("int3");
868 __builtin_unreachable();
869}
870</pre>
871
872<p><b>Description:</b></p>
873
874<p>The __builtin_unreachable() builtin has completely undefined behavior. Since
875it has undefined behavior, it is a statement that it is never reached and the
876optimizer can take advantage of this to produce better code. This builtin takes
877no arguments and produces a void result.
878</p>
879
880<p>Query for this feature with __has_builtin(__builtin_unreachable).</p>
881
Chris Lattner23aa9c82011-04-09 03:57:26 +0000[diff] [blame]882<!-- ======================================================================= -->
883<h3 id="__sync_swap">__sync_swap</h3>
884<!-- ======================================================================= -->
885
886<p><tt>__sync_swap</tt> is used to atomically swap integers or pointers in
887memory.
888</p>
889
890<p><b>Syntax:</b></p>
891
892<pre>
893<i>type</i> __sync_swap(<i>type</i> *ptr, <i>type</i> value, ...)
894</pre>
895
896<p><b>Example of Use:</b></p>
897
898<pre>
899int old_value = __sync_swap(&value, new_value);
900</pre>
901
902<p><b>Description:</b></p>
903
904<p>The __sync_swap() builtin extends the existing __sync_*() family of atomic
905intrinsics to allow code to atomically swap the current value with the new
906value. More importantly, it helps developers write more efficient and correct
907code by avoiding expensive loops around __sync_bool_compare_and_swap() or
908relying on the platform specific implementation details of
909__sync_lock_test_and_set(). The __sync_swap() builtin is a full barrier.
910</p>
911
Chris Lattner21190d52009-09-21 03:09:59 +0000[diff] [blame]912
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]913<!-- ======================================================================= -->
914<h2 id="targetspecific">Target-Specific Extensions</h2>
915<!-- ======================================================================= -->
916
917<p>Clang supports some language features conditionally on some targets.</p>
918
919<!-- ======================================================================= -->
920<h3 id="x86-specific">X86/X86-64 Language Extensions</h3>
921<!-- ======================================================================= -->
922
923<p>The X86 backend has these language extensions:</p>
924
925<!-- ======================================================================= -->
926<h4 id="x86-gs-segment">Memory references off the GS segment</h4>
927<!-- ======================================================================= -->
928
929<p>Annotating a pointer with address space #256 causes it to be code generated
Chris Lattnera021e7c2009-05-05 18:54:47 +0000[diff] [blame]930relative to the X86 GS segment register, and address space #257 causes it to be
931relative to the X86 FS segment. Note that this is a very very low-level
932feature that should only be used if you know what you're doing (for example in
933an OS kernel).</p>
Chris Lattner1177f912009-04-09 19:58:15 +0000[diff] [blame]934
935<p>Here is an example:</p>
936
937<pre>
938#define GS_RELATIVE __attribute__((address_space(256)))
939int foo(int GS_RELATIVE *P) {
940 return *P;
941}
942</pre>
943
944<p>Which compiles to (on X86-32):</p>
945
946<pre>
947_foo:
948 movl 4(%esp), %eax
949 movl %gs:(%eax), %eax
950 ret
951</pre>
952
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]953<!-- ======================================================================= -->
954<h2 id="analyzerspecific">Static Analysis-Specific Extensions</h2>
955<!-- ======================================================================= -->
956
957<p>Clang supports additional attributes that are useful for documenting program
958invariants and rules for static analysis tools. The extensions documented here
959are used by the <a
960href="http://clang.llvm.org/StaticAnalysis.html">path-sensitive static analyzer
961engine</a> that is part of Clang's Analysis library.</p>
962
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]963<h3 id="attr_analyzer_noreturn">The <tt>analyzer_noreturn</tt> attribute</h3>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]964
965<p>Clang's static analysis engine understands the standard <tt>noreturn</tt>
Ted Kremenek4df21142009-04-10 05:04:22 +0000[diff] [blame]966attribute. This attribute, which is typically affixed to a function prototype,
967indicates that a call to a given function never returns. Function prototypes for
968common functions like <tt>exit</tt> are typically annotated with this attribute,
969as well as a variety of common assertion handlers. Users can educate the static
970analyzer about their own custom assertion handles (thus cutting down on false
971positives due to false paths) by marking their own &quot;panic&quot; functions
972with this attribute.</p>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]973
974<p>While useful, <tt>noreturn</tt> is not applicable in all cases. Sometimes
Nick Lewycky625b5862009-06-14 04:08:08 +0000[diff] [blame]975there are special functions that for all intents and purposes should be
976considered panic functions (i.e., they are only called when an internal program
977error occurs) but may actually return so that the program can fail gracefully.
978The <tt>analyzer_noreturn</tt> attribute allows one to annotate such functions
979as being interpreted as &quot;no return&quot; functions by the analyzer (thus
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]980pruning bogus paths) but will not affect compilation (as in the case of
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]981<tt>noreturn</tt>).</p>
982
983<p><b>Usage</b>: The <tt>analyzer_noreturn</tt> attribute can be placed in the
Chris Lattner28935892009-04-10 05:54:56 +0000[diff] [blame]984same places where the <tt>noreturn</tt> attribute can be placed. It is commonly
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]985placed at the end of function prototypes:</p>
986
987<pre>
988 void foo() <b>__attribute__((analyzer_noreturn))</b>;
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]989</pre>
990
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]991<p>Query for this feature with
992<tt>__has_attribute(analyzer_noreturn)</tt>.</p>
Chris Lattner148772a2009-06-13 07:13:28 +0000[diff] [blame]993
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]994<h3 id="attr_method_family">The <tt>objc_method_family</tt> attribute</h3>
995
996<p>Many methods in Objective-C have conventional meanings determined
997by their selectors. For the purposes of static analysis, it is
998sometimes useful to be able to mark a method as having a particular
999conventional meaning despite not having the right selector, or as not
1000having the conventional meaning that its selector would suggest.
1001For these use cases, we provide an attribute to specifically describe
1002the <q>method family</q> that a method belongs to.</p>
1003
1004<p><b>Usage</b>: <tt>__attribute__((objc_method_family(X)))</tt>,
1005where <tt>X</tt> is one of <tt>none</tt>, <tt>alloc</tt>, <tt>copy</tt>,
1006<tt>init</tt>, <tt>mutableCopy</tt>, or <tt>new</tt>. This attribute
1007can only be placed at the end of a method declaration:</p>
1008
1009<pre>
1010 - (NSString*) initMyStringValue <b>__attribute__((objc_method_family(none)))</b>;
1011</pre>
1012
1013<p>Users who do not wish to change the conventional meaning of a
1014method, and who merely want to document its non-standard retain and
1015release semantics, should use the
1016<a href="#attr_retain_release">retaining behavior attributes</a>
1017described below.</p>
1018
1019<p>Query for this feature with
1020<tt>__has_attribute(objc_method_family)</tt>.</p>
1021
1022<h3 id="attr_retain_release">Objective-C retaining behavior attributes</h3>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1023
1024<p>In Objective-C, functions and methods are generally assumed to take
1025and return objects with +0 retain counts, with some exceptions for
1026special methods like <tt>+alloc</tt> and <tt>init</tt>. However,
1027there are exceptions, and so Clang provides attributes to allow these
1028exceptions to be documented, which helps the analyzer find leaks (and
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1029ignore non-leaks). Some exceptions may be better described using
1030the <a href="#attr_method_family"><tt>objc_method_family</tt></a>
1031attribute instead.</p>
John McCall630b7ae2011-01-25 04:26:21 +0000[diff] [blame]1032
1033<p><b>Usage</b>: The <tt>ns_returns_retained</tt>, <tt>ns_returns_not_retained</tt>,
1034<tt>ns_returns_autoreleased</tt>, <tt>cf_returns_retained</tt>,
1035and <tt>cf_returns_not_retained</tt> attributes can be placed on
1036methods and functions that return Objective-C or CoreFoundation
1037objects. They are commonly placed at the end of a function prototype
1038or method declaration:</p>
1039
1040<pre>
1041 id foo() <b>__attribute__((ns_returns_retained))</b>;
1042
1043 - (NSString*) bar: (int) x <b>__attribute__((ns_returns_retained))</b>;
1044</pre>
1045
1046<p>The <tt>*_returns_retained</tt> attributes specify that the
1047returned object has a +1 retain count.
1048The <tt>*_returns_not_retained</tt> attributes specify that the return
1049object has a +0 retain count, even if the normal convention for its
1050selector would be +1. <tt>ns_returns_autoreleased</tt> specifies that the
1051returned object is +0, but is guaranteed to live at least as long as the
1052next flush of an autorelease pool.</p>
1053
1054<p><b>Usage</b>: The <tt>ns_consumed</tt> and <tt>cf_consumed</tt>
1055attributes can be placed on an parameter declaration; they specify
1056that the argument is expected to have a +1 retain count, which will be
1057balanced in some way by the function or method.
1058The <tt>ns_consumes_self</tt> attribute can only be placed on an
1059Objective-C method; it specifies that the method expects
1060its <tt>self</tt> parameter to have a +1 retain count, which it will
1061balance in some way.</p>
1062
1063<pre>
1064 void <b>foo(__attribute__((ns_consumed))</b> NSString *string);
1065
1066 - (void) bar <b>__attribute__((ns_consumes_self))</b>;
1067 - (void) baz: (id) <b>__attribute__((ns_consumed))</b> x;
1068</pre>
Ted Kremeneked869312009-04-10 05:03:33 +0000[diff] [blame]1069
John McCall87494012011-03-18 03:51:49 +0000[diff] [blame]1070<p>Query for these features with <tt>__has_attribute(ns_consumed)</tt>,
1071<tt>__has_attribute(ns_returns_retained)</tt>, etc.</p>
1072
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]1073</div>
1074</body>
1075</html>