Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / cb54d4362faf9f309f371219d4311a47bdcd5b59 / . / docs / LanguageExtensions.html
blob: e9f409ace9cdf29cd9b49bed86435ced5b74da4d [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>
22<li><a href="#vectors">Vectors and Extended Vectors</a></li>
23<li><a href="#blocks">Blocks</a></li>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame^]24<li><a href="#overloading-in-c">Function Overloading in C</a></li>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]25<li><a href="#builtins">Builtin Functions</a>
26 <ul>
27 <li><a href="#__builtin_overload">__builtin_overload</a></li>
28 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
29 </ul>
30</li>
31</ul>
32
33
34<!-- ======================================================================= -->
35<h2 id="intro">Introduction</h2>
36<!-- ======================================================================= -->
37
38<p>This document describes the language extensions provided by Clang. In
39addition to the langauge extensions listed here, Clang aims to support a broad
40range of GCC extensions. Please see the <a
41href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
42more information on these extensions.</p>
43
44<!-- ======================================================================= -->
45<h2 id="vectors">Vectors and Extended Vectors</h2>
46<!-- ======================================================================= -->
47
48<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
49with V.xyzw syntax and other tidbits. See also <a
50href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
51
52<!-- ======================================================================= -->
53<h2 id="blocks">Blocks</h2>
54<!-- ======================================================================= -->
55
56<p>The idea, syntax, and semantics.</p>
57
58<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame^]59<h2 id="overloading-in-c">Function Overloading in C</h2>
60<!-- ======================================================================= -->
61
62<p>Clang provides support for C++ function overloading in C. Function overloading in C is introduced using the <tt>overloadable</tt> attribute. For example, one might provide several overloaded versions of a <tt>tgsin</tt> function that invokes the appropriate standard function computing the sine of a value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt> precision:</p>
63
64<blockquote>
65<pre>
66#include &lt;math.h&gt;
67float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
68double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
69long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
70</pre>
71</blockquote>
72
73<p>Given these declarations, one can call <tt>tgsin</tt> with a
74<tt>float</tt> value to receive a <tt>float</tt> result, with a
75<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
76overloading in C follows the rules of C++ function overloading to pick
77the best overload given the call arguments, with a few C-specific
78semantics:</p>
79<ul>
80 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
81 double</tt> is ranked as a floating-point promotion (per C99) rather
82 than as a floating-point conversion (as in C++).</li>
83
84 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
85 <tt>U*</tt> is considered a pointer conversion (with conversion
86 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
87
88 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
89 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
90 conversion is given "conversion" rank.</li>
91</ul>
92
93<p>The declaration of <tt>overloadable</tt> functions is restricted to
94function declarations and definitions. Most importantly, if any
95function with a given name is given the <tt>overloadable</tt>
96attribute, then all function declarations and definitions with that
97name (and in that scope) must have the <tt>overloadable</tt>
98attribute. This rule even applies to redeclarations of functions whose original declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
99
100<blockquote>
101<pre>
102int f(int) __attribute__((overloadable));
103float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
104
105int g(int) __attribute__((overloadable));
106int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
107</pre>
108</blockquote>
109
110<p>Functions declared with the <tt>overloadable</tt> attribute have
111their names mangled according to the same rules as C++ function
112names. For example, the three <tt>tgsin</tt> functions in our
113motivating example get the mangled names <tt>_Z5tgsinf</tt>,
114<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
115caveats to this use of name mangling:</p>
116
117<ul>
118
119 <li>Future versions of Clang may change the name mangling of
120 functions overloaded in C, so you should not depend on an specific
121 mangling. To be completely safe, we strongly urge the use of
122 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
123
124 <li>The <tt>overloadable</tt> attribute has almost no meaning when
125 used in C++, because names will already be mangled and functions are
126 already overloadable. However, when an <tt>overloadable</tt>
127 function occurs within an <tt>extern "C"</tt> linkage specification,
128 it's name <i>will</i> be mangled in the same way as it would in
129 C.</li>
130</ul>
131
132<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]133<h2 id="builtins">Builtin Functions</h2>
134<!-- ======================================================================= -->
135
136<p>Clang supports a number of builtin library functions with the same syntax as
137GCC, including things like <tt>__builtin_nan</tt>,
138<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
139<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
140addition to the GCC builtins, Clang supports a number of builtins that GCC does
141not, which are listed here.</p>
142
143<p>Please note that Clang does not and will not support all of the GCC builtins
144for vector operations. Instead of using builtins, you should use the functions
145defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
146define portable wrappers for these. Many of the Clang versions of these
147functions are implemented directly in terms of <a href="#vectors">extended
148vector support</a> instead of builtins, in order to reduce the number of
149builtins that we need to implement.</p>
150
151
152<!-- ======================================================================= -->
153<h3 id="__builtin_overload">__builtin_overload</h3>
154<!-- ======================================================================= -->
155
156<p><tt>__builtin_overload</tt> is used to implement type-generic "overloaded"
157functions in C. This builtin is used to implement the <tt>&lt;tgmath.h&gt;</tt>
158header file, but is intended to be usable for a broad variety of other similar
159situations, like the <tt>&lt;altivec.h&gt;</tt> header.
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame^]160<b>In the future, we intend to eliminate <tt>__builtin_overload</tt> in favor of <a href="#overloading-in-c">function overloading in C</a>, which provides a better solution for type-generic "overloaded" functions.</b>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]161</p>
162
163<p><b>Syntax:</b></p>
164
165<pre>
166__builtin_overload(FnNameStr, PromotionRuleStr, NumArgs, arg1, arg2, ...
167 overloadcandidate1, overloadcandidate2, ...)
168</pre>
169
170<p><b>Examples:</b></p>
171
172<pre>
173#define sin(x) \
174 (__builtin_overload("sin", "tgmath", 1, x, sinf, sin, sinl,
175 csinf, csin, csinl)(x))
176#define fma(x,y,z) \
177 (__builtin_overload("fma", "tgmath", 3, x, y, z, fmaf, fma, fmal)(x,y,z))
178#define ldexp(x, y) \
179 (__builtin_overload("ldexp", "tgmath1", 2, x, 0, ldexpf, ldexp, ldexpl)(x,y))
180</pre>
181
182<p><b>Description:</b></p>
183
184<p>The first argument to __builtin_overload is a string that is the name of the
185"function" being implemented. This is used to produce diagnostics that make
186sense to the user. For example, if you accidentally pass a pointer argument to
187"sin" in GCC, it emits 6 errors about incompatible types. This name allows
188Clang to diagnose the error in a way the user can understand.
189</p>
190
191<p>The second argument is a string that indicates a set of promotion rules to
192apply to the arguments before prototype matching occurs. The currently
193supported rules are:</p>
194
195<dl>
196 <dt>tgmath</dt>
197 <dd>Follow the rules of C99 7.22 to determine a single common type, and use it
198 for every argument.</dd>
199 <dt>tgmath1</dt>
200 <dd>Follow the rules of C99 7.22 to determine a single common type of just the
201 first argument (e.g. treat ints as doubles).</dd>
202</dl>
203
204<p>The third argument is an integer that specifies the arity of the function
205 being overloaded. After this are N expression arguments which are promoted
206 according to the rules specified by the promotion rule string.</p>
207
208<p>The final arguments are functions or function pointers with different
209 signatures. __builtin_overload will match and evaluate to the first function
210 pointer whose signature is compatible and does not cause value truncation of
211 any arguments to the function.</p>
212
213
214<!-- ======================================================================= -->
215<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
216<!-- ======================================================================= -->
217
218<p>todo describe me.</p>
219
220
221</div>
222</body>
223</html>