Clang Language Extensions

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.

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”.

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:

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.

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:

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.

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 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:

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. 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.

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:

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.

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:

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.

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:

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.

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:

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.

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:

Not all developments systems have the same include files. The __has_include and __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.

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:

To test for this feature, use #if defined(__has_include):

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:

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.

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.

Defined to a string that contains the name of the main input file passed to Clang.

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.

Defined to an integer value that starts at zero and is incremented each time the __COUNTER__ macro is expanded.

Defined to an integral value that is the include depth of the file currently being translated. For the main file, this value is zero.

Defined to the date and time of the last modification of the current source file.

Defined when compiling with Clang

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 Feature Checking Macros.

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 Feature Checking Macros.

Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1).

Defined to a string that captures the Clang marketing version, including the Subversion tag or revision number, e.g., “1.5 (trunk 102332)”.

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.)

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.)

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:

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:

NEON vector types are created using neon_vector_type and neon_polyvector_type attributes. For example:

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:

Clang also supports the ext_vector_type attribute with boolean element types in C and C++. For example:

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 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:

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

>>,