-
Notifications
You must be signed in to change notification settings - Fork 10.8k
/
LanguageExtensions.rst
5258 lines (3918 loc) · 194 KB
/
LanguageExtensions.rst
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
=========================
Clang Language Extensions
=========================
.. contents::
:local:
:depth: 1
.. toctree::
:hidden:
ObjectiveCLiterals
BlockLanguageSpec
Block-ABI-Apple
AutomaticReferenceCounting
MatrixTypes
Introduction
============
This document describes the language extensions provided by Clang. In addition
to the language extensions listed here, Clang aims to support a broad range of
GCC extensions. Please see the `GCC manual
<https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on
these extensions.
.. _langext-feature_check:
Feature Checking Macros
=======================
Language extensions can be very useful, but only if you know you can depend on
them. In order to allow fine-grain features checks, we support three builtin
function-like macros. This allows you to directly test for a feature in your
code without having to resort to something like autoconf or fragile "compiler
version checks".
``__has_builtin``
-----------------
This function-like macro takes a single identifier argument that is the name of
a builtin function, a builtin pseudo-function (taking one or more type
arguments), or a builtin template.
It evaluates to 1 if the builtin is supported or 0 if not.
It can be used like this:
.. code-block:: c++
#ifndef __has_builtin // Optional of course.
#define __has_builtin(x) 0 // Compatibility with non-clang compilers.
#endif
...
#if __has_builtin(__builtin_trap)
__builtin_trap();
#else
abort();
#endif
...
.. note::
Prior to Clang 10, ``__has_builtin`` could not be used to detect most builtin
pseudo-functions.
``__has_builtin`` should not be used to detect support for a builtin macro;
use ``#ifdef`` instead.
``__has_constexpr_builtin``
---------------------------
This function-like macro takes a single identifier argument that is the name of
a builtin function, a builtin pseudo-function (taking one or more type
arguments), or a builtin template.
It evaluates to 1 if the builtin is supported and can be constant evaluated or
0 if not. It can be used for writing conditionally constexpr code like this:
.. code-block:: c++
#ifndef __has_constexpr_builtin // Optional of course.
#define __has_constexpr_builtin(x) 0 // Compatibility with non-clang compilers.
#endif
...
#if __has_constexpr_builtin(__builtin_fmax)
constexpr
#endif
double money_fee(double amount) {
return __builtin_fmax(amount * 0.03, 10.0);
}
...
For example, ``__has_constexpr_builtin`` is used in libcxx's implementation of
the ``<cmath>`` header file to conditionally make a function constexpr whenever
the constant evaluation of the corresponding builtin (for example,
``std::fmax`` calls ``__builtin_fmax``) is supported in Clang.
.. _langext-__has_feature-__has_extension:
``__has_feature`` and ``__has_extension``
-----------------------------------------
These function-like macros take a single identifier argument that is the name
of a feature. ``__has_feature`` evaluates to 1 if the feature is both
supported by Clang and standardized in the current language standard or 0 if
not (but see :ref:`below <langext-has-feature-back-compat>`), while
``__has_extension`` evaluates to 1 if the feature is supported by Clang in the
current language (either as a language extension or a standard language
feature) or 0 if not. They can be used like this:
.. code-block:: c++
#ifndef __has_feature // Optional of course.
#define __has_feature(x) 0 // Compatibility with non-clang compilers.
#endif
#ifndef __has_extension
#define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
#endif
...
#if __has_feature(cxx_rvalue_references)
// This code will only be compiled with the -std=c++11 and -std=gnu++11
// options, because rvalue references are only standardized in C++11.
#endif
#if __has_extension(cxx_rvalue_references)
// This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
// and -std=gnu++98 options, because rvalue references are supported as a
// language extension in C++98.
#endif
.. _langext-has-feature-back-compat:
For backward compatibility, ``__has_feature`` can also be used to test
for support for non-standardized features, i.e. features not prefixed ``c_``,
``cxx_`` or ``objc_``.
Another use of ``__has_feature`` is to check for compiler features not related
to the language standard, such as e.g. :doc:`AddressSanitizer
<AddressSanitizer>`.
If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent
to ``__has_feature``.
The feature tag is described along with the language feature below.
The feature name or extension name can also be specified with a preceding and
following ``__`` (double underscore) to avoid interference from a macro with
the same name. For instance, ``__cxx_rvalue_references__`` can be used instead
of ``cxx_rvalue_references``.
``__has_cpp_attribute``
-----------------------
This function-like macro is available in C++20 by default, and is provided as an
extension in earlier language standards. It takes a single argument that is the
name of a double-square-bracket-style attribute. The argument can either be a
single identifier or a scoped identifier. If the attribute is supported, a
nonzero value is returned. If the attribute is a standards-based attribute, this
macro returns a nonzero value based on the year and month in which the attribute
was voted into the working draft. See `WG21 SD-6
<https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations>`_
for the list of values returned for standards-based attributes. If the attribute
is not supported by the current compilation target, this macro evaluates to 0.
It can be used like this:
.. code-block:: c++
#ifndef __has_cpp_attribute // For backwards compatibility
#define __has_cpp_attribute(x) 0
#endif
...
#if __has_cpp_attribute(clang::fallthrough)
#define FALLTHROUGH [[clang::fallthrough]]
#else
#define FALLTHROUGH
#endif
...
The attribute scope tokens ``clang`` and ``_Clang`` are interchangeable, as are
the attribute scope tokens ``gnu`` and ``__gnu__``. Attribute tokens in either
of these namespaces can be specified with a preceding and following ``__``
(double underscore) to avoid interference from a macro with the same name. For
instance, ``gnu::__const__`` can be used instead of ``gnu::const``.
``__has_c_attribute``
---------------------
This function-like macro takes a single argument that is the name of an
attribute exposed with the double square-bracket syntax in C mode. The argument
can either be a single identifier or a scoped identifier. If the attribute is
supported, a nonzero value is returned. If the attribute is not supported by the
current compilation target, this macro evaluates to 0. It can be used like this:
.. code-block:: c
#ifndef __has_c_attribute // Optional of course.
#define __has_c_attribute(x) 0 // Compatibility with non-clang compilers.
#endif
...
#if __has_c_attribute(fallthrough)
#define FALLTHROUGH [[fallthrough]]
#else
#define FALLTHROUGH
#endif
...
The attribute scope tokens ``clang`` and ``_Clang`` are interchangeable, as are
the attribute scope tokens ``gnu`` and ``__gnu__``. Attribute tokens in either
of these namespaces can be specified with a preceding and following ``__``
(double underscore) to avoid interference from a macro with the same name. For
instance, ``gnu::__const__`` can be used instead of ``gnu::const``.
``__has_attribute``
-------------------
This function-like macro takes a single identifier argument that is the name of
a GNU-style attribute. It evaluates to 1 if the attribute is supported by the
current compilation target, or 0 if not. It can be used like this:
.. code-block:: c++
#ifndef __has_attribute // Optional of course.
#define __has_attribute(x) 0 // Compatibility with non-clang compilers.
#endif
...
#if __has_attribute(always_inline)
#define ALWAYS_INLINE __attribute__((always_inline))
#else
#define ALWAYS_INLINE
#endif
...
The attribute name can also be specified with a preceding and following ``__``
(double underscore) to avoid interference from a macro with the same name. For
instance, ``__always_inline__`` can be used instead of ``always_inline``.
``__has_declspec_attribute``
----------------------------
This function-like macro takes a single identifier argument that is the name of
an attribute implemented as a Microsoft-style ``__declspec`` attribute. It
evaluates to 1 if the attribute is supported by the current compilation target,
or 0 if not. It can be used like this:
.. code-block:: c++
#ifndef __has_declspec_attribute // Optional of course.
#define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers.
#endif
...
#if __has_declspec_attribute(dllexport)
#define DLLEXPORT __declspec(dllexport)
#else
#define DLLEXPORT
#endif
...
The attribute name can also be specified with a preceding and following ``__``
(double underscore) to avoid interference from a macro with the same name. For
instance, ``__dllexport__`` can be used instead of ``dllexport``.
``__is_identifier``
-------------------
This function-like macro takes a single identifier argument that might be either
a reserved word or a regular identifier. It evaluates to 1 if the argument is just
a regular identifier and not a reserved word, in the sense that it can then be
used as the name of a user-defined function or variable. Otherwise it evaluates
to 0. It can be used like this:
.. code-block:: c++
...
#ifdef __is_identifier // Compatibility with non-clang compilers.
#if __is_identifier(__wchar_t)
typedef wchar_t __wchar_t;
#endif
#endif
__wchar_t WideCharacter;
...
Include File Checking Macros
============================
Not all developments systems have the same include files. The
:ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow
you to check for the existence of an include file before doing a possibly
failing ``#include`` directive. Include file checking macros must be used
as expressions in ``#if`` or ``#elif`` preprocessing directives.
.. _langext-__has_include:
``__has_include``
-----------------
This function-like macro takes a single file name string argument that is the
name of an include file. It evaluates to 1 if the file can be found using the
include paths, or 0 otherwise:
.. code-block:: c++
// Note the two possible file name string formats.
#if __has_include("myinclude.h") && __has_include(<stdint.h>)
# include "myinclude.h"
#endif
To test for this feature, use ``#if defined(__has_include)``:
.. code-block:: c++
// To avoid problem with non-clang compilers not having this macro.
#if defined(__has_include)
#if __has_include("myinclude.h")
# include "myinclude.h"
#endif
#endif
.. _langext-__has_include_next:
``__has_include_next``
----------------------
This function-like macro takes a single file name string argument that is the
name of an include file. It is like ``__has_include`` except that it looks for
the second instance of the given file found in the include paths. It evaluates
to 1 if the second instance of the file can be found using the include paths,
or 0 otherwise:
.. code-block:: c++
// Note the two possible file name string formats.
#if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
# include_next "myinclude.h"
#endif
// To avoid problem with non-clang compilers not having this macro.
#if defined(__has_include_next)
#if __has_include_next("myinclude.h")
# include_next "myinclude.h"
#endif
#endif
Note that ``__has_include_next``, like the GNU extension ``#include_next``
directive, is intended for use in headers only, and will issue a warning if
used in the top-level compilation file. A warning will also be issued if an
absolute path is used in the file argument.
``__has_warning``
-----------------
This function-like macro takes a string literal that represents a command line
option for a warning and returns true if that is a valid warning option.
.. code-block:: c++
#if __has_warning("-Wformat")
...
#endif
.. _languageextensions-builtin-macros:
Builtin Macros
==============
``__BASE_FILE__``
Defined to a string that contains the name of the main input file passed to
Clang.
``__FILE_NAME__``
Clang-specific extension that functions similar to ``__FILE__`` but only
renders the last path component (the filename) instead of an invocation
dependent full path to that file.
``__COUNTER__``
Defined to an integer value that starts at zero and is incremented each time
the ``__COUNTER__`` macro is expanded.
``__INCLUDE_LEVEL__``
Defined to an integral value that is the include depth of the file currently
being translated. For the main file, this value is zero.
``__TIMESTAMP__``
Defined to the date and time of the last modification of the current source
file.
``__clang__``
Defined when compiling with Clang
``__clang_major__``
Defined to the major marketing version number of Clang (e.g., the 2 in
2.0.1). Note that marketing version numbers should not be used to check for
language features, as different vendors use different numbering schemes.
Instead, use the :ref:`langext-feature_check`.
``__clang_minor__``
Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note
that marketing version numbers should not be used to check for language
features, as different vendors use different numbering schemes. Instead, use
the :ref:`langext-feature_check`.
``__clang_patchlevel__``
Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
``__clang_version__``
Defined to a string that captures the Clang marketing version, including the
Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``".
``__clang_literal_encoding__``
Defined to a narrow string literal that represents the current encoding of
narrow string literals, e.g., ``"hello"``. This macro typically expands to
"UTF-8" (but may change in the future if the
``-fexec-charset="Encoding-Name"`` option is implemented.)
``__clang_wide_literal_encoding__``
Defined to a narrow string literal that represents the current encoding of
wide string literals, e.g., ``L"hello"``. This macro typically expands to
"UTF-16" or "UTF-32" (but may change in the future if the
``-fwide-exec-charset="Encoding-Name"`` option is implemented.)
.. _langext-vectors:
Vectors and Extended Vectors
============================
Supports the GCC, OpenCL, AltiVec, NEON and SVE vector extensions.
OpenCL vector types are created using the ``ext_vector_type`` attribute. It
supports the ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example
is:
.. code-block:: c++
typedef float float4 __attribute__((ext_vector_type(4)));
typedef float float2 __attribute__((ext_vector_type(2)));
float4 foo(float2 a, float2 b) {
float4 c;
c.xz = a;
c.yw = b;
return c;
}
Query for this feature with ``__has_attribute(ext_vector_type)``.
Giving ``-maltivec`` option to clang enables support for AltiVec vector syntax
and functions. For example:
.. code-block:: c++
vector float foo(vector int a) {
vector int b;
b = vec_add(a, a) + a;
return (vector float)b;
}
NEON vector types are created using ``neon_vector_type`` and
``neon_polyvector_type`` attributes. For example:
.. code-block:: c++
typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
int8x8_t foo(int8x8_t a) {
int8x8_t v;
v = a;
return v;
}
GCC vector types are created using the ``vector_size(N)`` attribute. The
argument ``N`` specifies the number of bytes that will be allocated for an
object of this type. The size has to be multiple of the size of the vector
element type. For example:
.. code-block:: c++
// OK: This declares a vector type with four 'int' elements
typedef int int4 __attribute__((vector_size(4 * sizeof(int))));
// ERROR: '11' is not a multiple of sizeof(int)
typedef int int_impossible __attribute__((vector_size(11)));
int4 foo(int4 a) {
int4 v;
v = a;
return v;
}
Boolean Vectors
---------------
Clang also supports the ext_vector_type attribute with boolean element types in
C and C++. For example:
.. code-block:: c++
// legal for Clang, error for GCC:
typedef bool bool4 __attribute__((ext_vector_type(4)));
// Objects of bool4 type hold 8 bits, sizeof(bool4) == 1
bool4 foo(bool4 a) {
bool4 v;
v = a;
return v;
}
Boolean vectors are a Clang extension of the ext vector type. Boolean vectors
are intended, though not guaranteed, to map to vector mask registers. The size
parameter of a boolean vector type is the number of bits in the vector. The
boolean vector is dense and each bit in the boolean vector is one vector
element.
The semantics of boolean vectors borrows from C bit-fields with the following
differences:
* Distinct boolean vectors are always distinct memory objects (there is no
packing).
* Only the operators `?:`, `!`, `~`, `|`, `&`, `^` and comparison are allowed on
boolean vectors.
* Casting a scalar bool value to a boolean vector type means broadcasting the
scalar value onto all lanes (same as general ext_vector_type).
* It is not possible to access or swizzle elements of a boolean vector
(different than general ext_vector_type).
The size and alignment are both the number of bits rounded up to the next power
of two, but the alignment is at most the maximum vector alignment of the
target.
Vector Literals
---------------
Vector literals can be used to create vectors from a set of scalars, or
vectors. Either parentheses or braces form can be used. In the parentheses
form the number of literal values specified must be one, i.e. referring to a
scalar value, or must match the size of the vector type being created. If a
single scalar literal value is specified, the scalar literal value will be
replicated to all the components of the vector type. In the brackets form any
number of literals can be specified. For example:
.. code-block:: c++
typedef int v4si __attribute__((__vector_size__(16)));
typedef float float4 __attribute__((ext_vector_type(4)));
typedef float float2 __attribute__((ext_vector_type(2)));
v4si vsi = (v4si){1, 2, 3, 4};
float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f);
vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1).
vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0).
vector int vi3 = (vector int)(1, 2); // error
vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0).
vector int vi5 = (vector int)(1, 2, 3, 4);
float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f));
Vector Operations
-----------------
The table below shows the support for each operation by vector extension. A
dash indicates that an operation is not accepted according to a corresponding
specification.
============================== ======= ======= ============= ======= =====
Operator OpenCL AltiVec GCC NEON SVE
============================== ======= ======= ============= ======= =====
[] yes yes yes yes yes
unary operators +, -- yes yes yes yes yes
++, -- -- yes yes yes no no
+,--,*,/,% yes yes yes yes yes
bitwise operators &,|,^,~ yes yes yes yes yes
>>,<< yes yes yes yes yes
!, &&, || yes -- yes yes yes
==, !=, >, <, >=, <= yes yes yes yes yes
= yes yes yes yes yes
?: [#]_ yes -- yes yes yes
sizeof yes yes yes yes yes [#]_
C-style cast yes yes yes no no
reinterpret_cast yes no yes no no
static_cast yes no yes no no
const_cast no no no no no
address &v[i] no no no [#]_ no no
============================== ======= ======= ============= ======= =====
See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
.. [#] ternary operator(?:) has different behaviors depending on condition
operand's vector type. If the condition is a GNU vector (i.e. __vector_size__),
a NEON vector or an SVE vector, it's only available in C++ and uses normal bool
conversions (that is, != 0).
If it's an extension (OpenCL) vector, it's only available in C and OpenCL C.
And it selects base on signedness of the condition operands (OpenCL v1.1 s6.3.9).
.. [#] sizeof can only be used on vector length specific SVE types.
.. [#] Clang does not allow the address of an element to be taken while GCC
allows this. This is intentional for vectors with a boolean element type and
not implemented otherwise.
Vector Builtins
---------------
**Note: The implementation of vector builtins is work-in-progress and incomplete.**
In addition to the operators mentioned above, Clang provides a set of builtins
to perform additional operations on certain scalar and vector types.
Let ``T`` be one of the following types:
* an integer type (as in C2x 6.2.5p19), but excluding enumerated types and _Bool
* the standard floating types float or double
* a half-precision floating point type, if one is supported on the target
* a vector type.
For scalar types, consider the operation applied to a vector with a single element.
*Elementwise Builtins*
Each builtin returns a vector equivalent to applying the specified operation
elementwise to the input.
Unless specified otherwise operation(±0) = ±0 and operation(±infinity) = ±infinity
=========================================== ================================================================ =========================================
Name Operation Supported element types
=========================================== ================================================================ =========================================
T __builtin_elementwise_abs(T x) return the absolute value of a number x; the absolute value of signed integer and floating point types
the most negative integer remains the most negative integer
T __builtin_elementwise_fma(T x, T y, T z) fused multiply add, (x * y) + z. floating point types
T __builtin_elementwise_ceil(T x) return the smallest integral value greater than or equal to x floating point types
T __builtin_elementwise_sin(T x) return the sine of x interpreted as an angle in radians floating point types
T __builtin_elementwise_cos(T x) return the cosine of x interpreted as an angle in radians floating point types
T __builtin_elementwise_floor(T x) return the largest integral value less than or equal to x floating point types
T __builtin_elementwise_log(T x) return the natural logarithm of x floating point types
T __builtin_elementwise_log2(T x) return the base 2 logarithm of x floating point types
T __builtin_elementwise_log10(T x) return the base 10 logarithm of x floating point types
T __builtin_elementwise_exp(T x) returns the base-e exponential, e^x, of the specified value floating point types
T __builtin_elementwise_exp2(T x) returns the base-2 exponential, 2^x, of the specified value floating point types
T __builtin_elementwise_roundeven(T x) round x to the nearest integer value in floating point format, floating point types
rounding halfway cases to even (that is, to the nearest value
that is an even integer), regardless of the current rounding
direction.
T __builtin_elementwise_round(T x) round x to the nearest integer value in floating point format, floating point types
rounding halfway cases away from zero, regardless of the
current rounding direction. May raise floating-point
exceptions.
T __builtin_elementwise_trunc(T x) return the integral value nearest to but no larger in floating point types
magnitude than x
T __builtin_elementwise_nearbyint(T x) round x to the nearest integer value in floating point format, floating point types
rounding according to the current rounding direction.
May not raise the inexact floating-point exception. This is
treated the same as ``__builtin_elementwise_rint`` unless
:ref:`FENV_ACCESS is enabled <floating-point-environment>`.
T __builtin_elementwise_rint(T x) round x to the nearest integer value in floating point format, floating point types
rounding according to the current rounding
direction. May raise floating-point exceptions. This is treated
the same as ``__builtin_elementwise_nearbyint`` unless
:ref:`FENV_ACCESS is enabled <floating-point-environment>`.
T __builtin_elementwise_canonicalize(T x) return the platform specific canonical encoding floating point types
of a floating-point number
T __builtin_elementwise_copysign(T x, T y) return the magnitude of x with the sign of y. floating point types
T __builtin_elementwise_max(T x, T y) return x or y, whichever is larger integer and floating point types
T __builtin_elementwise_min(T x, T y) return x or y, whichever is smaller integer and floating point types
T __builtin_elementwise_add_sat(T x, T y) return the sum of x and y, clamped to the range of integer types
representable values for the signed/unsigned integer type.
T __builtin_elementwise_sub_sat(T x, T y) return the difference of x and y, clamped to the range of integer types
representable values for the signed/unsigned integer type.
=========================================== ================================================================ =========================================
*Reduction Builtins*
Each builtin returns a scalar equivalent to applying the specified
operation(x, y) as recursive even-odd pairwise reduction to all vector
elements. ``operation(x, y)`` is repeatedly applied to each non-overlapping
even-odd element pair with indices ``i * 2`` and ``i * 2 + 1`` with
``i in [0, Number of elements / 2)``. If the numbers of elements is not a
power of 2, the vector is widened with neutral elements for the reduction
at the end to the next power of 2.
Example:
.. code-block:: c++
__builtin_reduce_add([e3, e2, e1, e0]) = __builtin_reduced_add([e3 + e2, e1 + e0])
= (e3 + e2) + (e1 + e0)
Let ``VT`` be a vector type and ``ET`` the element type of ``VT``.
======================================= ================================================================ ==================================
Name Operation Supported element types
======================================= ================================================================ ==================================
ET __builtin_reduce_max(VT a) return x or y, whichever is larger; If exactly one argument is integer and floating point types
a NaN, return the other argument. If both arguments are NaNs,
fmax() return a NaN.
ET __builtin_reduce_min(VT a) return x or y, whichever is smaller; If exactly one argument integer and floating point types
is a NaN, return the other argument. If both arguments are
NaNs, fmax() return a NaN.
ET __builtin_reduce_add(VT a) \+ integer types
ET __builtin_reduce_mul(VT a) \* integer types
ET __builtin_reduce_and(VT a) & integer types
ET __builtin_reduce_or(VT a) \| integer types
ET __builtin_reduce_xor(VT a) ^ integer types
======================================= ================================================================ ==================================
Matrix Types
============
Clang provides an extension for matrix types, which is currently being
implemented. See :ref:`the draft specification <matrixtypes>` for more details.
For example, the code below uses the matrix types extension to multiply two 4x4
float matrices and add the result to a third 4x4 matrix.
.. code-block:: c++
typedef float m4x4_t __attribute__((matrix_type(4, 4)));
m4x4_t f(m4x4_t a, m4x4_t b, m4x4_t c) {
return a + b * c;
}
The matrix type extension also supports operations on a matrix and a scalar.
.. code-block:: c++
typedef float m4x4_t __attribute__((matrix_type(4, 4)));
m4x4_t f(m4x4_t a) {
return (a + 23) * 12;
}
The matrix type extension supports division on a matrix and a scalar but not on a matrix and a matrix.
.. code-block:: c++
typedef float m4x4_t __attribute__((matrix_type(4, 4)));
m4x4_t f(m4x4_t a) {
a = a / 3.0;
return a;
}
The matrix type extension supports compound assignments for addition, subtraction, and multiplication on matrices
and on a matrix and a scalar, provided their types are consistent.
.. code-block:: c++
typedef float m4x4_t __attribute__((matrix_type(4, 4)));
m4x4_t f(m4x4_t a, m4x4_t b) {
a += b;
a -= b;
a *= b;
a += 23;
a -= 12;
return a;
}
The matrix type extension supports explicit casts. Implicit type conversion between matrix types is not allowed.
.. code-block:: c++
typedef int ix5x5 __attribute__((matrix_type(5, 5)));
typedef float fx5x5 __attribute__((matrix_type(5, 5)));
fx5x5 f1(ix5x5 i, fx5x5 f) {
return (fx5x5) i;
}
template <typename X>
using matrix_4_4 = X __attribute__((matrix_type(4, 4)));
void f2() {
matrix_5_5<double> d;
matrix_5_5<int> i;
i = (matrix_5_5<int>)d;
i = static_cast<matrix_5_5<int>>(d);
}
Half-Precision Floating Point
=============================
Clang supports three half-precision (16-bit) floating point types:
``__fp16``, ``_Float16`` and ``__bf16``. These types are supported
in all language modes, but their support differs between targets.
A target is said to have "native support" for a type if the target
processor offers instructions for directly performing basic arithmetic
on that type. In the absence of native support, a type can still be
supported if the compiler can emulate arithmetic on the type by promoting
to ``float``; see below for more information on this emulation.
* ``__fp16`` is supported on all targets. The special semantics of this
type mean that no arithmetic is ever performed directly on ``__fp16`` values;
see below.
* ``_Float16`` is supported on the following targets:
* 32-bit ARM (natively on some architecture versions)
* 64-bit ARM (AArch64) (natively on ARMv8.2a and above)
* AMDGPU (natively)
* SPIR (natively)
* X86 (if SSE2 is available; natively if AVX512-FP16 is also available)
* ``__bf16`` is supported on the following targets (currently never natively):
* 32-bit ARM
* 64-bit ARM (AArch64)
* X86 (when SSE2 is available)
(For X86, SSE2 is available on 64-bit and all recent 32-bit processors.)
``__fp16`` and ``_Float16`` both use the binary16 format from IEEE
754-2008, which provides a 5-bit exponent and an 11-bit significand
(counting the implicit leading 1). ``__bf16`` uses the `bfloat16
<https://en.wikipedia.org/wiki/Bfloat16_floating-point_format>`_ format,
which provides an 8-bit exponent and an 8-bit significand; this is the same
exponent range as `float`, just with greatly reduced precision.
``_Float16`` and ``__bf16`` follow the usual rules for arithmetic
floating-point types. Most importantly, this means that arithmetic operations
on operands of these types are formally performed in the type and produce
values of the type. ``__fp16`` does not follow those rules: most operations
immediately promote operands of type ``__fp16`` to ``float``, and so
arithmetic operations are defined to be performed in ``float`` and so result in
a value of type ``float`` (unless further promoted because of other operands).
See below for more information on the exact specifications of these types.
When compiling arithmetic on ``_Float16`` and ``__bf16`` for a target without
native support, Clang will perform the arithmetic in ``float``, inserting
extensions and truncations as necessary. This can be done in a way that
exactly matches the operation-by-operation behavior of native support,
but that can require many extra truncations and extensions. By default,
when emulating ``_Float16`` and ``__bf16`` arithmetic using ``float``, Clang
does not truncate intermediate operands back to their true type unless the
operand is the result of an explicit cast or assignment. This is generally
much faster but can generate different results from strict operation-by-operation
emulation. Usually the results are more precise. This is permitted by the
C and C++ standards under the rules for excess precision in intermediate operands;
see the discussion of evaluation formats in the C standard and [expr.pre] in
the C++ standard.
The use of excess precision can be independently controlled for these two
types with the ``-ffloat16-excess-precision=`` and
``-fbfloat16-excess-precision=`` options. Valid values include:
* ``none``: meaning to perform strict operation-by-operation emulation
* ``standard``: meaning that excess precision is permitted under the rules
described in the standard, i.e. never across explicit casts or statements
* ``fast``: meaning that excess precision is permitted whenever the
optimizer sees an opportunity to avoid truncations; currently this has no
effect beyond ``standard``
The ``_Float16`` type is an interchange floating type specified in
ISO/IEC TS 18661-3:2015 ("Floating-point extensions for C"). It will
be supported on more targets as they define ABIs for it.
The ``__bf16`` type is a non-standard extension, but it generally follows
the rules for arithmetic interchange floating types from ISO/IEC TS
18661-3:2015. In previous versions of Clang, it was a storage-only type
that forbade arithmetic operations. It will be supported on more targets
as they define ABIs for it.
The ``__fp16`` type was originally an ARM extension and is specified
by the `ARM C Language Extensions <https://github.com/ARM-software/acle/releases>`_.
Clang uses the ``binary16`` format from IEEE 754-2008 for ``__fp16``,
not the ARM alternative format. Operators that expect arithmetic operands
immediately promote ``__fp16`` operands to ``float``.
It is recommended that portable code use ``_Float16`` instead of ``__fp16``,
as it has been defined by the C standards committee and has behavior that is
more familiar to most programmers.
Because ``__fp16`` operands are always immediately promoted to ``float``, the
common real type of ``__fp16`` and ``_Float16`` for the purposes of the usual
arithmetic conversions is ``float``.
A literal can be given ``_Float16`` type using the suffix ``f16``. For example,
``3.14f16``.
Because default argument promotion only applies to the standard floating-point
types, ``_Float16`` values are not promoted to ``double`` when passed as variadic
or untyped arguments. As a consequence, some caution must be taken when using
certain library facilities with ``_Float16``; for example, there is no ``printf`` format
specifier for ``_Float16``, and (unlike ``float``) it will not be implicitly promoted to
``double`` when passed to ``printf``, so the programmer must explicitly cast it to
``double`` before using it with an ``%f`` or similar specifier.
Messages on ``deprecated`` and ``unavailable`` Attributes
=========================================================
An optional string message can be added to the ``deprecated`` and
``unavailable`` attributes. For example:
.. code-block:: c++
void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
If the deprecated or unavailable declaration is used, the message will be
incorporated into the appropriate diagnostic:
.. code-block:: none
harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
[-Wdeprecated-declarations]
explode();
^
Query for this feature with
``__has_extension(attribute_deprecated_with_message)`` and
``__has_extension(attribute_unavailable_with_message)``.
Attributes on Enumerators
=========================
Clang allows attributes to be written on individual enumerators. This allows
enumerators to be deprecated, made unavailable, etc. The attribute must appear
after the enumerator name and before any initializer, like so:
.. code-block:: c++
enum OperationMode {
OM_Invalid,
OM_Normal,
OM_Terrified __attribute__((deprecated)),
OM_AbortOnError __attribute__((deprecated)) = 4
};
Attributes on the ``enum`` declaration do not apply to individual enumerators.
Query for this feature with ``__has_extension(enumerator_attributes)``.
C++11 Attributes on using-declarations
======================================
Clang allows C++-style ``[[]]`` attributes to be written on using-declarations.
For instance:
.. code-block:: c++
[[clang::using_if_exists]] using foo::bar;
using foo::baz [[clang::using_if_exists]];
You can test for support for this extension with
``__has_extension(cxx_attributes_on_using_declarations)``.
'User-Specified' System Frameworks
==================================
Clang provides a mechanism by which frameworks can be built in such a way that
they will always be treated as being "system frameworks", even if they are not
present in a system framework directory. This can be useful to system
framework developers who want to be able to test building other applications
with development builds of their framework, including the manner in which the
compiler changes warning behavior for system headers.
Framework developers can opt-in to this mechanism by creating a
"``.system_framework``" file at the top-level of their framework. That is, the
framework should have contents like:
.. code-block:: none
.../TestFramework.framework
.../TestFramework.framework/.system_framework
.../TestFramework.framework/Headers
.../TestFramework.framework/Headers/TestFramework.h
...
Clang will treat the presence of this file as an indicator that the framework
should be treated as a system framework, regardless of how it was found in the
framework search path. For consistency, we recommend that such files never be
included in installed versions of the framework.
Checks for Standard Language Features
=====================================
The ``__has_feature`` macro can be used to query if certain standard language
features are enabled. The ``__has_extension`` macro can be used to query if
language features are available as an extension when compiling for a standard
which does not provide them. The features which can be tested are listed here.
Since Clang 3.4, the C++ SD-6 feature test macros are also supported.
These are macros with names of the form ``__cpp_<feature_name>``, and are
intended to be a portable way to query the supported features of the compiler.
See `the C++ status page <https://clang.llvm.org/cxx_status.html#ts>`_ for
information on the version of SD-6 supported by each Clang release, and the
macros provided by that revision of the recommendations.
C++98
-----
The features listed below are part of the C++98 standard. These features are