From dbe13110f59f48b4dbb7552b3ac2935acdeece7f Mon Sep 17 00:00:00 2001 From: Dimitry Andric Date: Sat, 14 Apr 2012 14:01:31 +0000 Subject: Vendor import of clang trunk r154661: http://llvm.org/svn/llvm-project/cfe/trunk@r154661 --- docs/LanguageExtensions.html | 660 ++++++++++++++++++++++++++++++++++--------- 1 file changed, 529 insertions(+), 131 deletions(-) (limited to 'docs/LanguageExtensions.html') diff --git a/docs/LanguageExtensions.html b/docs/LanguageExtensions.html index c4a8047f1f48..68f0afc1ffa5 100644 --- a/docs/LanguageExtensions.html +++ b/docs/LanguageExtensions.html @@ -11,6 +11,7 @@ td { vertical-align: top; } + th { background-color: #ffddaa; } @@ -29,54 +30,59 @@
  • Vectors and Extended Vectors
  • Messages on deprecated and unavailable attributes
  • Attributes on enumerators
  • +
  • 'User-Specified' System Frameworks
  • +
  • Availability attribute
  • Checks for Standard Language Features
  • +
  • C11 alignment specifiers
  • +
  • C11 atomic operations
  • +
  • C11 generic selections
  • +
  • C11 _Static_assert()
  • + +
  • Checks for Type Traits
  • Blocks
  • Objective-C Features @@ -84,6 +90,8 @@
  • Related result types
  • Automatic reference counting
  • Enumerations with a fixed underlying type
  • +
  • Interoperability with C++11 lambdas
  • +
  • Object Literals and Subscripting
  • Function Overloading in C
  • @@ -101,7 +109,12 @@
  • Static Analysis-Specific Extensions
  • -
  • Thread Safety Annotation Checking
  • +
  • Dynamic Analysis-Specific Extensions + +
  • +
  • Thread Safety Annotation Checking +
  • @@ -192,12 +206,12 @@ language feature) or 0 if not. They can be used like this:

    ... #if __has_feature(cxx_rvalue_references) -// This code will only be compiled with the -std=c++0x and -std=gnu++0x -// options, because rvalue references are only standardized in C++0x. +// 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++0x, -std=gnu++0x, -std=c++98 +// 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 @@ -209,11 +223,21 @@ language feature) or 0 if not. They can be used like this:

    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.

    +

    __has_attribute

    @@ -238,6 +262,11 @@ 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.

    +

    Include File Checking Macros

    @@ -346,30 +375,36 @@ is used in the file argument.

    Defined when compiling with Clang
    __clang_major__
    -
    Defined to the major version number of Clang (e.g., the 2 in - 2.0.1).
    +
    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.
    __clang_minor__
    Defined to the minor version number of Clang (e.g., the 0 in - 2.0.1).
    + 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.
    __clang_patchlevel__
    -
    Defined to the patch level of Clang (e.g., the 1 in 2.0.1).
    +
    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 version, including - the Subversion tag or revision number, e.g., "1.5 (trunk - 102332)".
    +
    Defined to a string that captures the Clang marketing version, including + the Subversion tag or revision number, e.g., "1.5 (trunk 102332)".

    Vectors and Extended Vectors

    -

    Supports the GCC vector extensions, plus some stuff like V[1].

    +

    Supports the GCC, OpenCL, AltiVec and NEON vector extensions.

    -

    Also supports ext_vector, which additionally support for V.xyzw -syntax and other tidbits as seen in OpenCL. An example is:

    +

    OpenCL vector types are created using ext_vector_type attribute. It +support for V.xyzw syntax and other tidbits as seen in OpenCL. An +example is:

    @@ -385,7 +420,161 @@ float4 foo(float2 a, float2 b) {
     
    -

    Query for this feature with __has_extension(attribute_ext_vector_type).

    +

    Query for this feature with +__has_extension(attribute_ext_vector_type).

    + +

    Giving -faltivec option to clang enables support for AltiVec vector +syntax and functions. For example:

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

    + +
    +
    +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;
    +}
    +
    +
    + + +

    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:

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

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    OperatorOpenCLAltiVecGCCNEON
    []yesyesyes-
    unary operators +, -yesyesyes-
    ++, --yesyes--
    +, -, *, /, %yesyesyes-
    bitwise operators &, |, ^, ~yesyesyes-
    >>, <<yesyesyes-
    !, &&,||no---
    ==,!=, >, <, >=, <=yesyes--
    =yesyesyesyes
    :?yes---
    sizeofyesyesyesyes

    See also __builtin_shufflevector.

    @@ -404,7 +593,8 @@ and unavailable attributes. For example:

    will be incorporated into the appropriate diagnostic:

    -
    harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! [-Wdeprecated-declarations]
    +
    harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!!
    +      [-Wdeprecated-declarations]
       explode();
       ^
    @@ -437,233 +627,334 @@ individual enumerators.

    Query for this feature with __has_extension(enumerator_attributes).

    -

    Checks for Standard Language Features

    +

    'User-Specified' System Frameworks

    -

    The __has_feature macro can be used to query if certain standard language features are -enabled. Those features are listed here.

    +

    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.

    -

    C++ exceptions

    +

    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:

    -

    Use __has_feature(cxx_exceptions) to determine if C++ exceptions have been enabled. For -example, compiling code with -fexceptions enables C++ exceptions.

    +
    + .../TestFramework.framework
    + .../TestFramework.framework/.system_framework
    + .../TestFramework.framework/Headers
    + .../TestFramework.framework/Headers/TestFramework.h
    + ...
    +
    -

    C++ RTTI

    +

    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.

    -

    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.

    + +

    Availability attribute

    + +

    Clang introduces the availability attribute, which can +be placed on declarations to describe the lifecycle of that +declaration relative to operating system versions. Consider the function declaration for a hypothetical function f:

    + +
    +void f(void) __attribute__((availability(macosx,introduced=10.4,deprecated=10.6,obsoleted=10.7)));
    +
    + +

    The availability attribute states that f was introduced in Mac OS X 10.4, deprecated in Mac OS X 10.6, and obsoleted in Mac OS X 10.7. This information is used by Clang to determine when it is safe to use f: for example, if Clang is instructed to compile code for Mac OS X 10.5, a call to f() succeeds. If Clang is instructed to compile code for Mac OS X 10.6, the call succeeds but Clang emits a warning specifying that the function is deprecated. Finally, if Clang is instructed to compile code for Mac OS X 10.7, the call fails because f() is no longer available.

    + +

    The availablility attribute is a comma-separated list starting with the platform name and then including clauses specifying important milestones in the declaration's lifetime (in any order) along with additional information. Those clauses can be:

    + +
    +
    introduced=version
    +
    The first version in which this declaration was introduced.
    + +
    deprecated=version
    +
    The first version in which this declaration was deprecated, meaning that users should migrate away from this API.
    + +
    obsoleted=version
    +
    The first version in which this declaration was obsoleted, meaning that it was removed completely and can no longer be used.
    + +
    unavailable
    +
    This declaration is never available on this platform.
    + +
    message=string-literal
    +
    Additional message text that Clang will provide when emitting a warning or error about use of a deprecated or obsoleted declaration. Useful to direct users to replacement APIs.
    +
    + +

    Multiple availability attributes can be placed on a declaration, which may correspond to different platforms. Only the availability attribute with the platform corresponding to the target platform will be used; any others will be ignored. If no availability attribute specifies availability for the current target platform, the availability attributes are ignored. Supported platforms are:

    + +
    +
    ios
    +
    Apple's iOS operating system. The minimum deployment target is specified by the -mios-version-min=version or -miphoneos-version-min=version command-line arguments.
    + +
    macosx
    +
    Apple's Mac OS X operating system. The minimum deployment target is specified by the -mmacosx-version-min=version command-line argument.
    +
    + +

    A declaration can be used even when deploying back to a platform +version prior to when the declaration was introduced. When this +happens, the declaration is weakly +linked, as if the weak_import attribute were added to the declaration. A weakly-linked declaration may or may not be present a run-time, and a program can determine whether the declaration is present by checking whether the address of that declaration is non-NULL.

    -

    Checks for Upcoming Standard Language Features

    +

    Checks for Standard Language Features

    -

    The __has_feature or __has_extension macros can be used -to query if certain upcoming standard language features are enabled. Those -features are listed here. Features that are not yet implemented will be -noted.

    +

    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.

    + +

    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

    -

    C++0x

    +

    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

    -

    The features listed below are slated for inclusion in the upcoming -C++0x standard. As a result, all these features are enabled -with the -std=c++0x option when compiling C++ code.

    +

    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++0x SFINAE includes access control

    +

    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++0x alias templates

    +

    C++11 alias templates

    Use __has_feature(cxx_alias_templates) or __has_extension(cxx_alias_templates) to determine if support for -C++0x's alias declarations and alias templates is enabled.

    +C++11's alias declarations and alias templates is enabled.

    -

    C++0x alignment specifiers

    +

    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.

    -

    C++0x attributes

    +

    C++11 attributes

    Use __has_feature(cxx_attributes) or __has_extension(cxx_attributes) to determine if support for attribute -parsing with C++0x's square bracket notation is enabled.

    +parsing with C++11's square bracket notation is enabled.

    -

    C++0x generalized constant expressions

    +

    C++11 generalized constant expressions

    Use __has_feature(cxx_constexpr) to determine if support for generalized constant expressions (e.g., constexpr) is -enabled. Clang does not currently implement this feature.

    +enabled.

    -

    C++0x decltype()

    +

    C++11 decltype()

    Use __has_feature(cxx_decltype) or __has_extension(cxx_decltype) to determine if support for the -decltype() specifier is enabled.

    +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++0x default template arguments in function templates

    +

    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++0x delegating constructors

    +

    C++11 defaulted 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++0x deleted functions

    +

    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++0x explicit conversion functions

    +

    C++11 explicit conversion functions

    Use __has_feature(cxx_explicit_conversions) to determine if support for explicit conversion functions is enabled.

    -

    C++0x generalized initializers

    +

    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. Clang does not currently implement -this feature.

    +std::initializer_list) is enabled.

    -

    C++0x implicit move constructors/assignment operators

    +

    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++0x inheriting constructors

    +

    C++11 inheriting constructors

    Use __has_feature(cxx_inheriting_constructors) to determine if support for inheriting constructors is enabled. Clang does not currently implement this feature.

    -

    C++0x inline namespaces

    +

    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++0x lambdas

    +

    C++11 lambdas

    Use __has_feature(cxx_lambdas) or __has_extension(cxx_lambdas) to determine if support for lambdas -is enabled. Clang does not currently implement this feature.

    +is enabled.

    + +

    C++11 local and unnamed types as template arguments

    -

    C++0x noexcept

    +

    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++0x in-class non-static data member initialization

    +

    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++0x nullptr

    +

    C++11 nullptr

    Use __has_feature(cxx_nullptr) or __has_extension(cxx_nullptr) to determine if support for nullptr is enabled.

    -

    C++0x override control

    +

    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++0x reference-qualified functions

    +

    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++0x range-based for loop

    +

    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++0x raw string literals

    -

    Use __has_feature(cxx_raw_string_literals) to determine if support for raw string literals (e.g., R"foo\bar") 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++0x rvalue references

    +

    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++0x static_assert()

    +

    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++0x type inference

    +

    C++11 type inference

    Use __has_feature(cxx_auto_type) or -__has_extension(cxx_auto_type) to determine C++0x type inference is +__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++0x strongly typed enumerations

    +

    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++0x trailing return type

    +

    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++0x Unicode string literals

    +

    C++11 Unicode string literals

    Use __has_feature(cxx_unicode_literals) to determine if support for Unicode string literals is enabled.

    -

    C++0x unrestricted unions

    +

    C++11 unrestricted unions

    -

    Use __has_feature(cxx_unrestricted_unions) to determine if support for unrestricted unions is enabled. Clang does not currently support this feature.

    +

    Use __has_feature(cxx_unrestricted_unions) to determine if support for unrestricted unions is enabled.

    -

    C++0x user-defined literals

    +

    C++11 user-defined literals

    -

    Use __has_feature(cxx_user_literals) to determine if support for user-defined literals is enabled. Clang does not currently support this feature.

    +

    Use __has_feature(cxx_user_literals) to determine if support for user-defined literals is enabled.

    -

    C++0x variadic templates

    +

    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.

    -

    C1X

    +

    C11

    -

    The features listed below are slated for inclusion in the upcoming -C1X standard. As a result, all these features are enabled -with the -std=c1x option when compiling C code.

    +

    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.

    -

    C1X alignment specifiers

    +

    C11 alignment specifiers

    Use __has_feature(c_alignas) or __has_extension(c_alignas) to determine if support for alignment specifiers using _Alignas is enabled.

    -

    C1X generic selections

    +

    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 a set of builtins which can be +used to implement the <stdatomic.h> operations on _Atomic +types.

    + +

    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 C1X generic selection expression is available in all +

    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 -C1X draft standard.

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

    -

    C1X _Static_assert()

    +

    C11 _Static_assert()

    Use __has_feature(c_static_assert) or __has_extension(c_static_assert) to determine if support for @@ -707,7 +998,10 @@ struct is_convertible_to {

  • __is_polymorphic (GNU, Microsoft)
  • __is_union (GNU, Microsoft)
  • __is_literal(type): Determines whether the given type is a literal type
  • -
  • __underlying_type(type): Retrieves the underlying type for a given enum type. This trait is required to implement the C++0x standard library.
  • +
  • __is_final: Determines whether the given type is declared with a final class-virt-specifier.
  • +
  • __underlying_type(type): Retrieves the underlying type for a given enum type. This trait is required to implement the C++11 standard library.
  • +
  • __is_trivially_assignable(totype, fromtype): Determines whether a value of type totype can be assigned to from a value of type fromtype such that no non-trivial functions are called as part of that assignment. This trait is required to implement the C++11 standard library.
  • +
  • __is_trivially_constructible(type, argtypes...): Determines whether a value of type type can be direct-initialized with arguments of types argtypes... such that no non-trivial functions are called as part of that initialization. This trait is required to implement the C++11 standard library.
  • @@ -771,7 +1065,7 @@ an Objective-C method, e.g.

    The related result type can also be inferred for some methods. To determine whether a method has an inferred related result type, the first word in the camel-case selector (e.g., "init" in "initWithObjects") is -considered, and the method will a related result type if its return +considered, and the method will have a related result type if its return type is compatible with the type of its class and if