1 =========================
2 Clang Language Extensions
3 =========================
15 AutomaticReferenceCounting
20 This document describes the language extensions provided by Clang. In addition
21 to the language extensions listed here, Clang aims to support a broad range of
22 GCC extensions. Please see the `GCC manual
23 <http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on
26 .. _langext-feature_check:
28 Feature Checking Macros
29 =======================
31 Language extensions can be very useful, but only if you know you can depend on
32 them. In order to allow fine-grain features checks, we support three builtin
33 function-like macros. This allows you to directly test for a feature in your
34 code without having to resort to something like autoconf or fragile "compiler
40 This function-like macro takes a single identifier argument that is the name of
41 a builtin function. It evaluates to 1 if the builtin is supported or 0 if not.
42 It can be used like this:
46 #ifndef __has_builtin // Optional of course.
47 #define __has_builtin(x) 0 // Compatibility with non-clang compilers.
51 #if __has_builtin(__builtin_trap)
58 .. _langext-__has_feature-__has_extension:
60 ``__has_feature`` and ``__has_extension``
61 -----------------------------------------
63 These function-like macros take a single identifier argument that is the name
64 of a feature. ``__has_feature`` evaluates to 1 if the feature is both
65 supported by Clang and standardized in the current language standard or 0 if
66 not (but see :ref:`below <langext-has-feature-back-compat>`), while
67 ``__has_extension`` evaluates to 1 if the feature is supported by Clang in the
68 current language (either as a language extension or a standard language
69 feature) or 0 if not. They can be used like this:
73 #ifndef __has_feature // Optional of course.
74 #define __has_feature(x) 0 // Compatibility with non-clang compilers.
76 #ifndef __has_extension
77 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers.
81 #if __has_feature(cxx_rvalue_references)
82 // This code will only be compiled with the -std=c++11 and -std=gnu++11
83 // options, because rvalue references are only standardized in C++11.
86 #if __has_extension(cxx_rvalue_references)
87 // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98
88 // and -std=gnu++98 options, because rvalue references are supported as a
89 // language extension in C++98.
92 .. _langext-has-feature-back-compat:
94 For backward compatibility, ``__has_feature`` can also be used to test
95 for support for non-standardized features, i.e. features not prefixed ``c_``,
96 ``cxx_`` or ``objc_``.
98 Another use of ``__has_feature`` is to check for compiler features not related
99 to the language standard, such as e.g. :doc:`AddressSanitizer
102 If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent
103 to ``__has_feature``.
105 The feature tag is described along with the language feature below.
107 The feature name or extension name can also be specified with a preceding and
108 following ``__`` (double underscore) to avoid interference from a macro with
109 the same name. For instance, ``__cxx_rvalue_references__`` can be used instead
110 of ``cxx_rvalue_references``.
112 ``__has_cpp_attribute``
113 -----------------------
115 This function-like macro takes a single argument that is the name of a
116 C++11-style attribute. The argument can either be a single identifier, or a
117 scoped identifier. If the attribute is supported, a nonzero value is returned.
118 If the attribute is a standards-based attribute, this macro returns a nonzero
119 value based on the year and month in which the attribute was voted into the
120 working draft. If the attribute is not supported by the current compliation
121 target, this macro evaluates to 0. It can be used like this:
125 #ifndef __has_cpp_attribute // Optional of course.
126 #define __has_cpp_attribute(x) 0 // Compatibility with non-clang compilers.
130 #if __has_cpp_attribute(clang::fallthrough)
131 #define FALLTHROUGH [[clang::fallthrough]]
137 The attribute identifier (but not scope) can also be specified with a preceding
138 and following ``__`` (double underscore) to avoid interference from a macro with
139 the same name. For instance, ``gnu::__const__`` can be used instead of
145 This function-like macro takes a single identifier argument that is the name of
146 a GNU-style attribute. It evaluates to 1 if the attribute is supported by the
147 current compilation target, or 0 if not. It can be used like this:
151 #ifndef __has_attribute // Optional of course.
152 #define __has_attribute(x) 0 // Compatibility with non-clang compilers.
156 #if __has_attribute(always_inline)
157 #define ALWAYS_INLINE __attribute__((always_inline))
159 #define ALWAYS_INLINE
163 The attribute name can also be specified with a preceding and following ``__``
164 (double underscore) to avoid interference from a macro with the same name. For
165 instance, ``__always_inline__`` can be used instead of ``always_inline``.
168 ``__has_declspec_attribute``
169 ----------------------------
171 This function-like macro takes a single identifier argument that is the name of
172 an attribute implemented as a Microsoft-style ``__declspec`` attribute. It
173 evaluates to 1 if the attribute is supported by the current compilation target,
174 or 0 if not. It can be used like this:
178 #ifndef __has_declspec_attribute // Optional of course.
179 #define __has_declspec_attribute(x) 0 // Compatibility with non-clang compilers.
183 #if __has_declspec_attribute(dllexport)
184 #define DLLEXPORT __declspec(dllexport)
190 The attribute name can also be specified with a preceding and following ``__``
191 (double underscore) to avoid interference from a macro with the same name. For
192 instance, ``__dllexport__`` can be used instead of ``dllexport``.
197 This function-like macro takes a single identifier argument that might be either
198 a reserved word or a regular identifier. It evaluates to 1 if the argument is just
199 a regular identifier and not a reserved word, in the sense that it can then be
200 used as the name of a user-defined function or variable. Otherwise it evaluates
201 to 0. It can be used like this:
206 #ifdef __is_identifier // Compatibility with non-clang compilers.
207 #if __is_identifier(__wchar_t)
208 typedef wchar_t __wchar_t;
212 __wchar_t WideCharacter;
215 Include File Checking Macros
216 ============================
218 Not all developments systems have the same include files. The
219 :ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow
220 you to check for the existence of an include file before doing a possibly
221 failing ``#include`` directive. Include file checking macros must be used
222 as expressions in ``#if`` or ``#elif`` preprocessing directives.
224 .. _langext-__has_include:
229 This function-like macro takes a single file name string argument that is the
230 name of an include file. It evaluates to 1 if the file can be found using the
231 include paths, or 0 otherwise:
235 // Note the two possible file name string formats.
236 #if __has_include("myinclude.h") && __has_include(<stdint.h>)
237 # include "myinclude.h"
240 To test for this feature, use ``#if defined(__has_include)``:
244 // To avoid problem with non-clang compilers not having this macro.
245 #if defined(__has_include)
246 #if __has_include("myinclude.h")
247 # include "myinclude.h"
251 .. _langext-__has_include_next:
253 ``__has_include_next``
254 ----------------------
256 This function-like macro takes a single file name string argument that is the
257 name of an include file. It is like ``__has_include`` except that it looks for
258 the second instance of the given file found in the include paths. It evaluates
259 to 1 if the second instance of the file can be found using the include paths,
264 // Note the two possible file name string formats.
265 #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>)
266 # include_next "myinclude.h"
269 // To avoid problem with non-clang compilers not having this macro.
270 #if defined(__has_include_next)
271 #if __has_include_next("myinclude.h")
272 # include_next "myinclude.h"
276 Note that ``__has_include_next``, like the GNU extension ``#include_next``
277 directive, is intended for use in headers only, and will issue a warning if
278 used in the top-level compilation file. A warning will also be issued if an
279 absolute path is used in the file argument.
284 This function-like macro takes a string literal that represents a command line
285 option for a warning and returns true if that is a valid warning option.
289 #if __has_warning("-Wformat")
297 Defined to a string that contains the name of the main input file passed to
301 Defined to an integer value that starts at zero and is incremented each time
302 the ``__COUNTER__`` macro is expanded.
304 ``__INCLUDE_LEVEL__``
305 Defined to an integral value that is the include depth of the file currently
306 being translated. For the main file, this value is zero.
309 Defined to the date and time of the last modification of the current source
313 Defined when compiling with Clang
316 Defined to the major marketing version number of Clang (e.g., the 2 in
317 2.0.1). Note that marketing version numbers should not be used to check for
318 language features, as different vendors use different numbering schemes.
319 Instead, use the :ref:`langext-feature_check`.
322 Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note
323 that marketing version numbers should not be used to check for language
324 features, as different vendors use different numbering schemes. Instead, use
325 the :ref:`langext-feature_check`.
327 ``__clang_patchlevel__``
328 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).
330 ``__clang_version__``
331 Defined to a string that captures the Clang marketing version, including the
332 Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``".
336 Vectors and Extended Vectors
337 ============================
339 Supports the GCC, OpenCL, AltiVec and NEON vector extensions.
341 OpenCL vector types are created using ``ext_vector_type`` attribute. It
342 support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example
347 typedef float float4 __attribute__((ext_vector_type(4)));
348 typedef float float2 __attribute__((ext_vector_type(2)));
350 float4 foo(float2 a, float2 b) {
357 Query for this feature with ``__has_extension(attribute_ext_vector_type)``.
359 Giving ``-faltivec`` option to clang enables support for AltiVec vector syntax
360 and functions. For example:
364 vector float foo(vector int a) {
366 b = vec_add(a, a) + a;
367 return (vector float)b;
370 NEON vector types are created using ``neon_vector_type`` and
371 ``neon_polyvector_type`` attributes. For example:
375 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t;
376 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t;
378 int8x8_t foo(int8x8_t a) {
387 Vector literals can be used to create vectors from a set of scalars, or
388 vectors. Either parentheses or braces form can be used. In the parentheses
389 form the number of literal values specified must be one, i.e. referring to a
390 scalar value, or must match the size of the vector type being created. If a
391 single scalar literal value is specified, the scalar literal value will be
392 replicated to all the components of the vector type. In the brackets form any
393 number of literals can be specified. For example:
397 typedef int v4si __attribute__((__vector_size__(16)));
398 typedef float float4 __attribute__((ext_vector_type(4)));
399 typedef float float2 __attribute__((ext_vector_type(2)));
401 v4si vsi = (v4si){1, 2, 3, 4};
402 float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f);
403 vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1).
404 vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0).
405 vector int vi3 = (vector int)(1, 2); // error
406 vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0).
407 vector int vi5 = (vector int)(1, 2, 3, 4);
408 float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f));
413 The table below shows the support for each operation by vector extension. A
414 dash indicates that an operation is not accepted according to a corresponding
417 ============================== ======= ======= ======= =======
418 Opeator OpenCL AltiVec GCC NEON
419 ============================== ======= ======= ======= =======
421 unary operators +, -- yes yes yes --
422 ++, -- -- yes yes yes --
423 +,--,*,/,% yes yes yes --
424 bitwise operators &,|,^,~ yes yes yes --
426 !, &&, || yes -- -- --
427 ==, !=, >, <, >=, <= yes yes -- --
430 sizeof yes yes yes yes
431 C-style cast yes yes yes no
432 reinterpret_cast yes no yes no
433 static_cast yes no yes no
434 const_cast no no no no
435 ============================== ======= ======= ======= =======
437 See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`.
439 Messages on ``deprecated`` and ``unavailable`` Attributes
440 =========================================================
442 An optional string message can be added to the ``deprecated`` and
443 ``unavailable`` attributes. For example:
447 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!")));
449 If the deprecated or unavailable declaration is used, the message will be
450 incorporated into the appropriate diagnostic:
454 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
455 [-Wdeprecated-declarations]
459 Query for this feature with
460 ``__has_extension(attribute_deprecated_with_message)`` and
461 ``__has_extension(attribute_unavailable_with_message)``.
463 Attributes on Enumerators
464 =========================
466 Clang allows attributes to be written on individual enumerators. This allows
467 enumerators to be deprecated, made unavailable, etc. The attribute must appear
468 after the enumerator name and before any initializer, like so:
475 OM_Terrified __attribute__((deprecated)),
476 OM_AbortOnError __attribute__((deprecated)) = 4
479 Attributes on the ``enum`` declaration do not apply to individual enumerators.
481 Query for this feature with ``__has_extension(enumerator_attributes)``.
483 'User-Specified' System Frameworks
484 ==================================
486 Clang provides a mechanism by which frameworks can be built in such a way that
487 they will always be treated as being "system frameworks", even if they are not
488 present in a system framework directory. This can be useful to system
489 framework developers who want to be able to test building other applications
490 with development builds of their framework, including the manner in which the
491 compiler changes warning behavior for system headers.
493 Framework developers can opt-in to this mechanism by creating a
494 "``.system_framework``" file at the top-level of their framework. That is, the
495 framework should have contents like:
499 .../TestFramework.framework
500 .../TestFramework.framework/.system_framework
501 .../TestFramework.framework/Headers
502 .../TestFramework.framework/Headers/TestFramework.h
505 Clang will treat the presence of this file as an indicator that the framework
506 should be treated as a system framework, regardless of how it was found in the
507 framework search path. For consistency, we recommend that such files never be
508 included in installed versions of the framework.
510 Checks for Standard Language Features
511 =====================================
513 The ``__has_feature`` macro can be used to query if certain standard language
514 features are enabled. The ``__has_extension`` macro can be used to query if
515 language features are available as an extension when compiling for a standard
516 which does not provide them. The features which can be tested are listed here.
518 Since Clang 3.4, the C++ SD-6 feature test macros are also supported.
519 These are macros with names of the form ``__cpp_<feature_name>``, and are
520 intended to be a portable way to query the supported features of the compiler.
521 See `the C++ status page <http://clang.llvm.org/cxx_status.html#ts>`_ for
522 information on the version of SD-6 supported by each Clang release, and the
523 macros provided by that revision of the recommendations.
528 The features listed below are part of the C++98 standard. These features are
529 enabled by default when compiling C++ code.
534 Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been
535 enabled. For example, compiling code with ``-fno-exceptions`` disables C++
541 Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For
542 example, compiling code with ``-fno-rtti`` disables the use of RTTI.
547 The features listed below are part of the C++11 standard. As a result, all
548 these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option
549 when compiling C++ code.
551 C++11 SFINAE includes access control
552 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
554 Use ``__has_feature(cxx_access_control_sfinae)`` or
555 ``__has_extension(cxx_access_control_sfinae)`` to determine whether
556 access-control errors (e.g., calling a private constructor) are considered to
557 be template argument deduction errors (aka SFINAE errors), per `C++ DR1170
558 <http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_.
560 C++11 alias templates
561 ^^^^^^^^^^^^^^^^^^^^^
563 Use ``__has_feature(cxx_alias_templates)`` or
564 ``__has_extension(cxx_alias_templates)`` to determine if support for C++11's
565 alias declarations and alias templates is enabled.
567 C++11 alignment specifiers
568 ^^^^^^^^^^^^^^^^^^^^^^^^^^
570 Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to
571 determine if support for alignment specifiers using ``alignas`` is enabled.
573 Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to
574 determine if support for the ``alignof`` keyword is enabled.
579 Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to
580 determine if support for attribute parsing with C++11's square bracket notation
583 C++11 generalized constant expressions
584 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
586 Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized
587 constant expressions (e.g., ``constexpr``) is enabled.
592 Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to
593 determine if support for the ``decltype()`` specifier is enabled. C++11's
594 ``decltype`` does not require type-completeness of a function call expression.
595 Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or
596 ``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if
597 support for this feature is enabled.
599 C++11 default template arguments in function templates
600 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
602 Use ``__has_feature(cxx_default_function_template_args)`` or
603 ``__has_extension(cxx_default_function_template_args)`` to determine if support
604 for default template arguments in function templates is enabled.
606 C++11 ``default``\ ed functions
607 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
609 Use ``__has_feature(cxx_defaulted_functions)`` or
610 ``__has_extension(cxx_defaulted_functions)`` to determine if support for
611 defaulted function definitions (with ``= default``) is enabled.
613 C++11 delegating constructors
614 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
616 Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for
617 delegating constructors is enabled.
619 C++11 ``deleted`` functions
620 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
622 Use ``__has_feature(cxx_deleted_functions)`` or
623 ``__has_extension(cxx_deleted_functions)`` to determine if support for deleted
624 function definitions (with ``= delete``) is enabled.
626 C++11 explicit conversion functions
627 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
629 Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for
630 ``explicit`` conversion functions is enabled.
632 C++11 generalized initializers
633 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
635 Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for
636 generalized initializers (using braced lists and ``std::initializer_list``) is
639 C++11 implicit move constructors/assignment operators
640 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
642 Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly
643 generate move constructors and move assignment operators where needed.
645 C++11 inheriting constructors
646 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
648 Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for
649 inheriting constructors is enabled.
651 C++11 inline namespaces
652 ^^^^^^^^^^^^^^^^^^^^^^^
654 Use ``__has_feature(cxx_inline_namespaces)`` or
655 ``__has_extension(cxx_inline_namespaces)`` to determine if support for inline
656 namespaces is enabled.
661 Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to
662 determine if support for lambdas is enabled.
664 C++11 local and unnamed types as template arguments
665 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
667 Use ``__has_feature(cxx_local_type_template_args)`` or
668 ``__has_extension(cxx_local_type_template_args)`` to determine if support for
669 local and unnamed types as template arguments is enabled.
674 Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to
675 determine if support for noexcept exception specifications is enabled.
677 C++11 in-class non-static data member initialization
678 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
680 Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class
681 initialization of non-static data members is enabled.
686 Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to
687 determine if support for ``nullptr`` is enabled.
689 C++11 ``override control``
690 ^^^^^^^^^^^^^^^^^^^^^^^^^^
692 Use ``__has_feature(cxx_override_control)`` or
693 ``__has_extension(cxx_override_control)`` to determine if support for the
694 override control keywords is enabled.
696 C++11 reference-qualified functions
697 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
699 Use ``__has_feature(cxx_reference_qualified_functions)`` or
700 ``__has_extension(cxx_reference_qualified_functions)`` to determine if support
701 for reference-qualified functions (e.g., member functions with ``&`` or ``&&``
702 applied to ``*this``) is enabled.
704 C++11 range-based ``for`` loop
705 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
707 Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to
708 determine if support for the range-based for loop is enabled.
710 C++11 raw string literals
711 ^^^^^^^^^^^^^^^^^^^^^^^^^
713 Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw
714 string literals (e.g., ``R"x(foo\bar)x"``) is enabled.
716 C++11 rvalue references
717 ^^^^^^^^^^^^^^^^^^^^^^^
719 Use ``__has_feature(cxx_rvalue_references)`` or
720 ``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue
721 references is enabled.
723 C++11 ``static_assert()``
724 ^^^^^^^^^^^^^^^^^^^^^^^^^
726 Use ``__has_feature(cxx_static_assert)`` or
727 ``__has_extension(cxx_static_assert)`` to determine if support for compile-time
728 assertions using ``static_assert`` is enabled.
730 C++11 ``thread_local``
731 ^^^^^^^^^^^^^^^^^^^^^^
733 Use ``__has_feature(cxx_thread_local)`` to determine if support for
734 ``thread_local`` variables is enabled.
739 Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to
740 determine C++11 type inference is supported using the ``auto`` specifier. If
741 this is disabled, ``auto`` will instead be a storage class specifier, as in C
744 C++11 strongly typed enumerations
745 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
747 Use ``__has_feature(cxx_strong_enums)`` or
748 ``__has_extension(cxx_strong_enums)`` to determine if support for strongly
749 typed, scoped enumerations is enabled.
751 C++11 trailing return type
752 ^^^^^^^^^^^^^^^^^^^^^^^^^^
754 Use ``__has_feature(cxx_trailing_return)`` or
755 ``__has_extension(cxx_trailing_return)`` to determine if support for the
756 alternate function declaration syntax with trailing return type is enabled.
758 C++11 Unicode string literals
759 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
761 Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode
762 string literals is enabled.
764 C++11 unrestricted unions
765 ^^^^^^^^^^^^^^^^^^^^^^^^^
767 Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for
768 unrestricted unions is enabled.
770 C++11 user-defined literals
771 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
773 Use ``__has_feature(cxx_user_literals)`` to determine if support for
774 user-defined literals is enabled.
776 C++11 variadic templates
777 ^^^^^^^^^^^^^^^^^^^^^^^^
779 Use ``__has_feature(cxx_variadic_templates)`` or
780 ``__has_extension(cxx_variadic_templates)`` to determine if support for
781 variadic templates is enabled.
786 The features listed below are part of the committee draft for the C++1y
787 standard. As a result, all these features are enabled with the ``-std=c++1y``
788 or ``-std=gnu++1y`` option when compiling C++ code.
790 C++1y binary literals
791 ^^^^^^^^^^^^^^^^^^^^^
793 Use ``__has_feature(cxx_binary_literals)`` or
794 ``__has_extension(cxx_binary_literals)`` to determine whether
795 binary literals (for instance, ``0b10010``) are recognized. Clang supports this
796 feature as an extension in all language modes.
798 C++1y contextual conversions
799 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
801 Use ``__has_feature(cxx_contextual_conversions)`` or
802 ``__has_extension(cxx_contextual_conversions)`` to determine if the C++1y rules
803 are used when performing an implicit conversion for an array bound in a
804 *new-expression*, the operand of a *delete-expression*, an integral constant
805 expression, or a condition in a ``switch`` statement.
810 Use ``__has_feature(cxx_decltype_auto)`` or
811 ``__has_extension(cxx_decltype_auto)`` to determine if support
812 for the ``decltype(auto)`` placeholder type is enabled.
814 C++1y default initializers for aggregates
815 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
817 Use ``__has_feature(cxx_aggregate_nsdmi)`` or
818 ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support
819 for default initializers in aggregate members is enabled.
821 C++1y digit separators
822 ^^^^^^^^^^^^^^^^^^^^^^
824 Use ``__cpp_digit_separators`` to determine if support for digit separators
825 using single quotes (for instance, ``10'000``) is enabled. At this time, there
826 is no corresponding ``__has_feature`` name
828 C++1y generalized lambda capture
829 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
831 Use ``__has_feature(cxx_init_captures)`` or
832 ``__has_extension(cxx_init_captures)`` to determine if support for
833 lambda captures with explicit initializers is enabled
834 (for instance, ``[n(0)] { return ++n; }``).
836 C++1y generic lambdas
837 ^^^^^^^^^^^^^^^^^^^^^
839 Use ``__has_feature(cxx_generic_lambdas)`` or
840 ``__has_extension(cxx_generic_lambdas)`` to determine if support for generic
841 (polymorphic) lambdas is enabled
842 (for instance, ``[] (auto x) { return x + 1; }``).
844 C++1y relaxed constexpr
845 ^^^^^^^^^^^^^^^^^^^^^^^
847 Use ``__has_feature(cxx_relaxed_constexpr)`` or
848 ``__has_extension(cxx_relaxed_constexpr)`` to determine if variable
849 declarations, local variable modification, and control flow constructs
850 are permitted in ``constexpr`` functions.
852 C++1y return type deduction
853 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
855 Use ``__has_feature(cxx_return_type_deduction)`` or
856 ``__has_extension(cxx_return_type_deduction)`` to determine if support
857 for return type deduction for functions (using ``auto`` as a return type)
860 C++1y runtime-sized arrays
861 ^^^^^^^^^^^^^^^^^^^^^^^^^^
863 Use ``__has_feature(cxx_runtime_array)`` or
864 ``__has_extension(cxx_runtime_array)`` to determine if support
865 for arrays of runtime bound (a restricted form of variable-length arrays)
867 Clang's implementation of this feature is incomplete.
869 C++1y variable templates
870 ^^^^^^^^^^^^^^^^^^^^^^^^
872 Use ``__has_feature(cxx_variable_templates)`` or
873 ``__has_extension(cxx_variable_templates)`` to determine if support for
874 templated variable declarations is enabled.
879 The features listed below are part of the C11 standard. As a result, all these
880 features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when
881 compiling C code. Additionally, because these features are all
882 backward-compatible, they are available as extensions in all language modes.
884 C11 alignment specifiers
885 ^^^^^^^^^^^^^^^^^^^^^^^^
887 Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine
888 if support for alignment specifiers using ``_Alignas`` is enabled.
890 Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine
891 if support for the ``_Alignof`` keyword is enabled.
893 C11 atomic operations
894 ^^^^^^^^^^^^^^^^^^^^^
896 Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine
897 if support for atomic types using ``_Atomic`` is enabled. Clang also provides
898 :ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement
899 the ``<stdatomic.h>`` operations on ``_Atomic`` types. Use
900 ``__has_include(<stdatomic.h>)`` to determine if C11's ``<stdatomic.h>`` header
903 Clang will use the system's ``<stdatomic.h>`` header when one is available, and
904 will otherwise use its own. When using its own, implementations of the atomic
905 operations are provided as macros. In the cases where C11 also requires a real
906 function, this header provides only the declaration of that function (along
907 with a shadowing macro implementation), and you must link to a library which
908 provides a definition of the function if you use it instead of the macro.
910 C11 generic selections
911 ^^^^^^^^^^^^^^^^^^^^^^
913 Use ``__has_feature(c_generic_selections)`` or
914 ``__has_extension(c_generic_selections)`` to determine if support for generic
915 selections is enabled.
917 As an extension, the C11 generic selection expression is available in all
918 languages supported by Clang. The syntax is the same as that given in the C11
921 In C, type compatibility is decided according to the rules given in the
922 appropriate standard, but in C++, which lacks the type compatibility rules used
923 in C, types are considered compatible only if they are equivalent.
925 C11 ``_Static_assert()``
926 ^^^^^^^^^^^^^^^^^^^^^^^^
928 Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)``
929 to determine if support for compile-time assertions using ``_Static_assert`` is
932 C11 ``_Thread_local``
933 ^^^^^^^^^^^^^^^^^^^^^
935 Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)``
936 to determine if support for ``_Thread_local`` variables is enabled.
941 Use ``__has_feature(modules)`` to determine if Modules have been enabled.
942 For example, compiling code with ``-fmodules`` enables the use of Modules.
944 More information could be found `here <http://clang.llvm.org/docs/Modules.html>`_.
946 Checks for Type Trait Primitives
947 ================================
949 Type trait primitives are special builtin constant expressions that can be used
950 by the standard C++ library to facilitate or simplify the implementation of
951 user-facing type traits in the <type_traits> header.
953 They are not intended to be used directly by user code because they are
954 implementation-defined and subject to change -- as such they're tied closely to
955 the supported set of system headers, currently:
959 * The Microsoft standard C++ library
961 Clang supports the `GNU C++ type traits
962 <http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the
963 `Microsoft Visual C++ Type traits
964 <http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_.
966 Feature detection is supported only for some of the primitives at present. User
967 code should not use these checks because they bear no direct relation to the
968 actual set of type traits supported by the C++ standard library.
970 For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the
971 type trait primitive in the compiler. A simplistic usage example as might be
972 seen in standard C++ headers follows:
976 #if __has_extension(is_convertible_to)
977 template<typename From, typename To>
978 struct is_convertible_to {
979 static const bool value = __is_convertible_to(From, To);
982 // Emulate type trait for compatibility with other compilers.
985 The following type trait primitives are supported by Clang:
987 * ``__has_nothrow_assign`` (GNU, Microsoft)
988 * ``__has_nothrow_copy`` (GNU, Microsoft)
989 * ``__has_nothrow_constructor`` (GNU, Microsoft)
990 * ``__has_trivial_assign`` (GNU, Microsoft)
991 * ``__has_trivial_copy`` (GNU, Microsoft)
992 * ``__has_trivial_constructor`` (GNU, Microsoft)
993 * ``__has_trivial_destructor`` (GNU, Microsoft)
994 * ``__has_virtual_destructor`` (GNU, Microsoft)
995 * ``__is_abstract`` (GNU, Microsoft)
996 * ``__is_base_of`` (GNU, Microsoft)
997 * ``__is_class`` (GNU, Microsoft)
998 * ``__is_convertible_to`` (Microsoft)
999 * ``__is_empty`` (GNU, Microsoft)
1000 * ``__is_enum`` (GNU, Microsoft)
1001 * ``__is_interface_class`` (Microsoft)
1002 * ``__is_pod`` (GNU, Microsoft)
1003 * ``__is_polymorphic`` (GNU, Microsoft)
1004 * ``__is_union`` (GNU, Microsoft)
1005 * ``__is_literal(type)``: Determines whether the given type is a literal type
1006 * ``__is_final``: Determines whether the given type is declared with a
1007 ``final`` class-virt-specifier.
1008 * ``__underlying_type(type)``: Retrieves the underlying type for a given
1009 ``enum`` type. This trait is required to implement the C++11 standard
1011 * ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value
1012 of type ``totype`` can be assigned to from a value of type ``fromtype`` such
1013 that no non-trivial functions are called as part of that assignment. This
1014 trait is required to implement the C++11 standard library.
1015 * ``__is_trivially_constructible(type, argtypes...)``: Determines whether a
1016 value of type ``type`` can be direct-initialized with arguments of types
1017 ``argtypes...`` such that no non-trivial functions are called as part of
1018 that initialization. This trait is required to implement the C++11 standard
1020 * ``__is_destructible`` (MSVC 2013): partially implemented
1021 * ``__is_nothrow_destructible`` (MSVC 2013): partially implemented
1022 * ``__is_nothrow_assignable`` (MSVC 2013, clang)
1023 * ``__is_constructible`` (MSVC 2013, clang)
1024 * ``__is_nothrow_constructible`` (MSVC 2013, clang)
1029 The syntax and high level language feature description is in
1030 :doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for
1031 the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`.
1033 Query for this feature with ``__has_extension(blocks)``.
1035 Objective-C Features
1036 ====================
1038 Related result types
1039 --------------------
1041 According to Cocoa conventions, Objective-C methods with certain names
1042 ("``init``", "``alloc``", etc.) always return objects that are an instance of
1043 the receiving class's type. Such methods are said to have a "related result
1044 type", meaning that a message send to one of these methods will have the same
1045 static type as an instance of the receiver class. For example, given the
1048 .. code-block:: objc
1055 @interface NSArray : NSObject
1058 and this common initialization pattern
1060 .. code-block:: objc
1062 NSArray *array = [[NSArray alloc] init];
1064 the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because
1065 ``alloc`` implicitly has a related result type. Similarly, the type of the
1066 expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a
1067 related result type and its receiver is known to have the type ``NSArray *``.
1068 If neither ``alloc`` nor ``init`` had a related result type, the expressions
1069 would have had type ``id``, as declared in the method signature.
1071 A method with a related result type can be declared by using the type
1072 ``instancetype`` as its result type. ``instancetype`` is a contextual keyword
1073 that is only permitted in the result type of an Objective-C method, e.g.
1075 .. code-block:: objc
1078 + (instancetype)constructAnA;
1081 The related result type can also be inferred for some methods. To determine
1082 whether a method has an inferred related result type, the first word in the
1083 camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered,
1084 and the method will have a related result type if its return type is compatible
1085 with the type of its class and if:
1087 * the first word is "``alloc``" or "``new``", and the method is a class method,
1090 * the first word is "``autorelease``", "``init``", "``retain``", or "``self``",
1091 and the method is an instance method.
1093 If a method with a related result type is overridden by a subclass method, the
1094 subclass method must also return a type that is compatible with the subclass
1097 .. code-block:: objc
1099 @interface NSString : NSObject
1100 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString
1103 Related result types only affect the type of a message send or property access
1104 via the given method. In all other respects, a method with a related result
1105 type is treated the same way as method that returns ``id``.
1107 Use ``__has_feature(objc_instancetype)`` to determine whether the
1108 ``instancetype`` contextual keyword is available.
1110 Automatic reference counting
1111 ----------------------------
1113 Clang provides support for :doc:`automated reference counting
1114 <AutomaticReferenceCounting>` in Objective-C, which eliminates the need
1115 for manual ``retain``/``release``/``autorelease`` message sends. There are two
1116 feature macros associated with automatic reference counting:
1117 ``__has_feature(objc_arc)`` indicates the availability of automated reference
1118 counting in general, while ``__has_feature(objc_arc_weak)`` indicates that
1119 automated reference counting also includes support for ``__weak`` pointers to
1120 Objective-C objects.
1122 .. _objc-fixed-enum:
1124 Enumerations with a fixed underlying type
1125 -----------------------------------------
1127 Clang provides support for C++11 enumerations with a fixed underlying type
1128 within Objective-C. For example, one can write an enumeration type as:
1132 typedef enum : unsigned char { Red, Green, Blue } Color;
1134 This specifies that the underlying type, which is used to store the enumeration
1135 value, is ``unsigned char``.
1137 Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed
1138 underlying types is available in Objective-C.
1140 Interoperability with C++11 lambdas
1141 -----------------------------------
1143 Clang provides interoperability between C++11 lambdas and blocks-based APIs, by
1144 permitting a lambda to be implicitly converted to a block pointer with the
1145 corresponding signature. For example, consider an API such as ``NSArray``'s
1146 array-sorting method:
1148 .. code-block:: objc
1150 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr;
1152 ``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult
1153 (^)(id, id)``, and parameters of this type are generally provided with block
1154 literals as arguments. However, one can also use a C++11 lambda so long as it
1155 provides the same signature (in this case, accepting two parameters of type
1156 ``id`` and returning an ``NSComparisonResult``):
1158 .. code-block:: objc
1160 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11",
1162 const NSStringCompareOptions comparisonOptions
1163 = NSCaseInsensitiveSearch | NSNumericSearch |
1164 NSWidthInsensitiveSearch | NSForcedOrderingSearch;
1165 NSLocale *currentLocale = [NSLocale currentLocale];
1167 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult {
1168 NSRange string1Range = NSMakeRange(0, [s1 length]);
1169 return [s1 compare:s2 options:comparisonOptions
1170 range:string1Range locale:currentLocale];
1172 NSLog(@"sorted: %@", sorted);
1174 This code relies on an implicit conversion from the type of the lambda
1175 expression (an unnamed, local class type called the *closure type*) to the
1176 corresponding block pointer type. The conversion itself is expressed by a
1177 conversion operator in that closure type that produces a block pointer with the
1178 same signature as the lambda itself, e.g.,
1180 .. code-block:: objc
1182 operator NSComparisonResult (^)(id, id)() const;
1184 This conversion function returns a new block that simply forwards the two
1185 parameters to the lambda object (which it captures by copy), then returns the
1186 result. The returned block is first copied (with ``Block_copy``) and then
1187 autoreleased. As an optimization, if a lambda expression is immediately
1188 converted to a block pointer (as in the first example, above), then the block
1189 is not copied and autoreleased: rather, it is given the same lifetime as a
1190 block literal written at that point in the program, which avoids the overhead
1191 of copying a block to the heap in the common case.
1193 The conversion from a lambda to a block pointer is only available in
1194 Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory
1195 management (autorelease).
1197 Object Literals and Subscripting
1198 --------------------------------
1200 Clang provides support for :doc:`Object Literals and Subscripting
1201 <ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C
1202 programming patterns, makes programs more concise, and improves the safety of
1203 container creation. There are several feature macros associated with object
1204 literals and subscripting: ``__has_feature(objc_array_literals)`` tests the
1205 availability of array literals; ``__has_feature(objc_dictionary_literals)``
1206 tests the availability of dictionary literals;
1207 ``__has_feature(objc_subscripting)`` tests the availability of object
1210 Objective-C Autosynthesis of Properties
1211 ---------------------------------------
1213 Clang provides support for autosynthesis of declared properties. Using this
1214 feature, clang provides default synthesis of those properties not declared
1215 @dynamic and not having user provided backing getter and setter methods.
1216 ``__has_feature(objc_default_synthesize_properties)`` checks for availability
1217 of this feature in version of clang being used.
1219 .. _langext-objc-retain-release:
1221 Objective-C retaining behavior attributes
1222 -----------------------------------------
1224 In Objective-C, functions and methods are generally assumed to follow the
1225 `Cocoa Memory Management
1226 <http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_
1227 conventions for ownership of object arguments and
1228 return values. However, there are exceptions, and so Clang provides attributes
1229 to allow these exceptions to be documented. This are used by ARC and the
1230 `static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be
1231 better described using the ``objc_method_family`` attribute instead.
1233 **Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``,
1234 ``ns_returns_autoreleased``, ``cf_returns_retained``, and
1235 ``cf_returns_not_retained`` attributes can be placed on methods and functions
1236 that return Objective-C or CoreFoundation objects. They are commonly placed at
1237 the end of a function prototype or method declaration:
1239 .. code-block:: objc
1241 id foo() __attribute__((ns_returns_retained));
1243 - (NSString *)bar:(int)x __attribute__((ns_returns_retained));
1245 The ``*_returns_retained`` attributes specify that the returned object has a +1
1246 retain count. The ``*_returns_not_retained`` attributes specify that the return
1247 object has a +0 retain count, even if the normal convention for its selector
1248 would be +1. ``ns_returns_autoreleased`` specifies that the returned object is
1249 +0, but is guaranteed to live at least as long as the next flush of an
1252 **Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on
1253 an parameter declaration; they specify that the argument is expected to have a
1254 +1 retain count, which will be balanced in some way by the function or method.
1255 The ``ns_consumes_self`` attribute can only be placed on an Objective-C
1256 method; it specifies that the method expects its ``self`` parameter to have a
1257 +1 retain count, which it will balance in some way.
1259 .. code-block:: objc
1261 void foo(__attribute__((ns_consumed)) NSString *string);
1263 - (void) bar __attribute__((ns_consumes_self));
1264 - (void) baz:(id) __attribute__((ns_consumed)) x;
1266 Further examples of these attributes are available in the static analyzer's `list of annotations for analysis
1267 <http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_.
1269 Query for these features with ``__has_attribute(ns_consumed)``,
1270 ``__has_attribute(ns_returns_retained)``, etc.
1273 Objective-C++ ABI: protocol-qualifier mangling of parameters
1274 ------------------------------------------------------------
1276 Starting with LLVM 3.4, Clang produces a new mangling for parameters whose
1277 type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such
1278 parameters to be differentiated from those with the regular unqualified ``id``
1281 This was a non-backward compatible mangling change to the ABI. This change
1282 allows proper overloading, and also prevents mangling conflicts with template
1283 parameters of protocol-qualified type.
1285 Query the presence of this new mangling with
1286 ``__has_feature(objc_protocol_qualifier_mangling)``.
1288 .. _langext-overloading:
1290 Initializer lists for complex numbers in C
1291 ==========================================
1293 clang supports an extension which allows the following in C:
1298 #include <complex.h>
1299 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf)
1301 This construct is useful because there is no way to separately initialize the
1302 real and imaginary parts of a complex variable in standard C, given that clang
1303 does not support ``_Imaginary``. (Clang also supports the ``__real__`` and
1304 ``__imag__`` extensions from gcc, which help in some cases, but are not usable
1305 in static initializers.)
1307 Note that this extension does not allow eliding the braces; the meaning of the
1308 following two lines is different:
1312 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1)
1313 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0)
1315 This extension also works in C++ mode, as far as that goes, but does not apply
1316 to the C++ ``std::complex``. (In C++11, list initialization allows the same
1317 syntax to be used with ``std::complex`` with the same meaning.)
1322 Clang supports a number of builtin library functions with the same syntax as
1323 GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``,
1324 ``__builtin_choose_expr``, ``__builtin_types_compatible_p``,
1325 ``__builtin_assume_aligned``, ``__sync_fetch_and_add``, etc. In addition to
1326 the GCC builtins, Clang supports a number of builtins that GCC does not, which
1329 Please note that Clang does not and will not support all of the GCC builtins
1330 for vector operations. Instead of using builtins, you should use the functions
1331 defined in target-specific header files like ``<xmmintrin.h>``, which define
1332 portable wrappers for these. Many of the Clang versions of these functions are
1333 implemented directly in terms of :ref:`extended vector support
1334 <langext-vectors>` instead of builtins, in order to reduce the number of
1335 builtins that we need to implement.
1337 ``__builtin_assume``
1338 ------------------------------
1340 ``__builtin_assume`` is used to provide the optimizer with a boolean
1341 invariant that is defined to be true.
1347 __builtin_assume(bool)
1354 __builtin_assume(x != 0);
1356 // The optimizer may short-circuit this check using the invariant.
1358 return do_something();
1360 return do_something_else();
1365 The boolean argument to this function is defined to be true. The optimizer may
1366 analyze the form of the expression provided as the argument and deduce from
1367 that information used to optimize the program. If the condition is violated
1368 during execution, the behavior is undefined. The argument itself is never
1369 evaluated, so any side effects of the expression will be discarded.
1371 Query for this feature with ``__has_builtin(__builtin_assume)``.
1373 ``__builtin_readcyclecounter``
1374 ------------------------------
1376 ``__builtin_readcyclecounter`` is used to access the cycle counter register (or
1377 a similar low-latency, high-accuracy clock) on those targets that support it.
1383 __builtin_readcyclecounter()
1389 unsigned long long t0 = __builtin_readcyclecounter();
1391 unsigned long long t1 = __builtin_readcyclecounter();
1392 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow
1396 The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value,
1397 which may be either global or process/thread-specific depending on the target.
1398 As the backing counters often overflow quickly (on the order of seconds) this
1399 should only be used for timing small intervals. When not supported by the
1400 target, the return value is always zero. This builtin takes no arguments and
1401 produces an unsigned long long result.
1403 Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note
1404 that even if present, its use may depend on run-time privilege or other OS
1407 .. _langext-__builtin_shufflevector:
1409 ``__builtin_shufflevector``
1410 ---------------------------
1412 ``__builtin_shufflevector`` is used to express generic vector
1413 permutation/shuffle/swizzle operations. This builtin is also very important
1414 for the implementation of various target-specific header files like
1421 __builtin_shufflevector(vec1, vec2, index1, index2, ...)
1427 // identity operation - return 4-element vector v1.
1428 __builtin_shufflevector(v1, v1, 0, 1, 2, 3)
1430 // "Splat" element 0 of V1 into a 4-element result.
1431 __builtin_shufflevector(V1, V1, 0, 0, 0, 0)
1433 // Reverse 4-element vector V1.
1434 __builtin_shufflevector(V1, V1, 3, 2, 1, 0)
1436 // Concatenate every other element of 4-element vectors V1 and V2.
1437 __builtin_shufflevector(V1, V2, 0, 2, 4, 6)
1439 // Concatenate every other element of 8-element vectors V1 and V2.
1440 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14)
1442 // Shuffle v1 with some elements being undefined
1443 __builtin_shufflevector(v1, v1, 3, -1, 1, -1)
1447 The first two arguments to ``__builtin_shufflevector`` are vectors that have
1448 the same element type. The remaining arguments are a list of integers that
1449 specify the elements indices of the first two vectors that should be extracted
1450 and returned in a new vector. These element indices are numbered sequentially
1451 starting with the first vector, continuing into the second vector. Thus, if
1452 ``vec1`` is a 4-element vector, index 5 would refer to the second element of
1453 ``vec2``. An index of -1 can be used to indicate that the corresponding element
1454 in the returned vector is a don't care and can be optimized by the backend.
1456 The result of ``__builtin_shufflevector`` is a vector with the same element
1457 type as ``vec1``/``vec2`` but that has an element count equal to the number of
1460 Query for this feature with ``__has_builtin(__builtin_shufflevector)``.
1462 .. _langext-__builtin_convertvector:
1464 ``__builtin_convertvector``
1465 ---------------------------
1467 ``__builtin_convertvector`` is used to express generic vector
1468 type-conversion operations. The input vector and the output vector
1469 type must have the same number of elements.
1475 __builtin_convertvector(src_vec, dst_vec_type)
1481 typedef double vector4double __attribute__((__vector_size__(32)));
1482 typedef float vector4float __attribute__((__vector_size__(16)));
1483 typedef short vector4short __attribute__((__vector_size__(8)));
1484 vector4float vf; vector4short vs;
1486 // convert from a vector of 4 floats to a vector of 4 doubles.
1487 __builtin_convertvector(vf, vector4double)
1489 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] }
1491 // convert from a vector of 4 shorts to a vector of 4 floats.
1492 __builtin_convertvector(vs, vector4float)
1494 (vector4float) { (float) vs[0], (float) vs[1], (float) vs[2], (float) vs[3] }
1498 The first argument to ``__builtin_convertvector`` is a vector, and the second
1499 argument is a vector type with the same number of elements as the first
1502 The result of ``__builtin_convertvector`` is a vector with the same element
1503 type as the second argument, with a value defined in terms of the action of a
1504 C-style cast applied to each element of the first argument.
1506 Query for this feature with ``__has_builtin(__builtin_convertvector)``.
1508 ``__builtin_unreachable``
1509 -------------------------
1511 ``__builtin_unreachable`` is used to indicate that a specific point in the
1512 program cannot be reached, even if the compiler might otherwise think it can.
1513 This is useful to improve optimization and eliminates certain warnings. For
1514 example, without the ``__builtin_unreachable`` in the example below, the
1515 compiler assumes that the inline asm can fall through and prints a "function
1516 declared '``noreturn``' should not return" warning.
1522 __builtin_unreachable()
1528 void myabort(void) __attribute__((noreturn));
1529 void myabort(void) {
1531 __builtin_unreachable();
1536 The ``__builtin_unreachable()`` builtin has completely undefined behavior.
1537 Since it has undefined behavior, it is a statement that it is never reached and
1538 the optimizer can take advantage of this to produce better code. This builtin
1539 takes no arguments and produces a void result.
1541 Query for this feature with ``__has_builtin(__builtin_unreachable)``.
1546 ``__sync_swap`` is used to atomically swap integers or pointers in memory.
1552 type __sync_swap(type *ptr, type value, ...)
1558 int old_value = __sync_swap(&value, new_value);
1562 The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of
1563 atomic intrinsics to allow code to atomically swap the current value with the
1564 new value. More importantly, it helps developers write more efficient and
1565 correct code by avoiding expensive loops around
1566 ``__sync_bool_compare_and_swap()`` or relying on the platform specific
1567 implementation details of ``__sync_lock_test_and_set()``. The
1568 ``__sync_swap()`` builtin is a full barrier.
1570 ``__builtin_addressof``
1571 -----------------------
1573 ``__builtin_addressof`` performs the functionality of the built-in ``&``
1574 operator, ignoring any ``operator&`` overload. This is useful in constant
1575 expressions in C++11, where there is no other way to take the address of an
1576 object that overloads ``operator&``.
1582 template<typename T> constexpr T *addressof(T &value) {
1583 return __builtin_addressof(value);
1586 ``__builtin_operator_new`` and ``__builtin_operator_delete``
1587 ------------------------------------------------------------
1589 ``__builtin_operator_new`` allocates memory just like a non-placement non-class
1590 *new-expression*. This is exactly like directly calling the normal
1591 non-placement ``::operator new``, except that it allows certain optimizations
1592 that the C++ standard does not permit for a direct function call to
1593 ``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and
1594 merging allocations).
1596 Likewise, ``__builtin_operator_delete`` deallocates memory just like a
1597 non-class *delete-expression*, and is exactly like directly calling the normal
1598 ``::operator delete``, except that it permits optimizations. Only the unsized
1599 form of ``__builtin_operator_delete`` is currently available.
1601 These builtins are intended for use in the implementation of ``std::allocator``
1602 and other similar allocation libraries, and are only available in C++.
1604 Multiprecision Arithmetic Builtins
1605 ----------------------------------
1607 Clang provides a set of builtins which expose multiprecision arithmetic in a
1608 manner amenable to C. They all have the following form:
1612 unsigned x = ..., y = ..., carryin = ..., carryout;
1613 unsigned sum = __builtin_addc(x, y, carryin, &carryout);
1615 Thus one can form a multiprecision addition chain in the following manner:
1619 unsigned *x, *y, *z, carryin=0, carryout;
1620 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout);
1622 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout);
1624 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout);
1626 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout);
1628 The complete list of builtins are:
1632 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
1633 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1634 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1635 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1636 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1637 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout);
1638 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout);
1639 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout);
1640 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout);
1641 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout);
1643 Checked Arithmetic Builtins
1644 ---------------------------
1646 Clang provides a set of builtins that implement checked arithmetic for security
1647 critical applications in a manner that is fast and easily expressable in C. As
1648 an example of their usage:
1652 errorcode_t security_critical_application(...) {
1653 unsigned x, y, result;
1655 if (__builtin_umul_overflow(x, y, &result))
1656 return kErrorCodeHackers;
1658 use_multiply(result);
1662 A complete enumeration of the builtins are:
1666 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum);
1667 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum);
1668 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum);
1669 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff);
1670 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff);
1671 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff);
1672 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod);
1673 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod);
1674 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod);
1675 bool __builtin_sadd_overflow (int x, int y, int *sum);
1676 bool __builtin_saddl_overflow (long x, long y, long *sum);
1677 bool __builtin_saddll_overflow(long long x, long long y, long long *sum);
1678 bool __builtin_ssub_overflow (int x, int y, int *diff);
1679 bool __builtin_ssubl_overflow (long x, long y, long *diff);
1680 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff);
1681 bool __builtin_smul_overflow (int x, int y, int *prod);
1682 bool __builtin_smull_overflow (long x, long y, long *prod);
1683 bool __builtin_smulll_overflow(long long x, long long y, long long *prod);
1686 .. _langext-__c11_atomic:
1688 __c11_atomic builtins
1689 ---------------------
1691 Clang provides a set of builtins which are intended to be used to implement
1692 C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the
1693 ``_explicit`` form of the corresponding C11 operation, and are named with a
1694 ``__c11_`` prefix. The supported operations, and the differences from
1695 the corresponding C11 operations, are:
1697 * ``__c11_atomic_init``
1698 * ``__c11_atomic_thread_fence``
1699 * ``__c11_atomic_signal_fence``
1700 * ``__c11_atomic_is_lock_free`` (The argument is the size of the
1701 ``_Atomic(...)`` object, instead of its address)
1702 * ``__c11_atomic_store``
1703 * ``__c11_atomic_load``
1704 * ``__c11_atomic_exchange``
1705 * ``__c11_atomic_compare_exchange_strong``
1706 * ``__c11_atomic_compare_exchange_weak``
1707 * ``__c11_atomic_fetch_add``
1708 * ``__c11_atomic_fetch_sub``
1709 * ``__c11_atomic_fetch_and``
1710 * ``__c11_atomic_fetch_or``
1711 * ``__c11_atomic_fetch_xor``
1713 The macros ``__ATOMIC_RELAXED``, ``__ATOMIC_CONSUME``, ``__ATOMIC_ACQUIRE``,
1714 ``__ATOMIC_RELEASE``, ``__ATOMIC_ACQ_REL``, and ``__ATOMIC_SEQ_CST`` are
1715 provided, with values corresponding to the enumerators of C11's
1716 ``memory_order`` enumeration.
1718 Low-level ARM exclusive memory builtins
1719 ---------------------------------------
1721 Clang provides overloaded builtins giving direct access to the three key ARM
1722 instructions for implementing atomic operations.
1726 T __builtin_arm_ldrex(const volatile T *addr);
1727 T __builtin_arm_ldaex(const volatile T *addr);
1728 int __builtin_arm_strex(T val, volatile T *addr);
1729 int __builtin_arm_stlex(T val, volatile T *addr);
1730 void __builtin_arm_clrex(void);
1732 The types ``T`` currently supported are:
1733 * Integer types with width at most 64 bits (or 128 bits on AArch64).
1734 * Floating-point types
1737 Note that the compiler does not guarantee it will not insert stores which clear
1738 the exclusive monitor in between an ``ldrex`` type operation and its paired
1739 ``strex``. In practice this is only usually a risk when the extra store is on
1740 the same cache line as the variable being modified and Clang will only insert
1741 stack stores on its own, so it is best not to use these operations on variables
1742 with automatic storage duration.
1744 Also, loads and stores may be implicit in code written between the ``ldrex`` and
1745 ``strex``. Clang will not necessarily mitigate the effects of these either, so
1746 care should be exercised.
1748 For these reasons the higher level atomic primitives should be preferred where
1751 Non-standard C++11 Attributes
1752 =============================
1754 Clang's non-standard C++11 attributes live in the ``clang`` attribute
1757 Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which
1758 are accepted with the ``__attribute__((foo))`` syntax are also accepted as
1759 ``[[gnu::foo]]``. This only extends to attributes which are specified by GCC
1760 (see the list of `GCC function attributes
1761 <http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable
1762 attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and
1763 `GCC type attributes
1764 <http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC
1765 implementation, these attributes must appertain to the *declarator-id* in a
1766 declaration, which means they must go either at the start of the declaration or
1767 immediately after the name being declared.
1769 For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and
1770 also applies the GNU ``noreturn`` attribute to ``f``.
1774 [[gnu::unused]] int a, f [[gnu::noreturn]] ();
1776 Target-Specific Extensions
1777 ==========================
1779 Clang supports some language features conditionally on some targets.
1781 ARM/AArch64 Language Extensions
1782 -------------------------------
1784 Memory Barrier Intrinsics
1785 ^^^^^^^^^^^^^^^^^^^^^^^^^
1786 Clang implements the ``__dmb``, ``__dsb`` and ``__isb`` intrinsics as defined
1787 in the `ARM C Language Extensions Release 2.0
1788 <http://infocenter.arm.com/help/topic/com.arm.doc.ihi0053c/IHI0053C_acle_2_0.pdf>`_.
1789 Note that these intrinsics are implemented as motion barriers that block
1790 reordering of memory accesses and side effect instructions. Other instructions
1791 like simple arithmatic may be reordered around the intrinsic. If you expect to
1792 have no reordering at all, use inline assembly instead.
1794 X86/X86-64 Language Extensions
1795 ------------------------------
1797 The X86 backend has these language extensions:
1799 Memory references off the GS segment
1800 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1802 Annotating a pointer with address space #256 causes it to be code generated
1803 relative to the X86 GS segment register, and address space #257 causes it to be
1804 relative to the X86 FS segment. Note that this is a very very low-level
1805 feature that should only be used if you know what you're doing (for example in
1812 #define GS_RELATIVE __attribute__((address_space(256)))
1813 int foo(int GS_RELATIVE *P) {
1817 Which compiles to (on X86-32):
1823 movl %gs:(%eax), %eax
1826 Extensions for Static Analysis
1827 ==============================
1829 Clang supports additional attributes that are useful for documenting program
1830 invariants and rules for static analysis tools, such as the `Clang Static
1831 Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented
1832 in the analyzer's `list of source-level annotations
1833 <http://clang-analyzer.llvm.org/annotations.html>`_.
1836 Extensions for Dynamic Analysis
1837 ===============================
1839 Use ``__has_feature(address_sanitizer)`` to check if the code is being built
1840 with :doc:`AddressSanitizer`.
1842 Use ``__has_feature(thread_sanitizer)`` to check if the code is being built
1843 with :doc:`ThreadSanitizer`.
1845 Use ``__has_feature(memory_sanitizer)`` to check if the code is being built
1846 with :doc:`MemorySanitizer`.
1849 Extensions for selectively disabling optimization
1850 =================================================
1852 Clang provides a mechanism for selectively disabling optimizations in functions
1855 To disable optimizations in a single function definition, the GNU-style or C++11
1856 non-standard attribute ``optnone`` can be used.
1860 // The following functions will not be optimized.
1861 // GNU-style attribute
1862 __attribute__((optnone)) int foo() {
1866 [[clang::optnone]] int bar() {
1870 To facilitate disabling optimization for a range of function definitions, a
1871 range-based pragma is provided. Its syntax is ``#pragma clang optimize``
1872 followed by ``off`` or ``on``.
1874 All function definitions in the region between an ``off`` and the following
1875 ``on`` will be decorated with the ``optnone`` attribute unless doing so would
1876 conflict with explicit attributes already present on the function (e.g. the
1877 ones that control inlining).
1881 #pragma clang optimize off
1882 // This function will be decorated with optnone.
1887 // optnone conflicts with always_inline, so bar() will not be decorated.
1888 __attribute__((always_inline)) int bar() {
1891 #pragma clang optimize on
1893 If no ``on`` is found to close an ``off`` region, the end of the region is the
1894 end of the compilation unit.
1896 Note that a stray ``#pragma clang optimize on`` does not selectively enable
1897 additional optimizations when compiling at low optimization levels. This feature
1898 can only be used to selectively disable optimizations.
1900 The pragma has an effect on functions only at the point of their definition; for
1901 function templates, this means that the state of the pragma at the point of an
1902 instantiation is not necessarily relevant. Consider the following example:
1906 template<typename T> T twice(T t) {
1910 #pragma clang optimize off
1911 template<typename T> T thrice(T t) {
1915 int container(int a, int b) {
1916 return twice(a) + thrice(b);
1918 #pragma clang optimize on
1920 In this example, the definition of the template function ``twice`` is outside
1921 the pragma region, whereas the definition of ``thrice`` is inside the region.
1922 The ``container`` function is also in the region and will not be optimized, but
1923 it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of
1924 these two instantiations, ``twice`` will be optimized (because its definition
1925 was outside the region) and ``thrice`` will not be optimized.
1927 Extensions for loop hint optimizations
1928 ======================================
1930 The ``#pragma clang loop`` directive is used to specify hints for optimizing the
1931 subsequent for, while, do-while, or c++11 range-based for loop. The directive
1932 provides options for vectorization, interleaving, and unrolling. Loop hints can
1933 be specified before any loop and will be ignored if the optimization is not safe
1936 Vectorization and Interleaving
1937 ------------------------------
1939 A vectorized loop performs multiple iterations of the original loop
1940 in parallel using vector instructions. The instruction set of the target
1941 processor determines which vector instructions are available and their vector
1942 widths. This restricts the types of loops that can be vectorized. The vectorizer
1943 automatically determines if the loop is safe and profitable to vectorize. A
1944 vector instruction cost model is used to select the vector width.
1946 Interleaving multiple loop iterations allows modern processors to further
1947 improve instruction-level parallelism (ILP) using advanced hardware features,
1948 such as multiple execution units and out-of-order execution. The vectorizer uses
1949 a cost model that depends on the register pressure and generated code size to
1950 select the interleaving count.
1952 Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled
1953 by ``interleave(enable)``. This is useful when compiling with ``-Os`` to
1954 manually enable vectorization or interleaving.
1958 #pragma clang loop vectorize(enable)
1959 #pragma clang loop interleave(enable)
1964 The vector width is specified by ``vectorize_width(_value_)`` and the interleave
1965 count is specified by ``interleave_count(_value_)``, where
1966 _value_ is a positive integer. This is useful for specifying the optimal
1967 width/count of the set of target architectures supported by your application.
1971 #pragma clang loop vectorize_width(2)
1972 #pragma clang loop interleave_count(2)
1977 Specifying a width/count of 1 disables the optimization, and is equivalent to
1978 ``vectorize(disable)`` or ``interleave(disable)``.
1983 Unrolling a loop reduces the loop control overhead and exposes more
1984 opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling
1985 eliminates the loop and replaces it with an enumerated sequence of loop
1986 iterations. Full unrolling is only possible if the loop trip count is known at
1987 compile time. Partial unrolling replicates the loop body within the loop and
1988 reduces the trip count.
1990 If ``unroll(full)`` is specified the unroller will attempt to fully unroll the
1991 loop if the trip count is known at compile time. If the loop count is not known
1992 or the fully unrolled code size is greater than the limit specified by the
1993 `-pragma-unroll-threshold` command line option the loop will be partially
1994 unrolled subject to the same limit.
1998 #pragma clang loop unroll(full)
2003 The unroll count can be specified explicitly with ``unroll_count(_value_)`` where
2004 _value_ is a positive integer. If this value is greater than the trip count the
2005 loop will be fully unrolled. Otherwise the loop is partially unrolled subject
2006 to the `-pragma-unroll-threshold` limit.
2010 #pragma clang loop unroll_count(8)
2015 Unrolling of a loop can be prevented by specifying ``unroll(disable)``.
2017 Additional Information
2018 ----------------------
2020 For convenience multiple loop hints can be specified on a single line.
2024 #pragma clang loop vectorize_width(4) interleave_count(8)
2029 If an optimization cannot be applied any hints that apply to it will be ignored.
2030 For example, the hint ``vectorize_width(4)`` is ignored if the loop is not
2031 proven safe to vectorize. To identify and diagnose optimization issues use
2032 `-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the
2033 user guide for details.