Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / a7dbdf5c76d5da124f9384012c89eb1602de58e2 / . / docs / LanguageExtensions.html
blob: 5b8518b33054b0ae0d5f7cec428bc96c6457dc63 [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>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]27 <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
28 </ul>
29</li>
30</ul>
31
32
33<!-- ======================================================================= -->
34<h2 id="intro">Introduction</h2>
35<!-- ======================================================================= -->
36
37<p>This document describes the language extensions provided by Clang. In
38addition to the langauge extensions listed here, Clang aims to support a broad
39range of GCC extensions. Please see the <a
40href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
41more information on these extensions.</p>
42
43<!-- ======================================================================= -->
44<h2 id="vectors">Vectors and Extended Vectors</h2>
45<!-- ======================================================================= -->
46
47<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
48with V.xyzw syntax and other tidbits. See also <a
49href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>
50
51<!-- ======================================================================= -->
52<h2 id="blocks">Blocks</h2>
53<!-- ======================================================================= -->
54
Chris Lattnera7dbdf52009-03-09 07:03:22 +0000[diff] [blame^]55<p>The syntax and high level language feature description is in <a
56href="BlockLanguageSpec.txt">BlockLanguageSpec.txt</a>. Implementation and ABI
57details for the clang implementation are in <a
58href="BlockImplementation.txt">BlockImplementation.txt</a>.</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]59
60<!-- ======================================================================= -->
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]61<h2 id="overloading-in-c">Function Overloading in C</h2>
62<!-- ======================================================================= -->
63
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]64<p>Clang provides support for C++ function overloading in C. Function
65overloading in C is introduced using the <tt>overloadable</tt> attribute. For
66example, one might provide several overloaded versions of a <tt>tgsin</tt>
67function that invokes the appropriate standard function computing the sine of a
68value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt>
69precision:</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]70
71<blockquote>
72<pre>
73#include &lt;math.h&gt;
74float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
75double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
76long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
77</pre>
78</blockquote>
79
80<p>Given these declarations, one can call <tt>tgsin</tt> with a
81<tt>float</tt> value to receive a <tt>float</tt> result, with a
82<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
83overloading in C follows the rules of C++ function overloading to pick
84the best overload given the call arguments, with a few C-specific
85semantics:</p>
86<ul>
87 <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
88 double</tt> is ranked as a floating-point promotion (per C99) rather
89 than as a floating-point conversion (as in C++).</li>
90
91 <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
92 <tt>U*</tt> is considered a pointer conversion (with conversion
93 rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>
94
95 <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
96 is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
97 conversion is given "conversion" rank.</li>
98</ul>
99
100<p>The declaration of <tt>overloadable</tt> functions is restricted to
101function declarations and definitions. Most importantly, if any
102function with a given name is given the <tt>overloadable</tt>
103attribute, then all function declarations and definitions with that
104name (and in that scope) must have the <tt>overloadable</tt>
Chris Lattnerf161d412009-02-13 21:51:45 +0000[diff] [blame]105attribute. This rule even applies to redeclarations of functions whose original
106declaration had the <tt>overloadable</tt> attribute, e.g.,</p>
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]107
108<blockquote>
109<pre>
110int f(int) __attribute__((overloadable));
111float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>
112
113int g(int) __attribute__((overloadable));
114int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
115</pre>
116</blockquote>
117
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]118<p>Functions marked <tt>overloadable</tt> must have
119prototypes. Therefore, the following code is ill-formed:</p>
120
121<blockquote>
122<pre>
123int h() __attribute__((overloadable)); <i>// error: h does not have a prototype</i>
124</pre>
125</blockquote>
126
127<p>However, <tt>overloadable</tt> functions are allowed to use a
128ellipsis 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>
129
130<blockquote>
131<pre>
Chris Lattner02246802009-02-18 22:27:46 +0000[diff] [blame]132void honeypot(...) __attribute__((overloadable, unavailable)); <i>// calling me is an error</i>
Douglas Gregor965acbb2009-02-18 07:07:28 +0000[diff] [blame]133</pre>
134</blockquote>
135
Douglas Gregorcb54d432009-02-13 00:57:04 +0000[diff] [blame]136<p>Functions declared with the <tt>overloadable</tt> attribute have
137their names mangled according to the same rules as C++ function
138names. For example, the three <tt>tgsin</tt> functions in our
139motivating example get the mangled names <tt>_Z5tgsinf</tt>,
140<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
141caveats to this use of name mangling:</p>
142
143<ul>
144
145 <li>Future versions of Clang may change the name mangling of
146 functions overloaded in C, so you should not depend on an specific
147 mangling. To be completely safe, we strongly urge the use of
148 <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>
149
150 <li>The <tt>overloadable</tt> attribute has almost no meaning when
151 used in C++, because names will already be mangled and functions are
152 already overloadable. However, when an <tt>overloadable</tt>
153 function occurs within an <tt>extern "C"</tt> linkage specification,
154 it's name <i>will</i> be mangled in the same way as it would in
155 C.</li>
156</ul>
157
158<!-- ======================================================================= -->
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]159<h2 id="builtins">Builtin Functions</h2>
160<!-- ======================================================================= -->
161
162<p>Clang supports a number of builtin library functions with the same syntax as
163GCC, including things like <tt>__builtin_nan</tt>,
164<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
165<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
166addition to the GCC builtins, Clang supports a number of builtins that GCC does
167not, which are listed here.</p>
168
169<p>Please note that Clang does not and will not support all of the GCC builtins
170for vector operations. Instead of using builtins, you should use the functions
171defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
172define portable wrappers for these. Many of the Clang versions of these
173functions are implemented directly in terms of <a href="#vectors">extended
174vector support</a> instead of builtins, in order to reduce the number of
175builtins that we need to implement.</p>
176
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]177<!-- ======================================================================= -->
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]178<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]179<!-- ======================================================================= -->
180
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]181<p><tt>__builtin_shufflevector</tt> is used to expression generic vector
182permutation/shuffle/swizzle operations. This builtin is also very important for
183the implementation of various target-specific header files like
184<tt>&lt;xmmintrin.h&gt;</tt>.
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]185</p>
186
187<p><b>Syntax:</b></p>
188
189<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]190__builtin_shufflevector(vec1, vec2, index1, index2, ...)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]191</pre>
192
193<p><b>Examples:</b></p>
194
195<pre>
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]196 // Identity operation - return 4-element vector V1.
197 __builtin_shufflevector(V1, V1, 0, 1, 2, 3)
198
199 // "Splat" element 0 of V1 into a 4-element result.
200 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
201
202 // Reverse 4-element vector V1.
203 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
204
205 // Concatenate every other element of 4-element vectors V1 and V2.
206 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
207
208 // Concatenate every other element of 8-element vectors V1 and V2.
209 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]210</pre>
211
212<p><b>Description:</b></p>
213
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]214<p>The first two arguments to __builtin_shufflevector are vectors that have the
215same element type. The remaining arguments are a list of integers that specify
216the elements indices of the first two vectors that should be extracted and
217returned in a new vector. These element indices are numbered sequentially
218starting with the first vector, continuing into the second vector. Thus, if
219vec1 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]220</p>
221
Chris Lattner6f72da52009-02-13 20:00:20 +0000[diff] [blame]222<p>The result of __builtin_shufflevector is a vector
223with the same element type as vec1/vec2 but that has an element count equal to
224the number of indices specified.
225</p>
Chris Lattner5ce933f2009-02-09 08:46:11 +0000[diff] [blame]226
227</div>
228</body>
229</html>