========================= Clang Language Extensions ========================= .. contents:: :local: :depth: 1 .. toctree:: :hidden: ObjectiveCLiterals BlockLanguageSpec Block-ABI-Apple AutomaticReferenceCounting PointerAuthentication 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 `_ 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 ```` 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 `), 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 `. 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 `_ 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() # 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() # 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.) Implementation-defined keywords =============================== __datasizeof ------------ ``__datasizeof`` behaves like ``sizeof``, except that it returns the size of the type ignoring tail padding. _BitInt, _ExtInt ---------------- Clang supports the C23 ``_BitInt(N)`` feature as an extension in older C modes and in C++. This type was previously implemented in Clang with the same semantics, but spelled ``_ExtInt(N)``. This spelling has been deprecated in favor of the standard type. Note: the ABI for ``_BitInt(N)`` is still in the process of being stabilized, so this type should not yet be used in interfaces that require ABI stability. C keywords supported in all language modes ------------------------------------------ Clang supports ``_Alignas``, ``_Alignof``, ``_Atomic``, ``_Complex``, ``_Generic``, ``_Imaginary``, ``_Noreturn``, ``_Static_assert``, ``_Thread_local``, and ``_Float16`` in all language modes with the C semantics. __alignof, __alignof__ ---------------------- ``__alignof`` and ``__alignof__`` return, in contrast to ``_Alignof`` and ``alignof``, the preferred alignment of a type. This may be larger than the required alignment for improved performance. __extension__ ------------- ``__extension__`` suppresses extension diagnostics in the statement it is prepended to. __auto_type ----------- ``__auto_type`` behaves the same as ``auto`` in C++11 but is available in all language modes. __imag, __imag__ ---------------- ``__imag`` and ``__imag__`` can be used to get the imaginary part of a complex value. __real, __real__ ---------------- ``__real`` and ``__real__`` can be used to get the real part of a complex value. __asm, __asm__ -------------- ``__asm`` and ``__asm__`` are alternate spellings for ``asm``, but available in all language modes. __complex, __complex__ ---------------------- ``__complex`` and ``__complex__`` are alternate spellings for ``_Complex``. __const, __const__, __volatile, __volatile__, __restrict, __restrict__ ---------------------------------------------------------------------- These are alternate spellings for their non-underscore counterparts, but are available in all langauge modes. __decltype ---------- ``__decltype`` is an alternate spelling for ``decltype``, but is also available in C++ modes before C++11. __inline, __inline__ -------------------- ``__inline`` and ``__inline__`` are alternate spellings for ``inline``, but are available in all language modes. __nullptr --------- ``__nullptr`` is an alternate spelling for ``nullptr``. It is available in all C and C++ language modes. __signed, __signed__ -------------------- ``__signed`` and ``__signed__`` are alternate spellings for ``signed``. ``__unsigned`` and ``__unsigned__`` are **not** supported. __typeof, __typeof__, __typeof_unqual, __typeof_unqual__ -------------------------------------------------------- ``__typeof`` and ``__typeof__`` are alternate spellings for ``typeof``, but are available in all langauge modes. These spellings result in the operand, retaining all qualifiers. ``__typeof_unqual`` and ``__typeof_unqual__`` are alternate spellings for the C23 ``typeof_unqual`` type specifier, but are available in all language modes. These spellings result in the type of the operand, stripping all qualifiers. __char16_t, __char32_t ---------------------- ``__char16_t`` and ``__char32_t`` are alternate spellings for ``char16_t`` and ``char32_t`` respectively, but are also available in C++ modes before C++11. They are only supported in C++. ``__char8_t`` is not available. .. FIXME: This should list all the keyword extensions .. _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 C23 6.2.5p22), 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. *Vector Size* To determine the number of elements in a vector, use ``__builtin_vectorelements()``. For fixed-sized vectors, e.g., defined via ``__attribute__((vector_size(N)))`` or ARM NEON's vector types (e.g., ``uint16x8_t``), this returns the constant number of elements at compile-time. For scalable vectors, e.g., SVE or RISC-V V, the number of elements is not known at compile-time and is determined at runtime. This builtin can be used, e.g., to increment the loop-counter in vector-type agnostic loops. *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 The integer elementwise intrinsics, including ``__builtin_elementwise_popcount``, ``__builtin_elementwise_bitreverse``, ``__builtin_elementwise_add_sat``, ``__builtin_elementwise_sub_sat`` can be called in a ``constexpr`` context. No implicit promotion of integer types takes place. The mixing of integer types of different sizes and signs is forbidden in binary and ternary builtins. ============================================== ====================================================================== ========================================= 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_tan(T x) return the tangent of x interpreted as an angle in radians floating point types T __builtin_elementwise_asin(T x) return the arcsine of x interpreted as an angle in radians floating point types T __builtin_elementwise_acos(T x) return the arccosine of x interpreted as an angle in radians floating point types T __builtin_elementwise_atan(T x) return the arctangent of x interpreted as an angle in radians floating point types T __builtin_elementwise_atan2(T y, T x) return the arctangent of y/x floating point types T __builtin_elementwise_sinh(T x) return the hyperbolic sine of angle x in radians floating point types T __builtin_elementwise_cosh(T x) return the hyperbolic cosine of angle x in radians floating point types T __builtin_elementwise_tanh(T x) return the hyperbolic tangent of angle x 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_popcount(T x) return the number of 1 bits in x integer types T __builtin_elementwise_pow(T x, T y) return x raised to the power of y floating point types T __builtin_elementwise_bitreverse(T x) return the integer represented after reversing the bits of x integer 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_exp10(T x) returns the base-10 exponential, 10^x, of the specified value floating point types T __builtin_elementwise_sqrt(T x) return the square root of a floating-point number 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 `. 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 `. 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_fmod(T x, T y) return The floating-point remainder of (x/y) whose sign floating point types matches the sign of x. T __builtin_elementwise_max(T x, T y) return x or y, whichever is larger integer and floating point types For floating point types, follows semantics of maxNum in IEEE 754-2008. See `LangRef `_ for the comparison. T __builtin_elementwise_min(T x, T y) return x or y, whichever is smaller integer and floating point types For floating point types, follows semantics of minNum in IEEE 754-2008. See `LangRef `_ for the comparison. T __builtin_elementwise_maxnum(T x, T y) return x or y, whichever is larger. Follows IEEE 754-2008 floating point types semantics (maxNum) with +0.0>-0.0. See `LangRef `_ for the comparison. T __builtin_elementwise_minnum(T x, T y) return x or y, whichever is smaller. Follows IEEE 754-2008 floating point types semantics (minNum) with +0.0>-0.0. See `LangRef `_ for the comparison. 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. T __builtin_elementwise_maximum(T x, T y) return x or y, whichever is larger. Follows IEEE 754-2019 floating point types semantics, see `LangRef `_ for the comparison. T __builtin_elementwise_minimum(T x, T y) return x or y, whichever is smaller. Follows IEEE 754-2019 floating point types semantics, see `LangRef `_ for the comparison. ============================================== ====================================================================== ========================================= *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. These reductions support both fixed-sized and scalable vector types. The integer reduction intrinsics, including ``__builtin_reduce_max``, ``__builtin_reduce_min``, ``__builtin_reduce_add``, ``__builtin_reduce_mul``, ``__builtin_reduce_and``, ``__builtin_reduce_or``, and ``__builtin_reduce_xor``, can be called in a ``constexpr`` context. 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 the largest element of the vector. The floating point result integer and floating point types will always be a number unless all elements of the vector are NaN. ET __builtin_reduce_min(VT a) return the smallest element of the vector. The floating point result integer and floating point types will always be a number unless all elements of the vector are 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 ET __builtin_reduce_maximum(VT a) return the largest element of the vector. Follows IEEE 754-2019 floating point types semantics, see `LangRef `_ for the comparison. ET __builtin_reduce_minimum(VT a) return the smallest element of the vector. Follows IEEE 754-2019 floating point types semantics, see `LangRef `_ for the comparison. ======================================= ====================================================================== ================================== Matrix Types ============ Clang provides an extension for matrix types, which is currently being implemented. See :ref:`the draft specification ` 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 using matrix_4_4 = X __attribute__((matrix_type(4, 4))); void f2() { matrix_5_5 d; matrix_5_5 i; i = (matrix_5_5)d; i = static_cast>(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) * NVPTX (natively) * SPIR (natively) * X86 (if SSE2 is available; natively if AVX512-FP16 is also available) * RISC-V (natively if Zfh or Zhinx is available) * SystemZ (emulated) * ``__bf16`` is supported on the following targets (currently never natively): * 32-bit ARM * 64-bit ARM (AArch64) * RISC-V * 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 `_ 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 `_. 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_``, and are intended to be a portable way to query the supported features of the compiler. See `the C++ status page `_ 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 enabled by default when compiling C++ code. C++ exceptions ^^^^^^^^^^^^^^ Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been enabled. For example, compiling code with ``-fno-exceptions`` disables C++ exceptions. C++ RTTI ^^^^^^^^ Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For example, compiling code with ``-fno-rtti`` disables the use of RTTI. C++11 ----- The features listed below are part of the C++11 standard. As a result, all these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option when compiling C++ code. C++11 SFINAE includes access control ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_access_control_sfinae)`` or ``__has_extension(cxx_access_control_sfinae)`` to determine whether access-control errors (e.g., calling a private constructor) are considered to be template argument deduction errors (aka SFINAE errors), per `C++ DR1170 `_. C++11 alias templates ^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_alias_templates)`` or ``__has_extension(cxx_alias_templates)`` to determine if support for C++11's alias declarations and alias templates is enabled. C++11 alignment specifiers ^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to determine if support for alignment specifiers using ``alignas`` is enabled. Use ``__has_feature(cxx_alignof)`` or ``__has_extension(cxx_alignof)`` to determine if support for the ``alignof`` keyword is enabled. C++11 attributes ^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to determine if support for attribute parsing with C++11's square bracket notation is enabled. C++11 generalized constant expressions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized constant expressions (e.g., ``constexpr``) is enabled. C++11 ``decltype()`` ^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to determine if support for the ``decltype()`` specifier is enabled. C++11's ``decltype`` does not require type-completeness of a function call expression. Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or ``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if support for this feature is enabled. C++11 default template arguments in function templates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_default_function_template_args)`` or ``__has_extension(cxx_default_function_template_args)`` to determine if support for default template arguments in function templates is enabled. C++11 ``default``\ ed functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_defaulted_functions)`` or ``__has_extension(cxx_defaulted_functions)`` to determine if support for defaulted function definitions (with ``= default``) is enabled. C++11 delegating constructors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for delegating constructors is enabled. C++11 ``deleted`` functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_deleted_functions)`` or ``__has_extension(cxx_deleted_functions)`` to determine if support for deleted function definitions (with ``= delete``) is enabled. C++11 explicit conversion functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for ``explicit`` conversion functions is enabled. C++11 generalized initializers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for generalized initializers (using braced lists and ``std::initializer_list``) is enabled. C++11 implicit move constructors/assignment operators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly generate move constructors and move assignment operators where needed. C++11 inheriting constructors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for inheriting constructors is enabled. C++11 inline namespaces ^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_inline_namespaces)`` or ``__has_extension(cxx_inline_namespaces)`` to determine if support for inline namespaces is enabled. C++11 lambdas ^^^^^^^^^^^^^ Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to determine if support for lambdas is enabled. C++11 local and unnamed types as template arguments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_local_type_template_args)`` or ``__has_extension(cxx_local_type_template_args)`` to determine if support for local and unnamed types as template arguments is enabled. C++11 noexcept ^^^^^^^^^^^^^^ Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to determine if support for noexcept exception specifications is enabled. C++11 in-class non-static data member initialization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class initialization of non-static data members is enabled. C++11 ``nullptr`` ^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to determine if support for ``nullptr`` is enabled. C++11 ``override control`` ^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_override_control)`` or ``__has_extension(cxx_override_control)`` to determine if support for the override control keywords is enabled. C++11 reference-qualified functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_reference_qualified_functions)`` or ``__has_extension(cxx_reference_qualified_functions)`` to determine if support for reference-qualified functions (e.g., member functions with ``&`` or ``&&`` applied to ``*this``) is enabled. C++11 range-based ``for`` loop ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to determine if support for the range-based for loop is enabled. C++11 raw string literals ^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw string literals (e.g., ``R"x(foo\bar)x"``) is enabled. C++11 rvalue references ^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_rvalue_references)`` or ``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue references is enabled. C++11 ``static_assert()`` ^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_static_assert)`` or ``__has_extension(cxx_static_assert)`` to determine if support for compile-time assertions using ``static_assert`` is enabled. C++11 ``thread_local`` ^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_thread_local)`` to determine if support for ``thread_local`` variables is enabled. C++11 type inference ^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to determine C++11 type inference is supported using the ``auto`` specifier. If this is disabled, ``auto`` will instead be a storage class specifier, as in C or C++98. C++11 strongly typed enumerations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_strong_enums)`` or ``__has_extension(cxx_strong_enums)`` to determine if support for strongly typed, scoped enumerations is enabled. C++11 trailing return type ^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_trailing_return)`` or ``__has_extension(cxx_trailing_return)`` to determine if support for the alternate function declaration syntax with trailing return type is enabled. C++11 Unicode string literals ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode string literals is enabled. C++11 unrestricted unions ^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for unrestricted unions is enabled. C++11 user-defined literals ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_user_literals)`` to determine if support for user-defined literals is enabled. C++11 variadic templates ^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_variadic_templates)`` or ``__has_extension(cxx_variadic_templates)`` to determine if support for variadic templates is enabled. C++14 ----- The features listed below are part of the C++14 standard. As a result, all these features are enabled with the ``-std=C++14`` or ``-std=gnu++14`` option when compiling C++ code. C++14 binary literals ^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_binary_literals)`` or ``__has_extension(cxx_binary_literals)`` to determine whether binary literals (for instance, ``0b10010``) are recognized. Clang supports this feature as an extension in all language modes. C++14 contextual conversions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_contextual_conversions)`` or ``__has_extension(cxx_contextual_conversions)`` to determine if the C++14 rules are used when performing an implicit conversion for an array bound in a *new-expression*, the operand of a *delete-expression*, an integral constant expression, or a condition in a ``switch`` statement. C++14 decltype(auto) ^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_decltype_auto)`` or ``__has_extension(cxx_decltype_auto)`` to determine if support for the ``decltype(auto)`` placeholder type is enabled. C++14 default initializers for aggregates ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_aggregate_nsdmi)`` or ``__has_extension(cxx_aggregate_nsdmi)`` to determine if support for default initializers in aggregate members is enabled. C++14 digit separators ^^^^^^^^^^^^^^^^^^^^^^ Use ``__cpp_digit_separators`` to determine if support for digit separators using single quotes (for instance, ``10'000``) is enabled. At this time, there is no corresponding ``__has_feature`` name C++14 generalized lambda capture ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_init_captures)`` or ``__has_extension(cxx_init_captures)`` to determine if support for lambda captures with explicit initializers is enabled (for instance, ``[n(0)] { return ++n; }``). C++14 generic lambdas ^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_generic_lambdas)`` or ``__has_extension(cxx_generic_lambdas)`` to determine if support for generic (polymorphic) lambdas is enabled (for instance, ``[] (auto x) { return x + 1; }``). C++14 relaxed constexpr ^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_relaxed_constexpr)`` or ``__has_extension(cxx_relaxed_constexpr)`` to determine if variable declarations, local variable modification, and control flow constructs are permitted in ``constexpr`` functions. C++14 return type deduction ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_return_type_deduction)`` or ``__has_extension(cxx_return_type_deduction)`` to determine if support for return type deduction for functions (using ``auto`` as a return type) is enabled. C++14 runtime-sized arrays ^^^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_runtime_array)`` or ``__has_extension(cxx_runtime_array)`` to determine if support for arrays of runtime bound (a restricted form of variable-length arrays) is enabled. Clang's implementation of this feature is incomplete. C++14 variable templates ^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(cxx_variable_templates)`` or ``__has_extension(cxx_variable_templates)`` to determine if support for templated variable declarations is enabled. C11 --- The features listed below are part of the C11 standard. As a result, all these features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when compiling C code. Additionally, because these features are all backward-compatible, they are available as extensions in all language modes. C11 alignment specifiers ^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine if support for alignment specifiers using ``_Alignas`` is enabled. Use ``__has_feature(c_alignof)`` or ``__has_extension(c_alignof)`` to determine if support for the ``_Alignof`` keyword is enabled. C11 atomic operations ^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine if support for atomic types using ``_Atomic`` is enabled. Clang also provides :ref:`a set of builtins ` which can be used to implement the ```` operations on ``_Atomic`` types. Use ``__has_include()`` to determine if C11's ```` header is available. Clang will use the system's ```` header when one is available, and will otherwise use its own. When using its own, implementations of the atomic operations are provided as macros. In the cases where C11 also requires a real function, this header provides only the declaration of that function (along with a shadowing macro implementation), and you must link to a library which provides a definition of the function if you use it instead of the macro. C11 generic selections ^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(c_generic_selections)`` or ``__has_extension(c_generic_selections)`` to determine if support for generic selections is enabled. As an extension, the C11 generic selection expression is available in all languages supported by Clang. The syntax is the same as that given in the C11 standard. In C, type compatibility is decided according to the rules given in the appropriate standard, but in C++, which lacks the type compatibility rules used in C, types are considered compatible only if they are equivalent. Clang also supports an extended form of ``_Generic`` with a controlling type rather than a controlling expression. Unlike with a controlling expression, a controlling type argument does not undergo any conversions and thus is suitable for use when trying to match qualified types, incomplete types, or function types. Variable-length array types lack the necessary compile-time information to resolve which association they match with and thus are not allowed as a controlling type argument. Use ``__has_extension(c_generic_selection_with_controlling_type)`` to determine if support for this extension is enabled. C11 ``_Static_assert()`` ^^^^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)`` to determine if support for compile-time assertions using ``_Static_assert`` is enabled. C11 ``_Thread_local`` ^^^^^^^^^^^^^^^^^^^^^ Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)`` to determine if support for ``_Thread_local`` variables is enabled. C2y --- The features listed below are part of the C2y standard. As a result, all these features are enabled with the ``-std=c2y`` or ``-std=gnu2y`` option when compiling C code. C2y ``_Countof`` ^^^^^^^^^^^^^^^^ Use ``__has_feature(c_countof)`` (in C2y or later mode) or ``__has_extension(c_countof)`` (in C23 or earlier mode) to determine if support for the ``_Countof`` operator is enabled. This feature is not available in C++ mode. Modules ------- Use ``__has_feature(modules)`` to determine if Modules have been enabled. For example, compiling code with ``-fmodules`` enables the use of Modules. More information could be found `here `_. Language Extensions Back-ported to Previous Standards ===================================================== ============================================= ================================ ============= ============= Feature Feature Test Macro Introduced In Backported To ============================================= ================================ ============= ============= variadic templates __cpp_variadic_templates C++11 C++03 Alias templates __cpp_alias_templates C++11 C++03 Non-static data member initializers __cpp_nsdmi C++11 C++03 Range-based ``for`` loop __cpp_range_based_for C++11 C++03 RValue references __cpp_rvalue_references C++11 C++03 Attributes __cpp_attributes C++11 C++03 Lambdas __cpp_lambdas C++11 C++03 Generalized lambda captures __cpp_init_captures C++14 C++03 Generic lambda expressions __cpp_generic_lambdas C++14 C++03 variable templates __cpp_variable_templates C++14 C++03 Binary literals __cpp_binary_literals C++14 C++03 Relaxed constexpr __cpp_constexpr C++14 C++11 Static assert with no message __cpp_static_assert >= 201411L C++17 C++11 Pack expansion in generalized lambda-capture __cpp_init_captures C++17 C++03 ``if constexpr`` __cpp_if_constexpr C++17 C++11 fold expressions __cpp_fold_expressions C++17 C++03 Lambda capture of \*this by value __cpp_capture_star_this C++17 C++03 Attributes on enums __cpp_enumerator_attributes C++17 C++03 Guaranteed copy elision __cpp_guaranteed_copy_elision C++17 C++03 Hexadecimal floating literals __cpp_hex_float C++17 C++03 ``inline`` variables __cpp_inline_variables C++17 C++03 Attributes on namespaces __cpp_namespace_attributes C++17 C++11 Structured bindings __cpp_structured_bindings C++17 C++03 template template arguments __cpp_template_template_args C++17 C++03 Familiar template syntax for generic lambdas __cpp_generic_lambdas C++20 C++03 ``static operator[]`` __cpp_multidimensional_subscript C++20 C++03 Designated initializers __cpp_designated_initializers C++20 C++03 Conditional ``explicit`` __cpp_conditional_explicit C++20 C++03 ``using enum`` __cpp_using_enum C++20 C++03 ``if consteval`` __cpp_if_consteval C++23 C++20 ``static operator()`` __cpp_static_call_operator C++23 C++03 Attributes on Lambda-Expressions C++23 C++11 Attributes on Structured Bindings __cpp_structured_bindings C++26 C++03 Packs in Structured Bindings __cpp_structured_bindings C++26 C++03 Structured binding declaration as a condition __cpp_structured_bindings C++26 C++98 Static assert with user-generated message __cpp_static_assert >= 202306L C++26 C++11 Pack Indexing __cpp_pack_indexing C++26 C++03 ``= delete ("should have a reason");`` __cpp_deleted_function C++26 C++03 Variadic Friends __cpp_variadic_friend C++26 C++03 --------------------------------------------- -------------------------------- ------------- ------------- Designated initializers (N494) C99 C89 Array & element qualification (N2607) C23 C89 Attributes (N2335) C23 C89 ``#embed`` (N3017) C23 C89, C++ Octal literals prefixed with ``0o`` or ``0O`` C2y C89, C++ ``_Countof`` (N3369, N3469) C2y C89 ============================================= ================================ ============= ============= Builtin type aliases ==================== Clang provides a few builtin aliases to improve the throughput of certain metaprogramming facilities. __builtin_common_type --------------------- .. code-block:: c++ template