diff options
Diffstat (limited to 'clang/docs/LanguageExtensions.rst')
| -rw-r--r-- | clang/docs/LanguageExtensions.rst | 76 |
1 files changed, 38 insertions, 38 deletions
diff --git a/clang/docs/LanguageExtensions.rst b/clang/docs/LanguageExtensions.rst index bef6e9c1..495f2ab 100644 --- a/clang/docs/LanguageExtensions.rst +++ b/clang/docs/LanguageExtensions.rst @@ -32,7 +32,7 @@ Feature Checking Macros ======================= Language extensions can be very useful, but only if you know you can depend on -them. In order to allow fine-grain features checks, we support three builtin +them. In order to allow fine-grained feature checks, we support three builtin function-like macros. This allows you to directly test for a feature in your code without having to resort to something like autoconf or fragile "compiler version checks". @@ -137,7 +137,7 @@ feature) or 0 if not. They can be used like this: .. _langext-has-feature-back-compat: For backward compatibility, ``__has_feature`` can also be used to test -for support for non-standardized features, i.e. features not prefixed ``c_``, +for support for non-standardized features, i.e., features not prefixed ``c_``, ``cxx_`` or ``objc_``. Another use of ``__has_feature`` is to check for compiler features not related @@ -159,7 +159,7 @@ of ``cxx_rvalue_references``. This function-like macro is available in C++20 by default, and is provided as an extension in earlier language standards. It takes a single argument that is the -name of a double-square-bracket-style attribute. The argument can either be a +name of a double-square-bracket-style attribute. The argument can be either a single identifier or a scoped identifier. If the attribute is supported, a nonzero value is returned. If the attribute is a standards-based attribute, this macro returns a nonzero value based on the year and month in which the attribute @@ -320,7 +320,7 @@ To test for this feature, use ``#if defined(__has_include)``: .. code-block:: c++ - // To avoid problem with non-clang compilers not having this macro. + // To avoid problems with non-clang compilers not having this macro. #if defined(__has_include) #if __has_include("myinclude.h") # include "myinclude.h" @@ -345,7 +345,7 @@ or 0 otherwise: # include_next "myinclude.h" #endif - // To avoid problem with non-clang compilers not having this macro. + // To avoid problems with non-clang compilers not having this macro. #if defined(__has_include_next) #if __has_include_next("myinclude.h") # include_next "myinclude.h" @@ -361,7 +361,7 @@ absolute path is used in the file argument. ----------------- This function-like macro takes a string literal that represents a command line -option for a warning and returns true if that is a valid warning option. +option for a warning and returns ``true`` if that is a valid warning option. .. code-block:: c++ @@ -396,7 +396,7 @@ Builtin Macros file. ``__clang__`` - Defined when compiling with Clang + Defined when compiling with Clang. ``__clang_major__`` Defined to the major marketing version number of Clang (e.g., the 2 in @@ -599,7 +599,7 @@ NEON vector types are created using ``neon_vector_type`` and GCC vector types are created using the ``vector_size(N)`` attribute. The argument ``N`` specifies the number of bytes that will be allocated for an -object of this type. The size has to be multiple of the size of the vector +object of this type. The size has to be a multiple of the size of the vector element type. For example: .. code-block:: c++ @@ -620,7 +620,7 @@ element type. For example: Boolean Vectors --------------- -Clang also supports the ext_vector_type attribute with boolean element types in +Clang also supports the ``ext_vector_type`` attribute with boolean element types in C and C++. For example: .. code-block:: c++ @@ -674,7 +674,7 @@ 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 +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 @@ -725,12 +725,12 @@ address &v[i] no no no [#]_ no no See also :ref:`langext-__builtin_shufflevector`, :ref:`langext-__builtin_convertvector`. -.. [#] ternary operator(?:) has different behaviors depending on condition - operand's vector type. If the condition is a GNU vector (i.e. __vector_size__), +.. [#] ternary operator(?:) has different behaviors depending on the condition + operand's vector type. If the condition is a GNU vector (i.e., ``__vector_size__``), a NEON vector or an SVE vector, it's only available in C++ and uses normal bool conversions (that is, != 0). If it's an extension (OpenCL) vector, it's only available in C and OpenCL C. - And it selects based on signedness of the condition operands (OpenCL v1.1 s6.3.9). + And it selects based on the signedness of the condition operands (OpenCL v1.1 s6.3.9). .. [#] sizeof can only be used on vector length specific SVE types. .. [#] Clang does not allow the address of an element to be taken while GCC allows this. This is intentional for vectors with a boolean element type and @@ -747,7 +747,7 @@ to perform additional operations on certain scalar and vector types. Let ``T`` be one of the following types: * an integer type (as in C23 6.2.5p22), but excluding enumerated types and ``bool`` -* the standard floating types float or double +* the standard floating types ``float`` or ``double`` * a half-precision floating point type, if one is supported on the target * a vector type. @@ -833,7 +833,7 @@ of different sizes and signs is forbidden in binary and ternary builtins. T __builtin_elementwise_canonicalize(T x) return the platform specific canonical encoding floating point types of a floating-point number T __builtin_elementwise_copysign(T x, T y) return the magnitude of x with the sign of y. floating point types - T __builtin_elementwise_fmod(T x, T y) return The floating-point remainder of (x/y) whose sign floating point types + T __builtin_elementwise_fmod(T x, T y) return the floating-point remainder of (x/y) whose sign floating point types matches the sign of x. T __builtin_elementwise_max(T x, T y) return x or y, whichever is larger integer and floating point types For floating point types, follows semantics of maxNum @@ -948,7 +948,7 @@ Let ``VT`` be a vector type and ``ET`` the element type of ``VT``. Each builtin accesses memory according to a provided boolean mask. These are provided as ``__builtin_masked_load`` and ``__builtin_masked_store``. The first -argument is always boolean mask vector. The ``__builtin_masked_load`` builtin +argument is always a boolean mask vector. The ``__builtin_masked_load`` builtin takes an optional third vector argument that will be used for the result of the masked-off lanes. These builtins assume the memory is unaligned, use ``__builtin_assume_aligned`` if alignment is desired. @@ -1109,7 +1109,7 @@ to ``float``; see below for more information on this emulation. ``__fp16`` and ``_Float16`` both use the binary16 format from IEEE 754-2008, which provides a 5-bit exponent and an 11-bit significand -(counting the implicit leading 1). ``__bf16`` uses the `bfloat16 +(including the implicit leading 1). ``__bf16`` uses the `bfloat16 <https://en.wikipedia.org/wiki/Bfloat16_floating-point_format>`_ format, which provides an 8-bit exponent and an 8-bit significand; this is the same exponent range as `float`, just with greatly reduced precision. @@ -1143,7 +1143,7 @@ types with the ``-ffloat16-excess-precision=`` and * ``none``: meaning to perform strict operation-by-operation emulation * ``standard``: meaning that excess precision is permitted under the rules - described in the standard, i.e. never across explicit casts or statements + described in the standard, i.e., never across explicit casts or statements * ``fast``: meaning that excess precision is permitted whenever the optimizer sees an opportunity to avoid truncations; currently this has no effect beyond ``standard`` @@ -1899,7 +1899,7 @@ Type Trait Primitives Type trait primitives are special builtin constant expressions that can be used by the standard C++ library to facilitate or simplify the implementation of -user-facing type traits in the <type_traits> header. +user-facing type traits in the ``<type_traits>`` header. They are not intended to be used directly by user code because they are implementation-defined and subject to change -- as such they're tied closely to @@ -2054,7 +2054,7 @@ The following type trait primitives are supported by Clang. Those traits marked * ``__is_volatile`` (C++, Embarcadero) * ``__reference_binds_to_temporary(T, U)`` (Clang): Determines whether a reference of type ``T`` bound to an expression of type ``U`` would bind to a - materialized temporary object. If ``T`` is not a reference type the result + materialized temporary object. If ``T`` is not a reference type, the result is false. Note this trait will also return false when the initialization of ``T`` from ``U`` is ill-formed. Deprecated, use ``__reference_constructs_from_temporary``. @@ -2182,7 +2182,7 @@ Prior to clang-16, the output may only be used safely when the indirect branches are not taken. Query for this difference with ``__has_extension(gnu_asm_goto_with_outputs_full)``. -When using tied-outputs (i.e. outputs that are inputs and outputs, not just +When using tied-outputs (i.e., outputs that are inputs and outputs, not just outputs) with the `+r` constraint, there is a hidden input that's created before the label, so numeric references to operands must account for that. @@ -2361,7 +2361,7 @@ Loading from a ``__weak`` variable always implicitly retains the loaded value. In non-ARC modes, this retain is normally balanced by an implicit autorelease. This autorelease can be suppressed by performing the load in the receiver position of a ``-retain`` -message send (e.g. ``[weakReference retain]``); note that this performs +message send (e.g., ``[weakReference retain]``); note that this performs only a single retain (the retain done when primitively loading from the weak reference). @@ -2562,7 +2562,7 @@ When a method that's introduced in the OS newer than the target OS is called, a .. code-block:: objc void my_fun(NSSomeClass* var) { - // If fancyNewMethod was added in e.g. macOS 10.12, but the code is + // If fancyNewMethod was added in e.g., macOS 10.12, but the code is // built with -mmacos-version-min=10.11, then this unconditional call // will emit a -Wunguarded-availability warning: [var fancyNewMethod]; @@ -2725,7 +2725,7 @@ correctly in any circumstances. It can be used if: metaprogramming algorithms to be able to specify/detect types generically. - the generated kernel binary does not contain indirect calls because they - are eliminated using compiler optimizations e.g. devirtualization. + are eliminated using compiler optimizations e.g., devirtualization. - the selected target supports the function pointer like functionality e.g. most CPU targets. @@ -2755,12 +2755,12 @@ Extension Specification, section 1.2 <https://www.khronos.org/registry/OpenCL/specs/3.0-unified/html/OpenCL_Ext.html#extensions-overview>`_. This is not conformant behavior and it can only be used portably when the -functions with variadic prototypes do not get generated in binary e.g. the +functions with variadic prototypes do not get generated in binary e.g., the variadic prototype is used to specify a function type with any number of arguments in metaprogramming algorithms in C++ for OpenCL. This extension can also be used when the kernel code is intended for targets -supporting the variadic arguments e.g. majority of CPU targets. +supporting the variadic arguments e.g., majority of CPU targets. **Example of Use**: @@ -5170,8 +5170,8 @@ __builtin_amdgcn_fence ``__builtin_amdgcn_fence`` emits a fence. -* ``unsigned`` atomic ordering, e.g. ``__ATOMIC_ACQUIRE`` -* ``const char *`` synchronization scope, e.g. ``workgroup`` +* ``unsigned`` atomic ordering, e.g., ``__ATOMIC_ACQUIRE`` +* ``const char *`` synchronization scope, e.g., ``workgroup`` * Zero or more ``const char *`` address spaces names. The address spaces arguments must be one of the following string literals: @@ -5205,7 +5205,7 @@ boolean argument as a bit for every lane of the current wave that is currently active (i.e., that is converged with the executing thread), and a 0 bit for every lane that is not active. -The result is uniform, i.e. it is the same in every active thread of the wave. +The result is uniform, i.e., it is the same in every active thread of the wave. __builtin_amdgcn_inverse_ballot_w{32,64} ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -5374,7 +5374,7 @@ followed by ``off`` or ``on``. All function definitions in the region between an ``off`` and the following ``on`` will be decorated with the ``optnone`` attribute unless doing so would -conflict with explicit attributes already present on the function (e.g. the +conflict with explicit attributes already present on the function (e.g., the ones that control inlining). .. code-block:: c++ @@ -5472,12 +5472,12 @@ provides options for vectorization, interleaving, predication, unrolling and distribution. Loop hints can be specified before any loop and will be ignored if the optimization is not safe to apply. -There are loop hints that control transformations (e.g. vectorization, loop +There are loop hints that control transformations (e.g., vectorization, loop unrolling) and there are loop hints that set transformation options (e.g. ``vectorize_width``, ``unroll_count``). Pragmas setting transformation options -imply the transformation is enabled, as if it was enabled via the corresponding -transformation pragma (e.g. ``vectorize(enable)``). If the transformation is -disabled (e.g. ``vectorize(disable)``), that takes precedence over +imply the transformation is enabled, as if it were enabled via the corresponding +transformation pragma (e.g., ``vectorize(enable)``). If the transformation is +disabled (e.g., ``vectorize(disable)``), that takes precedence over transformations option pragmas implying that transformation. Vectorization, Interleaving, and Predication @@ -5704,7 +5704,7 @@ operation when supported by the target. The pragma can take three values: ``on``, ``fast`` and ``off``. The ``on`` option is identical to using ``#pragma STDC FP_CONTRACT(ON)`` and it allows fusion as specified the language standard. The ``fast`` option allows fusion -in cases when the language standard does not make this possible (e.g. across +in cases when the language standard does not make this possible (e.g., across statements in C). .. code-block:: c++ @@ -5859,14 +5859,14 @@ and ``ignore_denormal_mode``, each optionally prefixed with ``no_``. The meaning are as follows: - ``remote_memory`` means atomic operations may be performed on remote - memory, i.e. memory accessed through off-chip interconnects (e.g., PCIe). + memory, i.e., memory accessed through off-chip interconnects (e.g., PCIe). On ROCm platforms using HIP, remote memory refers to memory accessed via PCIe and is subject to specific atomic operation support. See `ROCm PCIe Atomics <https://rocm.docs.amd.com/en/latest/conceptual/ pcie-atomics.html>`_ for further details. Prefixing with ``no_remote_memory`` indicates that atomic operations should not be performed on remote memory. - ``fine_grained_memory`` means atomic operations may be performed on fine-grained - memory, i.e. memory regions that support fine-grained coherence, where updates to + memory, i.e., memory regions that support fine-grained coherence, where updates to memory are visible to other parts of the system even while modifications are ongoing. For example, in HIP, fine-grained coherence ensures that host and device share up-to-date data without explicit synchronization (see @@ -6088,7 +6088,7 @@ match rules are specified after the attribute. The compiler expects an identifier that corresponds to the subject set specifier. The ``apply_to`` specifier is currently the only supported subject set specifier. It allows you to specify match rules that form a subset of the attribute's allowed subject -set, i.e. the compiler doesn't require all of the attribute's subjects. For +set, i.e., the compiler doesn't require all of the attribute's subjects. For example, an attribute like ``[[nodiscard]]`` whose subject set includes ``enum``, ``record`` and ``hasType(functionType)``, requires the presence of at least one of these rules after ``apply_to``: |