1========================= 2Clang Language Extensions 3========================= 4 5.. contents:: 6 :local: 7 :depth: 1 8 9.. toctree:: 10 :hidden: 11 12 ObjectiveCLiterals 13 BlockLanguageSpec 14 Block-ABI-Apple 15 AutomaticReferenceCounting 16 17Introduction 18============ 19 20This document describes the language extensions provided by Clang. In addition 21to the language extensions listed here, Clang aims to support a broad range of 22GCC extensions. Please see the `GCC manual 23<http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html>`_ for more information on 24these extensions. 25 26.. _langext-feature_check: 27 28Feature Checking Macros 29======================= 30 31Language extensions can be very useful, but only if you know you can depend on 32them. In order to allow fine-grain features checks, we support three builtin 33function-like macros. This allows you to directly test for a feature in your 34code without having to resort to something like autoconf or fragile "compiler 35version checks". 36 37``__has_builtin`` 38----------------- 39 40This function-like macro takes a single identifier argument that is the name of 41a builtin function. It evaluates to 1 if the builtin is supported or 0 if not. 42It can be used like this: 43 44.. code-block:: c++ 45 46 #ifndef __has_builtin // Optional of course. 47 #define __has_builtin(x) 0 // Compatibility with non-clang compilers. 48 #endif 49 50 ... 51 #if __has_builtin(__builtin_trap) 52 __builtin_trap(); 53 #else 54 abort(); 55 #endif 56 ... 57 58.. _langext-__has_feature-__has_extension: 59 60``__has_feature`` and ``__has_extension`` 61----------------------------------------- 62 63These function-like macros take a single identifier argument that is the name 64of a feature. ``__has_feature`` evaluates to 1 if the feature is both 65supported by Clang and standardized in the current language standard or 0 if 66not (but see :ref:`below <langext-has-feature-back-compat>`), while 67``__has_extension`` evaluates to 1 if the feature is supported by Clang in the 68current language (either as a language extension or a standard language 69feature) or 0 if not. They can be used like this: 70 71.. code-block:: c++ 72 73 #ifndef __has_feature // Optional of course. 74 #define __has_feature(x) 0 // Compatibility with non-clang compilers. 75 #endif 76 #ifndef __has_extension 77 #define __has_extension __has_feature // Compatibility with pre-3.0 compilers. 78 #endif 79 80 ... 81 #if __has_feature(cxx_rvalue_references) 82 // This code will only be compiled with the -std=c++11 and -std=gnu++11 83 // options, because rvalue references are only standardized in C++11. 84 #endif 85 86 #if __has_extension(cxx_rvalue_references) 87 // This code will be compiled with the -std=c++11, -std=gnu++11, -std=c++98 88 // and -std=gnu++98 options, because rvalue references are supported as a 89 // language extension in C++98. 90 #endif 91 92.. _langext-has-feature-back-compat: 93 94For backwards compatibility reasons, ``__has_feature`` can also be used to test 95for support for non-standardized features, i.e. features not prefixed ``c_``, 96``cxx_`` or ``objc_``. 97 98Another use of ``__has_feature`` is to check for compiler features not related 99to the language standard, such as e.g. :doc:`AddressSanitizer 100<AddressSanitizer>`. 101 102If the ``-pedantic-errors`` option is given, ``__has_extension`` is equivalent 103to ``__has_feature``. 104 105The feature tag is described along with the language feature below. 106 107The feature name or extension name can also be specified with a preceding and 108following ``__`` (double underscore) to avoid interference from a macro with 109the same name. For instance, ``__cxx_rvalue_references__`` can be used instead 110of ``cxx_rvalue_references``. 111 112``__has_attribute`` 113------------------- 114 115This function-like macro takes a single identifier argument that is the name of 116an attribute. It evaluates to 1 if the attribute is supported by the current 117compilation target, or 0 if not. It can be used like this: 118 119.. code-block:: c++ 120 121 #ifndef __has_attribute // Optional of course. 122 #define __has_attribute(x) 0 // Compatibility with non-clang compilers. 123 #endif 124 125 ... 126 #if __has_attribute(always_inline) 127 #define ALWAYS_INLINE __attribute__((always_inline)) 128 #else 129 #define ALWAYS_INLINE 130 #endif 131 ... 132 133The attribute name can also be specified with a preceding and following ``__`` 134(double underscore) to avoid interference from a macro with the same name. For 135instance, ``__always_inline__`` can be used instead of ``always_inline``. 136 137``__is_identifier`` 138------------------- 139 140This function-like macro takes a single identifier argument that might be either 141a reserved word or a regular identifier. It evaluates to 1 if the argument is just 142a regular identifier and not a reserved word, in the sense that it can then be 143used as the name of a user-defined function or variable. Otherwise it evaluates 144to 0. It can be used like this: 145 146.. code-block:: c++ 147 148 ... 149 #ifdef __is_identifier // Compatibility with non-clang compilers. 150 #if __is_identifier(__wchar_t) 151 typedef wchar_t __wchar_t; 152 #endif 153 #endif 154 155 __wchar_t WideCharacter; 156 ... 157 158Include File Checking Macros 159============================ 160 161Not all developments systems have the same include files. The 162:ref:`langext-__has_include` and :ref:`langext-__has_include_next` macros allow 163you to check for the existence of an include file before doing a possibly 164failing ``#include`` directive. Include file checking macros must be used 165as expressions in ``#if`` or ``#elif`` preprocessing directives. 166 167.. _langext-__has_include: 168 169``__has_include`` 170----------------- 171 172This function-like macro takes a single file name string argument that is the 173name of an include file. It evaluates to 1 if the file can be found using the 174include paths, or 0 otherwise: 175 176.. code-block:: c++ 177 178 // Note the two possible file name string formats. 179 #if __has_include("myinclude.h") && __has_include(<stdint.h>) 180 # include "myinclude.h" 181 #endif 182 183To test for this feature, use ``#if defined(__has_include)``: 184 185.. code-block:: c++ 186 187 // To avoid problem with non-clang compilers not having this macro. 188 #if defined(__has_include) 189 #if __has_include("myinclude.h") 190 # include "myinclude.h" 191 #endif 192 #endif 193 194.. _langext-__has_include_next: 195 196``__has_include_next`` 197---------------------- 198 199This function-like macro takes a single file name string argument that is the 200name of an include file. It is like ``__has_include`` except that it looks for 201the second instance of the given file found in the include paths. It evaluates 202to 1 if the second instance of the file can be found using the include paths, 203or 0 otherwise: 204 205.. code-block:: c++ 206 207 // Note the two possible file name string formats. 208 #if __has_include_next("myinclude.h") && __has_include_next(<stdint.h>) 209 # include_next "myinclude.h" 210 #endif 211 212 // To avoid problem with non-clang compilers not having this macro. 213 #if defined(__has_include_next) 214 #if __has_include_next("myinclude.h") 215 # include_next "myinclude.h" 216 #endif 217 #endif 218 219Note that ``__has_include_next``, like the GNU extension ``#include_next`` 220directive, is intended for use in headers only, and will issue a warning if 221used in the top-level compilation file. A warning will also be issued if an 222absolute path is used in the file argument. 223 224``__has_warning`` 225----------------- 226 227This function-like macro takes a string literal that represents a command line 228option for a warning and returns true if that is a valid warning option. 229 230.. code-block:: c++ 231 232 #if __has_warning("-Wformat") 233 ... 234 #endif 235 236Builtin Macros 237============== 238 239``__BASE_FILE__`` 240 Defined to a string that contains the name of the main input file passed to 241 Clang. 242 243``__COUNTER__`` 244 Defined to an integer value that starts at zero and is incremented each time 245 the ``__COUNTER__`` macro is expanded. 246 247``__INCLUDE_LEVEL__`` 248 Defined to an integral value that is the include depth of the file currently 249 being translated. For the main file, this value is zero. 250 251``__TIMESTAMP__`` 252 Defined to the date and time of the last modification of the current source 253 file. 254 255``__clang__`` 256 Defined when compiling with Clang 257 258``__clang_major__`` 259 Defined to the major marketing version number of Clang (e.g., the 2 in 260 2.0.1). Note that marketing version numbers should not be used to check for 261 language features, as different vendors use different numbering schemes. 262 Instead, use the :ref:`langext-feature_check`. 263 264``__clang_minor__`` 265 Defined to the minor version number of Clang (e.g., the 0 in 2.0.1). Note 266 that marketing version numbers should not be used to check for language 267 features, as different vendors use different numbering schemes. Instead, use 268 the :ref:`langext-feature_check`. 269 270``__clang_patchlevel__`` 271 Defined to the marketing patch level of Clang (e.g., the 1 in 2.0.1). 272 273``__clang_version__`` 274 Defined to a string that captures the Clang marketing version, including the 275 Subversion tag or revision number, e.g., "``1.5 (trunk 102332)``". 276 277.. _langext-vectors: 278 279Vectors and Extended Vectors 280============================ 281 282Supports the GCC, OpenCL, AltiVec and NEON vector extensions. 283 284OpenCL vector types are created using ``ext_vector_type`` attribute. It 285support for ``V.xyzw`` syntax and other tidbits as seen in OpenCL. An example 286is: 287 288.. code-block:: c++ 289 290 typedef float float4 __attribute__((ext_vector_type(4))); 291 typedef float float2 __attribute__((ext_vector_type(2))); 292 293 float4 foo(float2 a, float2 b) { 294 float4 c; 295 c.xz = a; 296 c.yw = b; 297 return c; 298 } 299 300Query for this feature with ``__has_extension(attribute_ext_vector_type)``. 301 302Giving ``-faltivec`` option to clang enables support for AltiVec vector syntax 303and functions. For example: 304 305.. code-block:: c++ 306 307 vector float foo(vector int a) { 308 vector int b; 309 b = vec_add(a, a) + a; 310 return (vector float)b; 311 } 312 313NEON vector types are created using ``neon_vector_type`` and 314``neon_polyvector_type`` attributes. For example: 315 316.. code-block:: c++ 317 318 typedef __attribute__((neon_vector_type(8))) int8_t int8x8_t; 319 typedef __attribute__((neon_polyvector_type(16))) poly8_t poly8x16_t; 320 321 int8x8_t foo(int8x8_t a) { 322 int8x8_t v; 323 v = a; 324 return v; 325 } 326 327Vector Literals 328--------------- 329 330Vector literals can be used to create vectors from a set of scalars, or 331vectors. Either parentheses or braces form can be used. In the parentheses 332form the number of literal values specified must be one, i.e. referring to a 333scalar value, or must match the size of the vector type being created. If a 334single scalar literal value is specified, the scalar literal value will be 335replicated to all the components of the vector type. In the brackets form any 336number of literals can be specified. For example: 337 338.. code-block:: c++ 339 340 typedef int v4si __attribute__((__vector_size__(16))); 341 typedef float float4 __attribute__((ext_vector_type(4))); 342 typedef float float2 __attribute__((ext_vector_type(2))); 343 344 v4si vsi = (v4si){1, 2, 3, 4}; 345 float4 vf = (float4)(1.0f, 2.0f, 3.0f, 4.0f); 346 vector int vi1 = (vector int)(1); // vi1 will be (1, 1, 1, 1). 347 vector int vi2 = (vector int){1}; // vi2 will be (1, 0, 0, 0). 348 vector int vi3 = (vector int)(1, 2); // error 349 vector int vi4 = (vector int){1, 2}; // vi4 will be (1, 2, 0, 0). 350 vector int vi5 = (vector int)(1, 2, 3, 4); 351 float4 vf = (float4)((float2)(1.0f, 2.0f), (float2)(3.0f, 4.0f)); 352 353Vector Operations 354----------------- 355 356The table below shows the support for each operation by vector extension. A 357dash indicates that an operation is not accepted according to a corresponding 358specification. 359 360============================== ====== ======= === ==== 361 Opeator OpenCL AltiVec GCC NEON 362============================== ====== ======= === ==== 363[] yes yes yes -- 364unary operators +, -- yes yes yes -- 365++, -- -- yes yes yes -- 366+,--,*,/,% yes yes yes -- 367bitwise operators &,|,^,~ yes yes yes -- 368>>,<< yes yes yes -- 369!, &&, || no -- -- -- 370==, !=, >, <, >=, <= yes yes -- -- 371= yes yes yes yes 372:? yes -- -- -- 373sizeof yes yes yes yes 374============================== ====== ======= === ==== 375 376See also :ref:`langext-__builtin_shufflevector`. 377 378Messages on ``deprecated`` and ``unavailable`` Attributes 379========================================================= 380 381An optional string message can be added to the ``deprecated`` and 382``unavailable`` attributes. For example: 383 384.. code-block:: c++ 385 386 void explode(void) __attribute__((deprecated("extremely unsafe, use 'combust' instead!!!"))); 387 388If the deprecated or unavailable declaration is used, the message will be 389incorporated into the appropriate diagnostic: 390 391.. code-block:: c++ 392 393 harmless.c:4:3: warning: 'explode' is deprecated: extremely unsafe, use 'combust' instead!!! 394 [-Wdeprecated-declarations] 395 explode(); 396 ^ 397 398Query for this feature with 399``__has_extension(attribute_deprecated_with_message)`` and 400``__has_extension(attribute_unavailable_with_message)``. 401 402Attributes on Enumerators 403========================= 404 405Clang allows attributes to be written on individual enumerators. This allows 406enumerators to be deprecated, made unavailable, etc. The attribute must appear 407after the enumerator name and before any initializer, like so: 408 409.. code-block:: c++ 410 411 enum OperationMode { 412 OM_Invalid, 413 OM_Normal, 414 OM_Terrified __attribute__((deprecated)), 415 OM_AbortOnError __attribute__((deprecated)) = 4 416 }; 417 418Attributes on the ``enum`` declaration do not apply to individual enumerators. 419 420Query for this feature with ``__has_extension(enumerator_attributes)``. 421 422'User-Specified' System Frameworks 423================================== 424 425Clang provides a mechanism by which frameworks can be built in such a way that 426they will always be treated as being "system frameworks", even if they are not 427present in a system framework directory. This can be useful to system 428framework developers who want to be able to test building other applications 429with development builds of their framework, including the manner in which the 430compiler changes warning behavior for system headers. 431 432Framework developers can opt-in to this mechanism by creating a 433"``.system_framework``" file at the top-level of their framework. That is, the 434framework should have contents like: 435 436.. code-block:: none 437 438 .../TestFramework.framework 439 .../TestFramework.framework/.system_framework 440 .../TestFramework.framework/Headers 441 .../TestFramework.framework/Headers/TestFramework.h 442 ... 443 444Clang will treat the presence of this file as an indicator that the framework 445should be treated as a system framework, regardless of how it was found in the 446framework search path. For consistency, we recommend that such files never be 447included in installed versions of the framework. 448 449Checks for Standard Language Features 450===================================== 451 452The ``__has_feature`` macro can be used to query if certain standard language 453features are enabled. The ``__has_extension`` macro can be used to query if 454language features are available as an extension when compiling for a standard 455which does not provide them. The features which can be tested are listed here. 456 457C++98 458----- 459 460The features listed below are part of the C++98 standard. These features are 461enabled by default when compiling C++ code. 462 463C++ exceptions 464^^^^^^^^^^^^^^ 465 466Use ``__has_feature(cxx_exceptions)`` to determine if C++ exceptions have been 467enabled. For example, compiling code with ``-fno-exceptions`` disables C++ 468exceptions. 469 470C++ RTTI 471^^^^^^^^ 472 473Use ``__has_feature(cxx_rtti)`` to determine if C++ RTTI has been enabled. For 474example, compiling code with ``-fno-rtti`` disables the use of RTTI. 475 476C++11 477----- 478 479The features listed below are part of the C++11 standard. As a result, all 480these features are enabled with the ``-std=c++11`` or ``-std=gnu++11`` option 481when compiling C++ code. 482 483C++11 SFINAE includes access control 484^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 485 486Use ``__has_feature(cxx_access_control_sfinae)`` or 487``__has_extension(cxx_access_control_sfinae)`` to determine whether 488access-control errors (e.g., calling a private constructor) are considered to 489be template argument deduction errors (aka SFINAE errors), per `C++ DR1170 490<http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#1170>`_. 491 492C++11 alias templates 493^^^^^^^^^^^^^^^^^^^^^ 494 495Use ``__has_feature(cxx_alias_templates)`` or 496``__has_extension(cxx_alias_templates)`` to determine if support for C++11's 497alias declarations and alias templates is enabled. 498 499C++11 alignment specifiers 500^^^^^^^^^^^^^^^^^^^^^^^^^^ 501 502Use ``__has_feature(cxx_alignas)`` or ``__has_extension(cxx_alignas)`` to 503determine if support for alignment specifiers using ``alignas`` is enabled. 504 505C++11 attributes 506^^^^^^^^^^^^^^^^ 507 508Use ``__has_feature(cxx_attributes)`` or ``__has_extension(cxx_attributes)`` to 509determine if support for attribute parsing with C++11's square bracket notation 510is enabled. 511 512C++11 generalized constant expressions 513^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 514 515Use ``__has_feature(cxx_constexpr)`` to determine if support for generalized 516constant expressions (e.g., ``constexpr``) is enabled. 517 518C++11 ``decltype()`` 519^^^^^^^^^^^^^^^^^^^^ 520 521Use ``__has_feature(cxx_decltype)`` or ``__has_extension(cxx_decltype)`` to 522determine if support for the ``decltype()`` specifier is enabled. C++11's 523``decltype`` does not require type-completeness of a function call expression. 524Use ``__has_feature(cxx_decltype_incomplete_return_types)`` or 525``__has_extension(cxx_decltype_incomplete_return_types)`` to determine if 526support for this feature is enabled. 527 528C++11 default template arguments in function templates 529^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 530 531Use ``__has_feature(cxx_default_function_template_args)`` or 532``__has_extension(cxx_default_function_template_args)`` to determine if support 533for default template arguments in function templates is enabled. 534 535C++11 ``default``\ ed functions 536^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 537 538Use ``__has_feature(cxx_defaulted_functions)`` or 539``__has_extension(cxx_defaulted_functions)`` to determine if support for 540defaulted function definitions (with ``= default``) is enabled. 541 542C++11 delegating constructors 543^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 544 545Use ``__has_feature(cxx_delegating_constructors)`` to determine if support for 546delegating constructors is enabled. 547 548C++11 ``deleted`` functions 549^^^^^^^^^^^^^^^^^^^^^^^^^^^ 550 551Use ``__has_feature(cxx_deleted_functions)`` or 552``__has_extension(cxx_deleted_functions)`` to determine if support for deleted 553function definitions (with ``= delete``) is enabled. 554 555C++11 explicit conversion functions 556^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 557 558Use ``__has_feature(cxx_explicit_conversions)`` to determine if support for 559``explicit`` conversion functions is enabled. 560 561C++11 generalized initializers 562^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 563 564Use ``__has_feature(cxx_generalized_initializers)`` to determine if support for 565generalized initializers (using braced lists and ``std::initializer_list``) is 566enabled. 567 568C++11 implicit move constructors/assignment operators 569^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 570 571Use ``__has_feature(cxx_implicit_moves)`` to determine if Clang will implicitly 572generate move constructors and move assignment operators where needed. 573 574C++11 inheriting constructors 575^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 576 577Use ``__has_feature(cxx_inheriting_constructors)`` to determine if support for 578inheriting constructors is enabled. 579 580C++11 inline namespaces 581^^^^^^^^^^^^^^^^^^^^^^^ 582 583Use ``__has_feature(cxx_inline_namespaces)`` or 584``__has_extension(cxx_inline_namespaces)`` to determine if support for inline 585namespaces is enabled. 586 587C++11 lambdas 588^^^^^^^^^^^^^ 589 590Use ``__has_feature(cxx_lambdas)`` or ``__has_extension(cxx_lambdas)`` to 591determine if support for lambdas is enabled. 592 593C++11 local and unnamed types as template arguments 594^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 595 596Use ``__has_feature(cxx_local_type_template_args)`` or 597``__has_extension(cxx_local_type_template_args)`` to determine if support for 598local and unnamed types as template arguments is enabled. 599 600C++11 noexcept 601^^^^^^^^^^^^^^ 602 603Use ``__has_feature(cxx_noexcept)`` or ``__has_extension(cxx_noexcept)`` to 604determine if support for noexcept exception specifications is enabled. 605 606C++11 in-class non-static data member initialization 607^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 608 609Use ``__has_feature(cxx_nonstatic_member_init)`` to determine whether in-class 610initialization of non-static data members is enabled. 611 612C++11 ``nullptr`` 613^^^^^^^^^^^^^^^^^ 614 615Use ``__has_feature(cxx_nullptr)`` or ``__has_extension(cxx_nullptr)`` to 616determine if support for ``nullptr`` is enabled. 617 618C++11 ``override control`` 619^^^^^^^^^^^^^^^^^^^^^^^^^^ 620 621Use ``__has_feature(cxx_override_control)`` or 622``__has_extension(cxx_override_control)`` to determine if support for the 623override control keywords is enabled. 624 625C++11 reference-qualified functions 626^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 627 628Use ``__has_feature(cxx_reference_qualified_functions)`` or 629``__has_extension(cxx_reference_qualified_functions)`` to determine if support 630for reference-qualified functions (e.g., member functions with ``&`` or ``&&`` 631applied to ``*this``) is enabled. 632 633C++11 range-based ``for`` loop 634^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 635 636Use ``__has_feature(cxx_range_for)`` or ``__has_extension(cxx_range_for)`` to 637determine if support for the range-based for loop is enabled. 638 639C++11 raw string literals 640^^^^^^^^^^^^^^^^^^^^^^^^^ 641 642Use ``__has_feature(cxx_raw_string_literals)`` to determine if support for raw 643string literals (e.g., ``R"x(foo\bar)x"``) is enabled. 644 645C++11 rvalue references 646^^^^^^^^^^^^^^^^^^^^^^^ 647 648Use ``__has_feature(cxx_rvalue_references)`` or 649``__has_extension(cxx_rvalue_references)`` to determine if support for rvalue 650references is enabled. 651 652C++11 ``static_assert()`` 653^^^^^^^^^^^^^^^^^^^^^^^^^ 654 655Use ``__has_feature(cxx_static_assert)`` or 656``__has_extension(cxx_static_assert)`` to determine if support for compile-time 657assertions using ``static_assert`` is enabled. 658 659C++11 ``thread_local`` 660^^^^^^^^^^^^^^^^^^^^^^ 661 662Use ``__has_feature(cxx_thread_local)`` to determine if support for 663``thread_local`` variables is enabled. 664 665C++11 type inference 666^^^^^^^^^^^^^^^^^^^^ 667 668Use ``__has_feature(cxx_auto_type)`` or ``__has_extension(cxx_auto_type)`` to 669determine C++11 type inference is supported using the ``auto`` specifier. If 670this is disabled, ``auto`` will instead be a storage class specifier, as in C 671or C++98. 672 673C++11 strongly typed enumerations 674^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 675 676Use ``__has_feature(cxx_strong_enums)`` or 677``__has_extension(cxx_strong_enums)`` to determine if support for strongly 678typed, scoped enumerations is enabled. 679 680C++11 trailing return type 681^^^^^^^^^^^^^^^^^^^^^^^^^^ 682 683Use ``__has_feature(cxx_trailing_return)`` or 684``__has_extension(cxx_trailing_return)`` to determine if support for the 685alternate function declaration syntax with trailing return type is enabled. 686 687C++11 Unicode string literals 688^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 689 690Use ``__has_feature(cxx_unicode_literals)`` to determine if support for Unicode 691string literals is enabled. 692 693C++11 unrestricted unions 694^^^^^^^^^^^^^^^^^^^^^^^^^ 695 696Use ``__has_feature(cxx_unrestricted_unions)`` to determine if support for 697unrestricted unions is enabled. 698 699C++11 user-defined literals 700^^^^^^^^^^^^^^^^^^^^^^^^^^^ 701 702Use ``__has_feature(cxx_user_literals)`` to determine if support for 703user-defined literals is enabled. 704 705C++11 variadic templates 706^^^^^^^^^^^^^^^^^^^^^^^^ 707 708Use ``__has_feature(cxx_variadic_templates)`` or 709``__has_extension(cxx_variadic_templates)`` to determine if support for 710variadic templates is enabled. 711 712C++1y 713----- 714 715The features listed below are part of the committee draft for the C++1y 716standard. As a result, all these features are enabled with the ``-std=c++1y`` 717or ``-std=gnu++1y`` option when compiling C++ code. 718 719C++1y binary literals 720^^^^^^^^^^^^^^^^^^^^^ 721 722Use ``__has_feature(cxx_binary_literals)`` or 723``__has_extension(cxx_binary_literals)`` to determine whether 724binary literals (for instance, ``0b10010``) are recognized. Clang supports this 725feature as an extension in all language modes. 726 727C++1y contextual conversions 728^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 729 730Use ``__has_feature(cxx_contextual_conversions)`` or 731``__has_extension(cxx_contextual_conversions)`` to determine if the C++1y rules 732are used when performing an implicit conversion for an array bound in a 733*new-expression*, the operand of a *delete-expression*, an integral constant 734expression, or a condition in a ``switch`` statement. 735 736C++1y decltype(auto) 737^^^^^^^^^^^^^^^^^^^^ 738 739Use ``__has_feature(cxx_decltype_auto)`` or 740``__has_extension(cxx_decltype_auto)`` to determine if support 741for the ``decltype(auto)`` placeholder type is enabled. 742 743C++1y default initializers for aggregates 744^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 745 746Use ``__has_feature(cxx_aggregate_nsdmi)`` or 747``__has_extension(cxx_aggregate_nsdmi)`` to determine if support 748for default initializers in aggregate members is enabled. 749 750C++1y generalized lambda capture 751^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 752 753Use ``__has_feature(cxx_init_captures)`` or 754``__has_extension(cxx_init_captures)`` to determine if support for 755lambda captures with explicit initializers is enabled 756(for instance, ``[n(0)] { return ++n; }``). 757 758C++1y generic lambdas 759^^^^^^^^^^^^^^^^^^^^^ 760 761Use ``__has_feature(cxx_generic_lambdas)`` or 762``__has_extension(cxx_generic_lambdas)`` to determine if support for generic 763(polymorphic) lambdas is enabled 764(for instance, ``[] (auto x) { return x + 1; }``). 765 766C++1y relaxed constexpr 767^^^^^^^^^^^^^^^^^^^^^^^ 768 769Use ``__has_feature(cxx_relaxed_constexpr)`` or 770``__has_extension(cxx_relaxed_constexpr)`` to determine if variable 771declarations, local variable modification, and control flow constructs 772are permitted in ``constexpr`` functions. 773 774C++1y return type deduction 775^^^^^^^^^^^^^^^^^^^^^^^^^^^ 776 777Use ``__has_feature(cxx_return_type_deduction)`` or 778``__has_extension(cxx_return_type_deduction)`` to determine if support 779for return type deduction for functions (using ``auto`` as a return type) 780is enabled. 781 782C++1y runtime-sized arrays 783^^^^^^^^^^^^^^^^^^^^^^^^^^ 784 785Use ``__has_feature(cxx_runtime_array)`` or 786``__has_extension(cxx_runtime_array)`` to determine if support 787for arrays of runtime bound (a restricted form of variable-length arrays) 788is enabled. 789Clang's implementation of this feature is incomplete. 790 791C++1y variable templates 792^^^^^^^^^^^^^^^^^^^^^^^^ 793 794Use ``__has_feature(cxx_variable_templates)`` or 795``__has_extension(cxx_variable_templates)`` to determine if support for 796templated variable declarations is enabled. 797 798C11 799--- 800 801The features listed below are part of the C11 standard. As a result, all these 802features are enabled with the ``-std=c11`` or ``-std=gnu11`` option when 803compiling C code. Additionally, because these features are all 804backward-compatible, they are available as extensions in all language modes. 805 806C11 alignment specifiers 807^^^^^^^^^^^^^^^^^^^^^^^^ 808 809Use ``__has_feature(c_alignas)`` or ``__has_extension(c_alignas)`` to determine 810if support for alignment specifiers using ``_Alignas`` is enabled. 811 812C11 atomic operations 813^^^^^^^^^^^^^^^^^^^^^ 814 815Use ``__has_feature(c_atomic)`` or ``__has_extension(c_atomic)`` to determine 816if support for atomic types using ``_Atomic`` is enabled. Clang also provides 817:ref:`a set of builtins <langext-__c11_atomic>` which can be used to implement 818the ``<stdatomic.h>`` operations on ``_Atomic`` types. 819 820C11 generic selections 821^^^^^^^^^^^^^^^^^^^^^^ 822 823Use ``__has_feature(c_generic_selections)`` or 824``__has_extension(c_generic_selections)`` to determine if support for generic 825selections is enabled. 826 827As an extension, the C11 generic selection expression is available in all 828languages supported by Clang. The syntax is the same as that given in the C11 829standard. 830 831In C, type compatibility is decided according to the rules given in the 832appropriate standard, but in C++, which lacks the type compatibility rules used 833in C, types are considered compatible only if they are equivalent. 834 835C11 ``_Static_assert()`` 836^^^^^^^^^^^^^^^^^^^^^^^^ 837 838Use ``__has_feature(c_static_assert)`` or ``__has_extension(c_static_assert)`` 839to determine if support for compile-time assertions using ``_Static_assert`` is 840enabled. 841 842C11 ``_Thread_local`` 843^^^^^^^^^^^^^^^^^^^^^ 844 845Use ``__has_feature(c_thread_local)`` or ``__has_extension(c_thread_local)`` 846to determine if support for ``_Thread_local`` variables is enabled. 847 848Checks for Type Trait Primitives 849================================ 850 851Type trait primitives are special builtin constant expressions that can be used 852by the standard C++ library to facilitate or simplify the implementation of 853user-facing type traits in the <type_traits> header. 854 855They are not intended to be used directly by user code because they are 856implementation-defined and subject to change -- as such they're tied closely to 857the supported set of system headers, currently: 858 859* LLVM's own libc++ 860* GNU libstdc++ 861* The Microsoft standard C++ library 862 863Clang supports the `GNU C++ type traits 864<http://gcc.gnu.org/onlinedocs/gcc/Type-Traits.html>`_ and a subset of the 865`Microsoft Visual C++ Type traits 866<http://msdn.microsoft.com/en-us/library/ms177194(v=VS.100).aspx>`_. 867 868Feature detection is supported only for some of the primitives at present. User 869code should not use these checks because they bear no direct relation to the 870actual set of type traits supported by the C++ standard library. 871 872For type trait ``__X``, ``__has_extension(X)`` indicates the presence of the 873type trait primitive in the compiler. A simplistic usage example as might be 874seen in standard C++ headers follows: 875 876.. code-block:: c++ 877 878 #if __has_extension(is_convertible_to) 879 template<typename From, typename To> 880 struct is_convertible_to { 881 static const bool value = __is_convertible_to(From, To); 882 }; 883 #else 884 // Emulate type trait for compatibility with other compilers. 885 #endif 886 887The following type trait primitives are supported by Clang: 888 889* ``__has_nothrow_assign`` (GNU, Microsoft) 890* ``__has_nothrow_copy`` (GNU, Microsoft) 891* ``__has_nothrow_constructor`` (GNU, Microsoft) 892* ``__has_trivial_assign`` (GNU, Microsoft) 893* ``__has_trivial_copy`` (GNU, Microsoft) 894* ``__has_trivial_constructor`` (GNU, Microsoft) 895* ``__has_trivial_destructor`` (GNU, Microsoft) 896* ``__has_virtual_destructor`` (GNU, Microsoft) 897* ``__is_abstract`` (GNU, Microsoft) 898* ``__is_base_of`` (GNU, Microsoft) 899* ``__is_class`` (GNU, Microsoft) 900* ``__is_convertible_to`` (Microsoft) 901* ``__is_empty`` (GNU, Microsoft) 902* ``__is_enum`` (GNU, Microsoft) 903* ``__is_interface_class`` (Microsoft) 904* ``__is_pod`` (GNU, Microsoft) 905* ``__is_polymorphic`` (GNU, Microsoft) 906* ``__is_union`` (GNU, Microsoft) 907* ``__is_literal(type)``: Determines whether the given type is a literal type 908* ``__is_final``: Determines whether the given type is declared with a 909 ``final`` class-virt-specifier. 910* ``__underlying_type(type)``: Retrieves the underlying type for a given 911 ``enum`` type. This trait is required to implement the C++11 standard 912 library. 913* ``__is_trivially_assignable(totype, fromtype)``: Determines whether a value 914 of type ``totype`` can be assigned to from a value of type ``fromtype`` such 915 that no non-trivial functions are called as part of that assignment. This 916 trait is required to implement the C++11 standard library. 917* ``__is_trivially_constructible(type, argtypes...)``: Determines whether a 918 value of type ``type`` can be direct-initialized with arguments of types 919 ``argtypes...`` such that no non-trivial functions are called as part of 920 that initialization. This trait is required to implement the C++11 standard 921 library. 922* ``__is_destructible`` (MSVC 2013): partially implemented 923* ``__is_nothrow_destructible`` (MSVC 2013): partially implemented 924* ``__is_nothrow_assignable`` (MSVC 2013, clang) 925* ``__is_constructible`` (MSVC 2013, clang) 926* ``__is_nothrow_constructible`` (MSVC 2013, clang) 927 928Blocks 929====== 930 931The syntax and high level language feature description is in 932:doc:`BlockLanguageSpec<BlockLanguageSpec>`. Implementation and ABI details for 933the clang implementation are in :doc:`Block-ABI-Apple<Block-ABI-Apple>`. 934 935Query for this feature with ``__has_extension(blocks)``. 936 937Objective-C Features 938==================== 939 940Related result types 941-------------------- 942 943According to Cocoa conventions, Objective-C methods with certain names 944("``init``", "``alloc``", etc.) always return objects that are an instance of 945the receiving class's type. Such methods are said to have a "related result 946type", meaning that a message send to one of these methods will have the same 947static type as an instance of the receiver class. For example, given the 948following classes: 949 950.. code-block:: objc 951 952 @interface NSObject 953 + (id)alloc; 954 - (id)init; 955 @end 956 957 @interface NSArray : NSObject 958 @end 959 960and this common initialization pattern 961 962.. code-block:: objc 963 964 NSArray *array = [[NSArray alloc] init]; 965 966the type of the expression ``[NSArray alloc]`` is ``NSArray*`` because 967``alloc`` implicitly has a related result type. Similarly, the type of the 968expression ``[[NSArray alloc] init]`` is ``NSArray*``, since ``init`` has a 969related result type and its receiver is known to have the type ``NSArray *``. 970If neither ``alloc`` nor ``init`` had a related result type, the expressions 971would have had type ``id``, as declared in the method signature. 972 973A method with a related result type can be declared by using the type 974``instancetype`` as its result type. ``instancetype`` is a contextual keyword 975that is only permitted in the result type of an Objective-C method, e.g. 976 977.. code-block:: objc 978 979 @interface A 980 + (instancetype)constructAnA; 981 @end 982 983The related result type can also be inferred for some methods. To determine 984whether a method has an inferred related result type, the first word in the 985camel-case selector (e.g., "``init``" in "``initWithObjects``") is considered, 986and the method will have a related result type if its return type is compatible 987with the type of its class and if: 988 989* the first word is "``alloc``" or "``new``", and the method is a class method, 990 or 991 992* the first word is "``autorelease``", "``init``", "``retain``", or "``self``", 993 and the method is an instance method. 994 995If a method with a related result type is overridden by a subclass method, the 996subclass method must also return a type that is compatible with the subclass 997type. For example: 998 999.. code-block:: objc 1000 1001 @interface NSString : NSObject 1002 - (NSUnrelated *)init; // incorrect usage: NSUnrelated is not NSString or a superclass of NSString 1003 @end 1004 1005Related result types only affect the type of a message send or property access 1006via the given method. In all other respects, a method with a related result 1007type is treated the same way as method that returns ``id``. 1008 1009Use ``__has_feature(objc_instancetype)`` to determine whether the 1010``instancetype`` contextual keyword is available. 1011 1012Automatic reference counting 1013---------------------------- 1014 1015Clang provides support for :doc:`automated reference counting 1016<AutomaticReferenceCounting>` in Objective-C, which eliminates the need 1017for manual ``retain``/``release``/``autorelease`` message sends. There are two 1018feature macros associated with automatic reference counting: 1019``__has_feature(objc_arc)`` indicates the availability of automated reference 1020counting in general, while ``__has_feature(objc_arc_weak)`` indicates that 1021automated reference counting also includes support for ``__weak`` pointers to 1022Objective-C objects. 1023 1024.. _objc-fixed-enum: 1025 1026Enumerations with a fixed underlying type 1027----------------------------------------- 1028 1029Clang provides support for C++11 enumerations with a fixed underlying type 1030within Objective-C. For example, one can write an enumeration type as: 1031 1032.. code-block:: c++ 1033 1034 typedef enum : unsigned char { Red, Green, Blue } Color; 1035 1036This specifies that the underlying type, which is used to store the enumeration 1037value, is ``unsigned char``. 1038 1039Use ``__has_feature(objc_fixed_enum)`` to determine whether support for fixed 1040underlying types is available in Objective-C. 1041 1042Interoperability with C++11 lambdas 1043----------------------------------- 1044 1045Clang provides interoperability between C++11 lambdas and blocks-based APIs, by 1046permitting a lambda to be implicitly converted to a block pointer with the 1047corresponding signature. For example, consider an API such as ``NSArray``'s 1048array-sorting method: 1049 1050.. code-block:: objc 1051 1052 - (NSArray *)sortedArrayUsingComparator:(NSComparator)cmptr; 1053 1054``NSComparator`` is simply a typedef for the block pointer ``NSComparisonResult 1055(^)(id, id)``, and parameters of this type are generally provided with block 1056literals as arguments. However, one can also use a C++11 lambda so long as it 1057provides the same signature (in this case, accepting two parameters of type 1058``id`` and returning an ``NSComparisonResult``): 1059 1060.. code-block:: objc 1061 1062 NSArray *array = @[@"string 1", @"string 21", @"string 12", @"String 11", 1063 @"String 02"]; 1064 const NSStringCompareOptions comparisonOptions 1065 = NSCaseInsensitiveSearch | NSNumericSearch | 1066 NSWidthInsensitiveSearch | NSForcedOrderingSearch; 1067 NSLocale *currentLocale = [NSLocale currentLocale]; 1068 NSArray *sorted 1069 = [array sortedArrayUsingComparator:[=](id s1, id s2) -> NSComparisonResult { 1070 NSRange string1Range = NSMakeRange(0, [s1 length]); 1071 return [s1 compare:s2 options:comparisonOptions 1072 range:string1Range locale:currentLocale]; 1073 }]; 1074 NSLog(@"sorted: %@", sorted); 1075 1076This code relies on an implicit conversion from the type of the lambda 1077expression (an unnamed, local class type called the *closure type*) to the 1078corresponding block pointer type. The conversion itself is expressed by a 1079conversion operator in that closure type that produces a block pointer with the 1080same signature as the lambda itself, e.g., 1081 1082.. code-block:: objc 1083 1084 operator NSComparisonResult (^)(id, id)() const; 1085 1086This conversion function returns a new block that simply forwards the two 1087parameters to the lambda object (which it captures by copy), then returns the 1088result. The returned block is first copied (with ``Block_copy``) and then 1089autoreleased. As an optimization, if a lambda expression is immediately 1090converted to a block pointer (as in the first example, above), then the block 1091is not copied and autoreleased: rather, it is given the same lifetime as a 1092block literal written at that point in the program, which avoids the overhead 1093of copying a block to the heap in the common case. 1094 1095The conversion from a lambda to a block pointer is only available in 1096Objective-C++, and not in C++ with blocks, due to its use of Objective-C memory 1097management (autorelease). 1098 1099Object Literals and Subscripting 1100-------------------------------- 1101 1102Clang provides support for :doc:`Object Literals and Subscripting 1103<ObjectiveCLiterals>` in Objective-C, which simplifies common Objective-C 1104programming patterns, makes programs more concise, and improves the safety of 1105container creation. There are several feature macros associated with object 1106literals and subscripting: ``__has_feature(objc_array_literals)`` tests the 1107availability of array literals; ``__has_feature(objc_dictionary_literals)`` 1108tests the availability of dictionary literals; 1109``__has_feature(objc_subscripting)`` tests the availability of object 1110subscripting. 1111 1112Objective-C Autosynthesis of Properties 1113--------------------------------------- 1114 1115Clang provides support for autosynthesis of declared properties. Using this 1116feature, clang provides default synthesis of those properties not declared 1117@dynamic and not having user provided backing getter and setter methods. 1118``__has_feature(objc_default_synthesize_properties)`` checks for availability 1119of this feature in version of clang being used. 1120 1121.. _langext-objc-retain-release: 1122 1123Objective-C retaining behavior attributes 1124----------------------------------------- 1125 1126In Objective-C, functions and methods are generally assumed to follow the 1127`Cocoa Memory Management 1128<http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmRules.html>`_ 1129conventions for ownership of object arguments and 1130return values. However, there are exceptions, and so Clang provides attributes 1131to allow these exceptions to be documented. This are used by ARC and the 1132`static analyzer <http://clang-analyzer.llvm.org>`_ Some exceptions may be 1133better described using the ``objc_method_family`` attribute instead. 1134 1135**Usage**: The ``ns_returns_retained``, ``ns_returns_not_retained``, 1136``ns_returns_autoreleased``, ``cf_returns_retained``, and 1137``cf_returns_not_retained`` attributes can be placed on methods and functions 1138that return Objective-C or CoreFoundation objects. They are commonly placed at 1139the end of a function prototype or method declaration: 1140 1141.. code-block:: objc 1142 1143 id foo() __attribute__((ns_returns_retained)); 1144 1145 - (NSString *)bar:(int)x __attribute__((ns_returns_retained)); 1146 1147The ``*_returns_retained`` attributes specify that the returned object has a +1 1148retain count. The ``*_returns_not_retained`` attributes specify that the return 1149object has a +0 retain count, even if the normal convention for its selector 1150would be +1. ``ns_returns_autoreleased`` specifies that the returned object is 1151+0, but is guaranteed to live at least as long as the next flush of an 1152autorelease pool. 1153 1154**Usage**: The ``ns_consumed`` and ``cf_consumed`` attributes can be placed on 1155an parameter declaration; they specify that the argument is expected to have a 1156+1 retain count, which will be balanced in some way by the function or method. 1157The ``ns_consumes_self`` attribute can only be placed on an Objective-C 1158method; it specifies that the method expects its ``self`` parameter to have a 1159+1 retain count, which it will balance in some way. 1160 1161.. code-block:: objc 1162 1163 void foo(__attribute__((ns_consumed)) NSString *string); 1164 1165 - (void) bar __attribute__((ns_consumes_self)); 1166 - (void) baz:(id) __attribute__((ns_consumed)) x; 1167 1168Further examples of these attributes are available in the static analyzer's `list of annotations for analysis 1169<http://clang-analyzer.llvm.org/annotations.html#cocoa_mem>`_. 1170 1171Query for these features with ``__has_attribute(ns_consumed)``, 1172``__has_attribute(ns_returns_retained)``, etc. 1173 1174 1175Objective-C++ ABI: protocol-qualifier mangling of parameters 1176------------------------------------------------------------ 1177 1178Starting with LLVM 3.4, Clang produces a new mangling for parameters whose 1179type is a qualified-``id`` (e.g., ``id<Foo>``). This mangling allows such 1180parameters to be differentiated from those with the regular unqualified ``id`` 1181type. 1182 1183This was a non-backward compatible mangling change to the ABI. This change 1184allows proper overloading, and also prevents mangling conflicts with template 1185parameters of protocol-qualified type. 1186 1187Query the presence of this new mangling with 1188``__has_feature(objc_protocol_qualifier_mangling)``. 1189 1190.. _langext-overloading: 1191 1192Initializer lists for complex numbers in C 1193========================================== 1194 1195clang supports an extension which allows the following in C: 1196 1197.. code-block:: c++ 1198 1199 #include <math.h> 1200 #include <complex.h> 1201 complex float x = { 1.0f, INFINITY }; // Init to (1, Inf) 1202 1203This construct is useful because there is no way to separately initialize the 1204real and imaginary parts of a complex variable in standard C, given that clang 1205does not support ``_Imaginary``. (Clang also supports the ``__real__`` and 1206``__imag__`` extensions from gcc, which help in some cases, but are not usable 1207in static initializers.) 1208 1209Note that this extension does not allow eliding the braces; the meaning of the 1210following two lines is different: 1211 1212.. code-block:: c++ 1213 1214 complex float x[] = { { 1.0f, 1.0f } }; // [0] = (1, 1) 1215 complex float x[] = { 1.0f, 1.0f }; // [0] = (1, 0), [1] = (1, 0) 1216 1217This extension also works in C++ mode, as far as that goes, but does not apply 1218to the C++ ``std::complex``. (In C++11, list initialization allows the same 1219syntax to be used with ``std::complex`` with the same meaning.) 1220 1221Builtin Functions 1222================= 1223 1224Clang supports a number of builtin library functions with the same syntax as 1225GCC, including things like ``__builtin_nan``, ``__builtin_constant_p``, 1226``__builtin_choose_expr``, ``__builtin_types_compatible_p``, 1227``__sync_fetch_and_add``, etc. In addition to the GCC builtins, Clang supports 1228a number of builtins that GCC does not, which are listed here. 1229 1230Please note that Clang does not and will not support all of the GCC builtins 1231for vector operations. Instead of using builtins, you should use the functions 1232defined in target-specific header files like ``<xmmintrin.h>``, which define 1233portable wrappers for these. Many of the Clang versions of these functions are 1234implemented directly in terms of :ref:`extended vector support 1235<langext-vectors>` instead of builtins, in order to reduce the number of 1236builtins that we need to implement. 1237 1238``__builtin_readcyclecounter`` 1239------------------------------ 1240 1241``__builtin_readcyclecounter`` is used to access the cycle counter register (or 1242a similar low-latency, high-accuracy clock) on those targets that support it. 1243 1244**Syntax**: 1245 1246.. code-block:: c++ 1247 1248 __builtin_readcyclecounter() 1249 1250**Example of Use**: 1251 1252.. code-block:: c++ 1253 1254 unsigned long long t0 = __builtin_readcyclecounter(); 1255 do_something(); 1256 unsigned long long t1 = __builtin_readcyclecounter(); 1257 unsigned long long cycles_to_do_something = t1 - t0; // assuming no overflow 1258 1259**Description**: 1260 1261The ``__builtin_readcyclecounter()`` builtin returns the cycle counter value, 1262which may be either global or process/thread-specific depending on the target. 1263As the backing counters often overflow quickly (on the order of seconds) this 1264should only be used for timing small intervals. When not supported by the 1265target, the return value is always zero. This builtin takes no arguments and 1266produces an unsigned long long result. 1267 1268Query for this feature with ``__has_builtin(__builtin_readcyclecounter)``. Note 1269that even if present, its use may depend on run-time privilege or other OS 1270controlled state. 1271 1272.. _langext-__builtin_shufflevector: 1273 1274``__builtin_shufflevector`` 1275--------------------------- 1276 1277``__builtin_shufflevector`` is used to express generic vector 1278permutation/shuffle/swizzle operations. This builtin is also very important 1279for the implementation of various target-specific header files like 1280``<xmmintrin.h>``. 1281 1282**Syntax**: 1283 1284.. code-block:: c++ 1285 1286 __builtin_shufflevector(vec1, vec2, index1, index2, ...) 1287 1288**Examples**: 1289 1290.. code-block:: c++ 1291 1292 // identity operation - return 4-element vector v1. 1293 __builtin_shufflevector(v1, v1, 0, 1, 2, 3) 1294 1295 // "Splat" element 0 of V1 into a 4-element result. 1296 __builtin_shufflevector(V1, V1, 0, 0, 0, 0) 1297 1298 // Reverse 4-element vector V1. 1299 __builtin_shufflevector(V1, V1, 3, 2, 1, 0) 1300 1301 // Concatenate every other element of 4-element vectors V1 and V2. 1302 __builtin_shufflevector(V1, V2, 0, 2, 4, 6) 1303 1304 // Concatenate every other element of 8-element vectors V1 and V2. 1305 __builtin_shufflevector(V1, V2, 0, 2, 4, 6, 8, 10, 12, 14) 1306 1307 // Shuffle v1 with some elements being undefined 1308 __builtin_shufflevector(v1, v1, 3, -1, 1, -1) 1309 1310**Description**: 1311 1312The first two arguments to ``__builtin_shufflevector`` are vectors that have 1313the same element type. The remaining arguments are a list of integers that 1314specify the elements indices of the first two vectors that should be extracted 1315and returned in a new vector. These element indices are numbered sequentially 1316starting with the first vector, continuing into the second vector. Thus, if 1317``vec1`` is a 4-element vector, index 5 would refer to the second element of 1318``vec2``. An index of -1 can be used to indicate that the corresponding element 1319in the returned vector is a don't care and can be optimized by the backend. 1320 1321The result of ``__builtin_shufflevector`` is a vector with the same element 1322type as ``vec1``/``vec2`` but that has an element count equal to the number of 1323indices specified. 1324 1325Query for this feature with ``__has_builtin(__builtin_shufflevector)``. 1326 1327``__builtin_convertvector`` 1328--------------------------- 1329 1330``__builtin_convertvector`` is used to express generic vector 1331type-conversion operations. The input vector and the output vector 1332type must have the same number of elements. 1333 1334**Syntax**: 1335 1336.. code-block:: c++ 1337 1338 __builtin_convertvector(src_vec, dst_vec_type) 1339 1340**Examples**: 1341 1342.. code-block:: c++ 1343 1344 typedef double vector4double __attribute__((__vector_size__(32))); 1345 typedef float vector4float __attribute__((__vector_size__(16))); 1346 typedef short vector4short __attribute__((__vector_size__(8))); 1347 vector4float vf; vector4short vs; 1348 1349 // convert from a vector of 4 floats to a vector of 4 doubles. 1350 __builtin_convertvector(vf, vector4double) 1351 // equivalent to: 1352 (vector4double) { (double) vf[0], (double) vf[1], (double) vf[2], (double) vf[3] } 1353 1354 // convert from a vector of 4 shorts to a vector of 4 floats. 1355 __builtin_convertvector(vs, vector4float) 1356 // equivalent to: 1357 (vector4float) { (float) vf[0], (float) vf[1], (float) vf[2], (float) vf[3] } 1358 1359**Description**: 1360 1361The first argument to ``__builtin_convertvector`` is a vector, and the second 1362argument is a vector type with the same number of elements as the first 1363argument. 1364 1365The result of ``__builtin_convertvector`` is a vector with the same element 1366type as the second argument, with a value defined in terms of the action of a 1367C-style cast applied to each element of the first argument. 1368 1369Query for this feature with ``__has_builtin(__builtin_convertvector)``. 1370 1371``__builtin_unreachable`` 1372------------------------- 1373 1374``__builtin_unreachable`` is used to indicate that a specific point in the 1375program cannot be reached, even if the compiler might otherwise think it can. 1376This is useful to improve optimization and eliminates certain warnings. For 1377example, without the ``__builtin_unreachable`` in the example below, the 1378compiler assumes that the inline asm can fall through and prints a "function 1379declared '``noreturn``' should not return" warning. 1380 1381**Syntax**: 1382 1383.. code-block:: c++ 1384 1385 __builtin_unreachable() 1386 1387**Example of use**: 1388 1389.. code-block:: c++ 1390 1391 void myabort(void) __attribute__((noreturn)); 1392 void myabort(void) { 1393 asm("int3"); 1394 __builtin_unreachable(); 1395 } 1396 1397**Description**: 1398 1399The ``__builtin_unreachable()`` builtin has completely undefined behavior. 1400Since it has undefined behavior, it is a statement that it is never reached and 1401the optimizer can take advantage of this to produce better code. This builtin 1402takes no arguments and produces a void result. 1403 1404Query for this feature with ``__has_builtin(__builtin_unreachable)``. 1405 1406``__sync_swap`` 1407--------------- 1408 1409``__sync_swap`` is used to atomically swap integers or pointers in memory. 1410 1411**Syntax**: 1412 1413.. code-block:: c++ 1414 1415 type __sync_swap(type *ptr, type value, ...) 1416 1417**Example of Use**: 1418 1419.. code-block:: c++ 1420 1421 int old_value = __sync_swap(&value, new_value); 1422 1423**Description**: 1424 1425The ``__sync_swap()`` builtin extends the existing ``__sync_*()`` family of 1426atomic intrinsics to allow code to atomically swap the current value with the 1427new value. More importantly, it helps developers write more efficient and 1428correct code by avoiding expensive loops around 1429``__sync_bool_compare_and_swap()`` or relying on the platform specific 1430implementation details of ``__sync_lock_test_and_set()``. The 1431``__sync_swap()`` builtin is a full barrier. 1432 1433``__builtin_addressof`` 1434----------------------- 1435 1436``__builtin_addressof`` performs the functionality of the built-in ``&`` 1437operator, ignoring any ``operator&`` overload. This is useful in constant 1438expressions in C++11, where there is no other way to take the address of an 1439object that overloads ``operator&``. 1440 1441**Example of use**: 1442 1443.. code-block:: c++ 1444 1445 template<typename T> constexpr T *addressof(T &value) { 1446 return __builtin_addressof(value); 1447 } 1448 1449``__builtin_operator_new`` and ``__builtin_operator_delete`` 1450------------------------------------------------------------ 1451 1452``__builtin_operator_new`` allocates memory just like a non-placement non-class 1453*new-expression*. This is exactly like directly calling the normal 1454non-placement ``::operator new``, except that it allows certain optimizations 1455that the C++ standard does not permit for a direct function call to 1456``::operator new`` (in particular, removing ``new`` / ``delete`` pairs and 1457merging allocations). 1458 1459Likewise, ``__builtin_operator_delete`` deallocates memory just like a 1460non-class *delete-expression*, and is exactly like directly calling the normal 1461``::operator delete``, except that it permits optimizations. Only the unsized 1462form of ``__builtin_operator_delete`` is currently available. 1463 1464These builtins are intended for use in the implementation of ``std::allocator`` 1465and other similar allocation libraries, and are only available in C++. 1466 1467Multiprecision Arithmetic Builtins 1468---------------------------------- 1469 1470Clang provides a set of builtins which expose multiprecision arithmetic in a 1471manner amenable to C. They all have the following form: 1472 1473.. code-block:: c 1474 1475 unsigned x = ..., y = ..., carryin = ..., carryout; 1476 unsigned sum = __builtin_addc(x, y, carryin, &carryout); 1477 1478Thus one can form a multiprecision addition chain in the following manner: 1479 1480.. code-block:: c 1481 1482 unsigned *x, *y, *z, carryin=0, carryout; 1483 z[0] = __builtin_addc(x[0], y[0], carryin, &carryout); 1484 carryin = carryout; 1485 z[1] = __builtin_addc(x[1], y[1], carryin, &carryout); 1486 carryin = carryout; 1487 z[2] = __builtin_addc(x[2], y[2], carryin, &carryout); 1488 carryin = carryout; 1489 z[3] = __builtin_addc(x[3], y[3], carryin, &carryout); 1490 1491The complete list of builtins are: 1492 1493.. code-block:: c 1494 1495 unsigned char __builtin_addcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 1496 unsigned short __builtin_addcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 1497 unsigned __builtin_addc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 1498 unsigned long __builtin_addcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 1499 unsigned long long __builtin_addcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 1500 unsigned char __builtin_subcb (unsigned char x, unsigned char y, unsigned char carryin, unsigned char *carryout); 1501 unsigned short __builtin_subcs (unsigned short x, unsigned short y, unsigned short carryin, unsigned short *carryout); 1502 unsigned __builtin_subc (unsigned x, unsigned y, unsigned carryin, unsigned *carryout); 1503 unsigned long __builtin_subcl (unsigned long x, unsigned long y, unsigned long carryin, unsigned long *carryout); 1504 unsigned long long __builtin_subcll(unsigned long long x, unsigned long long y, unsigned long long carryin, unsigned long long *carryout); 1505 1506Checked Arithmetic Builtins 1507--------------------------- 1508 1509Clang provides a set of builtins that implement checked arithmetic for security 1510critical applications in a manner that is fast and easily expressable in C. As 1511an example of their usage: 1512 1513.. code-block:: c 1514 1515 errorcode_t security_critical_application(...) { 1516 unsigned x, y, result; 1517 ... 1518 if (__builtin_umul_overflow(x, y, &result)) 1519 return kErrorCodeHackers; 1520 ... 1521 use_multiply(result); 1522 ... 1523 } 1524 1525A complete enumeration of the builtins are: 1526 1527.. code-block:: c 1528 1529 bool __builtin_uadd_overflow (unsigned x, unsigned y, unsigned *sum); 1530 bool __builtin_uaddl_overflow (unsigned long x, unsigned long y, unsigned long *sum); 1531 bool __builtin_uaddll_overflow(unsigned long long x, unsigned long long y, unsigned long long *sum); 1532 bool __builtin_usub_overflow (unsigned x, unsigned y, unsigned *diff); 1533 bool __builtin_usubl_overflow (unsigned long x, unsigned long y, unsigned long *diff); 1534 bool __builtin_usubll_overflow(unsigned long long x, unsigned long long y, unsigned long long *diff); 1535 bool __builtin_umul_overflow (unsigned x, unsigned y, unsigned *prod); 1536 bool __builtin_umull_overflow (unsigned long x, unsigned long y, unsigned long *prod); 1537 bool __builtin_umulll_overflow(unsigned long long x, unsigned long long y, unsigned long long *prod); 1538 bool __builtin_sadd_overflow (int x, int y, int *sum); 1539 bool __builtin_saddl_overflow (long x, long y, long *sum); 1540 bool __builtin_saddll_overflow(long long x, long long y, long long *sum); 1541 bool __builtin_ssub_overflow (int x, int y, int *diff); 1542 bool __builtin_ssubl_overflow (long x, long y, long *diff); 1543 bool __builtin_ssubll_overflow(long long x, long long y, long long *diff); 1544 bool __builtin_smul_overflow (int x, int y, int *prod); 1545 bool __builtin_smull_overflow (long x, long y, long *prod); 1546 bool __builtin_smulll_overflow(long long x, long long y, long long *prod); 1547 1548 1549.. _langext-__c11_atomic: 1550 1551__c11_atomic builtins 1552--------------------- 1553 1554Clang provides a set of builtins which are intended to be used to implement 1555C11's ``<stdatomic.h>`` header. These builtins provide the semantics of the 1556``_explicit`` form of the corresponding C11 operation, and are named with a 1557``__c11_`` prefix. The supported operations are: 1558 1559* ``__c11_atomic_init`` 1560* ``__c11_atomic_thread_fence`` 1561* ``__c11_atomic_signal_fence`` 1562* ``__c11_atomic_is_lock_free`` 1563* ``__c11_atomic_store`` 1564* ``__c11_atomic_load`` 1565* ``__c11_atomic_exchange`` 1566* ``__c11_atomic_compare_exchange_strong`` 1567* ``__c11_atomic_compare_exchange_weak`` 1568* ``__c11_atomic_fetch_add`` 1569* ``__c11_atomic_fetch_sub`` 1570* ``__c11_atomic_fetch_and`` 1571* ``__c11_atomic_fetch_or`` 1572* ``__c11_atomic_fetch_xor`` 1573 1574Low-level ARM exclusive memory builtins 1575--------------------------------------- 1576 1577Clang provides overloaded builtins giving direct access to the three key ARM 1578instructions for implementing atomic operations. 1579 1580.. code-block:: c 1581 1582 T __builtin_arm_ldrex(const volatile T *addr); 1583 T __builtin_arm_ldaex(const volatile T *addr); 1584 int __builtin_arm_strex(T val, volatile T *addr); 1585 int __builtin_arm_stlex(T val, volatile T *addr); 1586 void __builtin_arm_clrex(void); 1587 1588The types ``T`` currently supported are: 1589* Integer types with width at most 64 bits (or 128 bits on AArch64). 1590* Floating-point types 1591* Pointer types. 1592 1593Note that the compiler does not guarantee it will not insert stores which clear 1594the exclusive monitor in between an ``ldrex`` type operation and its paired 1595``strex``. In practice this is only usually a risk when the extra store is on 1596the same cache line as the variable being modified and Clang will only insert 1597stack stores on its own, so it is best not to use these operations on variables 1598with automatic storage duration. 1599 1600Also, loads and stores may be implicit in code written between the ``ldrex`` and 1601``strex``. Clang will not necessarily mitigate the effects of these either, so 1602care should be exercised. 1603 1604For these reasons the higher level atomic primitives should be preferred where 1605possible. 1606 1607Non-standard C++11 Attributes 1608============================= 1609 1610Clang's non-standard C++11 attributes live in the ``clang`` attribute 1611namespace. 1612 1613Clang supports GCC's ``gnu`` attribute namespace. All GCC attributes which 1614are accepted with the ``__attribute__((foo))`` syntax are also accepted as 1615``[[gnu::foo]]``. This only extends to attributes which are specified by GCC 1616(see the list of `GCC function attributes 1617<http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html>`_, `GCC variable 1618attributes <http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html>`_, and 1619`GCC type attributes 1620<http://gcc.gnu.org/onlinedocs/gcc/Type-Attributes.html>`_). As with the GCC 1621implementation, these attributes must appertain to the *declarator-id* in a 1622declaration, which means they must go either at the start of the declaration or 1623immediately after the name being declared. 1624 1625For example, this applies the GNU ``unused`` attribute to ``a`` and ``f``, and 1626also applies the GNU ``noreturn`` attribute to ``f``. 1627 1628.. code-block:: c++ 1629 1630 [[gnu::unused]] int a, f [[gnu::noreturn]] (); 1631 1632Target-Specific Extensions 1633========================== 1634 1635Clang supports some language features conditionally on some targets. 1636 1637X86/X86-64 Language Extensions 1638------------------------------ 1639 1640The X86 backend has these language extensions: 1641 1642Memory references off the GS segment 1643^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1644 1645Annotating a pointer with address space #256 causes it to be code generated 1646relative to the X86 GS segment register, and address space #257 causes it to be 1647relative to the X86 FS segment. Note that this is a very very low-level 1648feature that should only be used if you know what you're doing (for example in 1649an OS kernel). 1650 1651Here is an example: 1652 1653.. code-block:: c++ 1654 1655 #define GS_RELATIVE __attribute__((address_space(256))) 1656 int foo(int GS_RELATIVE *P) { 1657 return *P; 1658 } 1659 1660Which compiles to (on X86-32): 1661 1662.. code-block:: gas 1663 1664 _foo: 1665 movl 4(%esp), %eax 1666 movl %gs:(%eax), %eax 1667 ret 1668 1669Extensions for Static Analysis 1670============================== 1671 1672Clang supports additional attributes that are useful for documenting program 1673invariants and rules for static analysis tools, such as the `Clang Static 1674Analyzer <http://clang-analyzer.llvm.org/>`_. These attributes are documented 1675in the analyzer's `list of source-level annotations 1676<http://clang-analyzer.llvm.org/annotations.html>`_. 1677 1678 1679Extensions for Dynamic Analysis 1680=============================== 1681 1682Use ``__has_feature(address_sanitizer)`` to check if the code is being built 1683with :doc:`AddressSanitizer`. 1684 1685Use ``__has_feature(thread_sanitizer)`` to check if the code is being built 1686with :doc:`ThreadSanitizer`. 1687 1688Use ``__has_feature(memory_sanitizer)`` to check if the code is being built 1689with :doc:`MemorySanitizer`. 1690 1691 1692Extensions for selectively disabling optimization 1693================================================= 1694 1695Clang provides a mechanism for selectively disabling optimizations in functions 1696and methods. 1697 1698To disable optimizations in a single function definition, the GNU-style or C++11 1699non-standard attribute ``optnone`` can be used. 1700 1701.. code-block:: c++ 1702 1703 // The following functions will not be optimized. 1704 // GNU-style attribute 1705 __attribute__((optnone)) int foo() { 1706 // ... code 1707 } 1708 // C++11 attribute 1709 [[clang::optnone]] int bar() { 1710 // ... code 1711 } 1712 1713To facilitate disabling optimization for a range of function definitions, a 1714range-based pragma is provided. Its syntax is ``#pragma clang optimize`` 1715followed by ``off`` or ``on``. 1716 1717All function definitions in the region between an ``off`` and the following 1718``on`` will be decorated with the ``optnone`` attribute unless doing so would 1719conflict with explicit attributes already present on the function (e.g. the 1720ones that control inlining). 1721 1722.. code-block:: c++ 1723 1724 #pragma clang optimize off 1725 // This function will be decorated with optnone. 1726 int foo() { 1727 // ... code 1728 } 1729 1730 // optnone conflicts with always_inline, so bar() will not be decorated. 1731 __attribute__((always_inline)) int bar() { 1732 // ... code 1733 } 1734 #pragma clang optimize on 1735 1736If no ``on`` is found to close an ``off`` region, the end of the region is the 1737end of the compilation unit. 1738 1739Note that a stray ``#pragma clang optimize on`` does not selectively enable 1740additional optimizations when compiling at low optimization levels. This feature 1741can only be used to selectively disable optimizations. 1742 1743The pragma has an effect on functions only at the point of their definition; for 1744function templates, this means that the state of the pragma at the point of an 1745instantiation is not necessarily relevant. Consider the following example: 1746 1747.. code-block:: c++ 1748 1749 template<typename T> T twice(T t) { 1750 return 2 * t; 1751 } 1752 1753 #pragma clang optimize off 1754 template<typename T> T thrice(T t) { 1755 return 3 * t; 1756 } 1757 1758 int container(int a, int b) { 1759 return twice(a) + thrice(b); 1760 } 1761 #pragma clang optimize on 1762 1763In this example, the definition of the template function ``twice`` is outside 1764the pragma region, whereas the definition of ``thrice`` is inside the region. 1765The ``container`` function is also in the region and will not be optimized, but 1766it causes the instantiation of ``twice`` and ``thrice`` with an ``int`` type; of 1767these two instantiations, ``twice`` will be optimized (because its definition 1768was outside the region) and ``thrice`` will not be optimized. 1769 1770Extensions for loop hint optimizations 1771====================================== 1772 1773The ``#pragma clang loop`` directive is used to specify hints for optimizing the 1774subsequent for, while, do-while, or c++11 range-based for loop. The directive 1775provides options for vectorization, interleaving, and unrolling. Loop hints can 1776be specified before any loop and will be ignored if the optimization is not safe 1777to apply. 1778 1779Vectorization and Interleaving 1780------------------------------ 1781 1782A vectorized loop performs multiple iterations of the original loop 1783in parallel using vector instructions. The instruction set of the target 1784processor determines which vector instructions are available and their vector 1785widths. This restricts the types of loops that can be vectorized. The vectorizer 1786automatically determines if the loop is safe and profitable to vectorize. A 1787vector instruction cost model is used to select the vector width. 1788 1789Interleaving multiple loop iterations allows modern processors to further 1790improve instruction-level parallelism (ILP) using advanced hardware features, 1791such as multiple execution units and out-of-order execution. The vectorizer uses 1792a cost model that depends on the register pressure and generated code size to 1793select the interleaving count. 1794 1795Vectorization is enabled by ``vectorize(enable)`` and interleaving is enabled 1796by ``interleave(enable)``. This is useful when compiling with ``-Os`` to 1797manually enable vectorization or interleaving. 1798 1799.. code-block:: c++ 1800 1801 #pragma clang loop vectorize(enable) 1802 #pragma clang loop interleave(enable) 1803 for(...) { 1804 ... 1805 } 1806 1807The vector width is specified by ``vectorize_width(_value_)`` and the interleave 1808count is specified by ``interleave_count(_value_)``, where 1809_value_ is a positive integer. This is useful for specifying the optimal 1810width/count of the set of target architectures supported by your application. 1811 1812.. code-block:: c++ 1813 1814 #pragma clang loop vectorize_width(2) 1815 #pragma clang loop interleave_count(2) 1816 for(...) { 1817 ... 1818 } 1819 1820Specifying a width/count of 1 disables the optimization, and is equivalent to 1821``vectorize(disable)`` or ``interleave(disable)``. 1822 1823Loop Unrolling 1824-------------- 1825 1826Unrolling a loop reduces the loop control overhead and exposes more 1827opportunities for ILP. Loops can be fully or partially unrolled. Full unrolling 1828eliminates the loop and replaces it with an enumerated sequence of loop 1829iterations. Full unrolling is only possible if the loop trip count is known at 1830compile time. Partial unrolling replicates the loop body within the loop and 1831reduces the trip count. 1832 1833If ``unroll(enable)`` is specified the unroller will attempt to fully unroll the 1834loop if the trip count is known at compile time. If the loop count is not known 1835or the fully unrolled code size is greater than the limit specified by the 1836`-pragma-unroll-threshold` command line option the loop will be partially 1837unrolled subject to the same limit. 1838 1839.. code-block:: c++ 1840 1841 #pragma clang loop unroll(enable) 1842 for(...) { 1843 ... 1844 } 1845 1846The unroll count can be specified explicitly with ``unroll_count(_value_)`` where 1847_value_ is a positive integer. If this value is greater than the trip count the 1848loop will be fully unrolled. Otherwise the loop is partially unrolled subject 1849to the `-pragma-unroll-threshold` limit. 1850 1851.. code-block:: c++ 1852 1853 #pragma clang loop unroll_count(8) 1854 for(...) { 1855 ... 1856 } 1857 1858Unrolling of a loop can be prevented by specifying ``unroll(disable)``. 1859 1860Additional Information 1861---------------------- 1862 1863For convenience multiple loop hints can be specified on a single line. 1864 1865.. code-block:: c++ 1866 1867 #pragma clang loop vectorize_width(4) interleave_count(8) 1868 for(...) { 1869 ... 1870 } 1871 1872If an optimization cannot be applied any hints that apply to it will be ignored. 1873For example, the hint ``vectorize_width(4)`` is ignored if the loop is not 1874proven safe to vectorize. To identify and diagnose optimization issues use 1875`-Rpass`, `-Rpass-missed`, and `-Rpass-analysis` command line options. See the 1876user guide for details. 1877