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