diff --git a/libcxx/docs/CodingGuidelines.rst b/libcxx/docs/CodingGuidelines.rst index c783a4f2e4e72..4a601dffa87ca 100644 --- a/libcxx/docs/CodingGuidelines.rst +++ b/libcxx/docs/CodingGuidelines.rst @@ -79,9 +79,9 @@ and then check for ``#if _LIBCPP_SOMETHING_ENABLED`` instead of and then checking for ``#ifdef _LIBCPP_SOMETHING_ENABLED``. -This makes it significantly easier to catch missing includes, since Clang and GCC will warn when using and undefined -marco inside an ``#if`` statement when using ``-Wundef``. Some macros in libc++ don't use this style yet, so this only -applies when introducing a new macro. +This makes it significantly easier to catch missing includes: Clang and GCC with ``-Wundef`` enabled will warn +when using an undefined macro inside an ``#if`` statement. Some macros in libc++ don't use this style yet, +so this guideline only applies when introducing a new macro. This is partially enforced by the clang-tidy check ``libcpp-internal-ftms``. @@ -107,9 +107,9 @@ This is enforced by the clang-tidy check ``libcpp-uglify-attributes``. Use C++11 extensions in C++03 code if they simplify the code ============================================================ -libc++ only supports Clang in C++98/03 mode. Clang provides many C++11 features in C++03, making it possible to write a -lot of code in a simpler way than if we were restricted to C++03 features. Some use of extensions is even mandatory, -since libc++ supports move semantics in C++03. +libc++ supports the C++98/03 mode only with the Clang compiler. Clang provides many C++11 features +in C++03, making it possible to write a lot of code in a simpler way than if we were restricted to C++03 features. +Some use of extensions is even mandatory, since libc++ supports move semantics in C++03. Use ``using`` aliases instead of ``typedef`` ============================================ diff --git a/libcxx/docs/Hardening.rst b/libcxx/docs/Hardening.rst index 097ad4b73b126..17808841bd9ec 100644 --- a/libcxx/docs/Hardening.rst +++ b/libcxx/docs/Hardening.rst @@ -32,8 +32,8 @@ modes are: including heuristic checks that might have significant performance overhead as well as internal library assertions. This mode should be used in non-production environments (such as test suites, CI, or local development). - We don’t commit to a particular level of performance in this mode and it’s - *not* intended to be used in production. + We do not commit to a particular level of performance in this mode. + In particular, this mode is *not* intended to be used in production. .. note:: @@ -155,13 +155,13 @@ easier to reason about the high-level semantics of a hardening mode. in the library -- whatever the consequences are, they will happen in the user code. -- ``pedantic`` -- checks preconditions that are imposed by the Standard, but - violating which happens to be benign in libc++. +- ``pedantic`` -- checks preconditions that are imposed by the C++ standard, + but violating which happens to be benign in libc++. - ``semantic-requirement`` -- checks that the given argument satisfies the - semantic requirements imposed by the Standard. Typically, there is no simple - way to completely prove that a semantic requirement is satisfied; thus, this - would often be a heuristic check and it might be quite expensive. + semantic requirements imposed by the C++ standard. Typically, there is no + simple way to completely prove that a semantic requirement is satisfied; + thus, this would often be a heuristic check and it might be quite expensive. - ``internal`` -- checks that internal invariants of the library hold. These assertions don't depend on user input. @@ -239,7 +239,7 @@ Mapping between the hardening modes and the assertion categories .. note:: - The categories enabled by each mode are subject to change and users should not + The categories enabled by each mode are subject to change. Users should not rely on the precise assertions enabled by a mode at a given point in time. However, the library does guarantee to keep the hardening modes stable and to fulfill the semantics documented here. diff --git a/libcxx/docs/ImplementationDefinedBehavior.rst b/libcxx/docs/ImplementationDefinedBehavior.rst index 1f95de77db0eb..62f715a354c00 100644 --- a/libcxx/docs/ImplementationDefinedBehavior.rst +++ b/libcxx/docs/ImplementationDefinedBehavior.rst @@ -4,8 +4,8 @@ Implementation-defined behavior =============================== -Contains the implementation details of the implementation-defined behavior in -libc++. Implementation-defined is mandated to be documented by the Standard. +This document contains the implementation details of the implementation-defined behavior in libc++. +The C++ standard mandates that implementation-defined behavior is documented. .. note: This page is far from complete. @@ -17,7 +17,7 @@ Implementation-defined behavior Updating the Time Zone Database ------------------------------- -The Standard allows implementations to automatically update the +The C++ standard allows implementations to automatically update the *remote time zone database*. Libc++ opts not to do that. Instead calling - ``std::chrono::remote_version()`` will update the version information of the @@ -32,7 +32,7 @@ give them full control over the process. `[ostream.formatted.print]/3 `_ A terminal capable of displaying Unicode -------------------------------------------------------------------------------------------------------------------------- -The Standard specifies that the manner in which a stream is determined to refer +The C++ standard specifies that the manner in which a stream is determined to refer to a terminal capable of displaying Unicode is implementation-defined. This is used for ``std::print`` and similar functions taking an ``ostream&`` argument. @@ -55,9 +55,9 @@ Libc++ determines that a stream is Unicode-capable terminal by: ---------------------------------------------------------------------------------------- Most functions within the Mathematical Special Functions section contain integral indices. -The Standard specifies the result for larger indices as implementation-defined. +The C++ standard specifies the result for larger indices as implementation-defined. Libc++ pursuits reasonable results by choosing the same formulas as for indices below that threshold. -E.g. +E.g., - ``std::hermite(unsigned n, T x)`` for ``n >= 128`` diff --git a/libcxx/docs/Modules.rst b/libcxx/docs/Modules.rst index 352a198f3774d..ebd851fed95fc 100644 --- a/libcxx/docs/Modules.rst +++ b/libcxx/docs/Modules.rst @@ -24,7 +24,7 @@ Overview The module sources are stored in ``.cppm`` files. Modules need to be available as BMIs, which are ``.pcm`` files for Clang. BMIs are not portable, they depend -on the compiler used and its compilation flags. Therefore there needs to be a +on the compiler and the compilation flags used. Therefore there needs to be a way to distribute the ``.cppm`` files to the user and offer a way for them to build and use the ``.pcm`` files. It is expected this will be done by build systems in the future. To aid early adaptor and build system vendors libc++ diff --git a/libcxx/docs/UserDocumentation.rst b/libcxx/docs/UserDocumentation.rst index 4a11a10224ae9..dbacb44735d08 100644 --- a/libcxx/docs/UserDocumentation.rst +++ b/libcxx/docs/UserDocumentation.rst @@ -7,29 +7,29 @@ User documentation .. contents:: :local: -This page contains information about configuration knobs that can be used by -users when they know libc++ is used by their toolchain, and how to use libc++ -when it is not the default library used by their toolchain. It is aimed at -users of libc++: a separate page contains documentation aimed at vendors who -build and ship libc++ as part of their toolchain. +This page contains information for users of libc++: how to use libc++ if it is not +the default library used by the toolchain, and what configuration knobs are available +if libc++ is used by the toolchain. This page is aimed at users of libc++, whereas a +separate page contains documentation aimed at vendors who build and ship libc++ +as part of their toolchain. Using a different version of the C++ Standard ============================================= -Libc++ implements the various versions of the C++ Standard. Changing the version of +Libc++ implements the various versions of the C++ standard. Changing the version of the standard can be done by passing ``-std=c++XY`` to the compiler. Libc++ will -automatically detect what Standard is being used and will provide functionality that -matches that Standard in the library. +automatically detect what standard is being used and will provide functionality that +matches that standard in the library. .. code-block:: bash $ clang++ -std=c++17 test.cpp -Note that using ``-std=c++XY`` with a version of the Standard that has not been ratified +Note that using ``-std=c++XY`` with a version of the standard that has not been ratified yet is considered unstable. While we strive to maintain stability, libc++ may be forced to -make breaking changes to features shipped in a Standard that hasn't been ratified yet. Use -these versions of the Standard at your own risk. +make breaking changes to features shipped in a C++ standard that has not been ratified yet. +Use these versions of the standard at your own risk. Using libc++ when it is not the system default @@ -39,16 +39,16 @@ Usually, libc++ is packaged and shipped by a vendor through some delivery vehicl (operating system distribution, SDK, toolchain, etc) and users don't need to do anything special in order to use the library. -On systems where libc++ is provided but is not the default, Clang provides a flag -called ``-stdlib=`` that can be used to decide which standard library is used. +However, on systems where libc++ is provided but is not the default, Clang can be invoked +with the ``-stdlib=`` flag to select which standard library is used. Using ``-stdlib=libc++`` will select libc++: .. code-block:: bash $ clang++ -stdlib=libc++ test.cpp -On systems where libc++ is the library in use by default such as macOS and FreeBSD, -this flag is not required. +This flag is not required on systems where libc++ is the default standard library, +such as macOS and FreeBSD. Enabling experimental C++ Library features @@ -56,9 +56,9 @@ Enabling experimental C++ Library features Libc++ provides implementations of some experimental features. Experimental features are either Technical Specifications (TSes) or official features that were voted to -the Standard but whose implementation is not complete or stable yet in libc++. Those -are disabled by default because they are neither API nor ABI stable. However, the -``-fexperimental-library`` compiler flag can be defined to turn those features on. +the C++ standard but whose implementation is not complete or stable yet in libc++. +Those are disabled by default because they are neither API nor ABI stable. However, +users can enable the ``-fexperimental-library`` compiler flag to turn those features on. On compilers that do not support the ``-fexperimental-library`` flag (such as GCC), users can define the ``_LIBCPP_ENABLE_EXPERIMENTAL`` macro and manually link against @@ -75,7 +75,7 @@ when ``-fexperimental-library`` is passed: .. note:: Experimental libraries are experimental. * The contents of the ```` headers and the associated static - library will not remain compatible between versions. + library may not remain compatible between versions. * No guarantees of API or ABI stability are provided. * When the standardized version of an experimental feature is implemented, the experimental feature is removed two releases after the non-experimental @@ -94,6 +94,24 @@ enable or disable extended libc++ behavior. only intended to be used by vendors and changing their value from the one provided in your toolchain can lead to unexpected behavior. +**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**: + This macro disables warnings when using deprecated components. For example, + using `std::auto_ptr` when compiling in C++11 mode will normally trigger a + warning saying that `std::auto_ptr` is deprecated. If the macro is defined, + no warning will be emitted. By default, this macro is not defined. + +**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**: + This macro is used to disable all visibility annotations inside libc++. + Defining this macro and then building libc++ with hidden visibility gives a + build of libc++ which does not export any symbols, which can be useful when + building statically for inclusion into another library. + +**_LIBCPP_ENABLE_EXPERIMENTAL**: + This macro enables experimental features. This can be used on compilers that do + not support the ``-fexperimental-library`` flag. When used, users also need to + ensure that the appropriate experimental library (usually ``libc++experimental.a``) + is linked into their program. + **_LIBCPP_ENABLE_THREAD_SAFETY_ANNOTATIONS**: This macro is used to enable -Wthread-safety annotations on libc++'s ``std::mutex`` and ``std::lock_guard``. By default, these annotations are @@ -102,12 +120,6 @@ enable or disable extended libc++ behavior. **_LIBCPP_HARDENING_MODE**: This macro is used to choose the :ref:`hardening mode `. -**_LIBCPP_DISABLE_VISIBILITY_ANNOTATIONS**: - This macro is used to disable all visibility annotations inside libc++. - Defining this macro and then building libc++ with hidden visibility gives a - build of libc++ which does not export any symbols, which can be useful when - building statically for inclusion into another library. - **_LIBCPP_NO_VCRUNTIME**: Microsoft's C and C++ headers are fairly entangled, and some of their C++ headers are fairly hard to avoid. In particular, `vcruntime_new.h` gets pulled @@ -150,18 +162,6 @@ enable or disable extended libc++ behavior. when updating to a newer version of the library, since transitive includes that your code was previously relying on may have been removed. -**_LIBCPP_DISABLE_DEPRECATION_WARNINGS**: - This macro disables warnings when using deprecated components. For example, - using `std::auto_ptr` when compiling in C++11 mode will normally trigger a - warning saying that `std::auto_ptr` is deprecated. If the macro is defined, - no warning will be emitted. By default, this macro is not defined. - -**_LIBCPP_ENABLE_EXPERIMENTAL**: - This macro enables experimental features. This can be used on compilers that do - not support the ``-fexperimental-library`` flag. When used, users also need to - ensure that the appropriate experimental library (usually ``libc++experimental.a``) - is linked into their program. - C++17 Specific Configuration Macros ----------------------------------- **_LIBCPP_ENABLE_CXX17_REMOVED_AUTO_PTR**: @@ -187,13 +187,6 @@ C++17 Specific Configuration Macros C++20 Specific Configuration Macros ----------------------------------- -**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**: - This macro is used to re-enable `uncaught_exception`. - -**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**: - This macro is used to re-enable the function - ``std::shared_ptr<...>::unique()``. - **_LIBCPP_ENABLE_CXX20_REMOVED_BINDER_TYPEDEFS**: This macro is used to re-enable the `argument_type`, `result_type`, `first_argument_type`, and `second_argument_type` members of class @@ -206,6 +199,10 @@ C++20 Specific Configuration Macros **_LIBCPP_ENABLE_CXX20_REMOVED_RAW_STORAGE_ITERATOR**: This macro is used to re-enable `raw_storage_iterator`. +**_LIBCPP_ENABLE_CXX20_REMOVED_SHARED_PTR_UNIQUE**: + This macro is used to re-enable the function + ``std::shared_ptr<...>::unique()``. + **_LIBCPP_ENABLE_CXX20_REMOVED_TEMPORARY_BUFFER**: This macro is used to re-enable `get_temporary_buffer` and `return_temporary_buffer`. @@ -213,10 +210,15 @@ C++20 Specific Configuration Macros This macro is used to re-enable `is_literal_type`, `is_literal_type_v`, `result_of` and `result_of_t`. +**_LIBCPP_ENABLE_CXX20_REMOVED_UNCAUGHT_EXCEPTION**: + This macro is used to re-enable `uncaught_exception`. C++26 Specific Configuration Macros ----------------------------------- +**_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**: + This macro is used to re-enable redundant member of ``allocator::is_always_equal``. + **_LIBCPP_ENABLE_CXX26_REMOVED_CODECVT**: This macro is used to re-enable all named declarations in ````. @@ -224,9 +226,6 @@ C++26 Specific Configuration Macros This macro is used to re-enable the function ``std::basic_string<...>::reserve()``. -**_LIBCPP_ENABLE_CXX26_REMOVED_ALLOCATOR_MEMBERS**: - This macro is used to re-enable redundant member of ``allocator::is_always_equal``. - **_LIBCPP_ENABLE_CXX26_REMOVED_STRSTREAM**: This macro is used to re-enable all named declarations in ````. @@ -237,23 +236,23 @@ C++26 Specific Configuration Macros Libc++ Extensions ================= -This section documents various extensions provided by libc++, how they're -provided, and any information regarding how to use them. +This section documents various extensions provided by libc++ +and any information regarding how to use them. Extended integral type support ------------------------------ -Several platforms support types that are not specified in the Standard, such as -the 128-bit integral types ``__int128_t`` and ``__uint128_t``. As an extension, -libc++ does a best-effort attempt to support these types like other integral -types, by supporting them notably in: +Several platforms support types that are not specified in the C++ standard, +such as the 128-bit integral types ``__int128_t`` and ``__uint128_t``. +As an extension, libc++ does a best-effort attempt to support these types like +other integral types, by supporting them notably in: * ```` * ```` * ```` -* ```` * ```` * ```` +* ```` Additional types supported in random distributions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -272,11 +271,10 @@ The exposition only type ``basic-format-string`` and its typedefs ``format_string``, and ``wformat_string`` in C++23. Libc++ makes these types available in C++20 as an extension. -For padding Unicode strings the ``format`` library relies on the Unicode -Standard. Libc++ retroactively updates the Unicode Standard in older C++ -versions. This allows the library to have better estimates for newly introduced -Unicode code points, without requiring the user to use the latest C++ version -in their code base. +For padding Unicode strings the ``format`` library relies on the Unicode standard. +Libc++ retroactively updates the Unicode standard in older C++ versions. +This allows the library to have better estimates for newly introduced Unicode code points, +without requiring the user to use the latest C++ version in their code base. In C++26 formatting pointers gained a type ``P`` and allows to use zero-padding. These options have been retroactively applied to C++20. @@ -297,8 +295,8 @@ pointer to heap-allocated memory, depending on the length of the string. As of C++20, the constructors are now declared ``constexpr``, which permits strings to be used during constant-evaluation time. In libc++, as in other common implementations, it is also possible to constant-initialize a string object (e.g. via declaring a variable with ``constinit`` or -``constexpr``), but, only if the string is short enough to not require a heap allocation. Reliance -upon this should be discouraged in portable code, as the allowed length differs based on the +``constexpr``), but only if the string is short enough to not require a heap allocation. +Reliance upon this is discouraged in portable code, as the allowed length differs based on the standard-library implementation and also based on whether the platform uses 32-bit or 64-bit pointers. @@ -317,12 +315,15 @@ Turning off ASan annotation in containers ----------------------------------------- ``__asan_annotate_container_with_allocator`` is a customization point to allow users to disable -`Address Sanitizer annotations for containers `_ for specific allocators. This may be necessary for allocators that access allocated memory. +`Address Sanitizer annotations for containers `_ for specific allocators. +This may be necessary for allocators that access allocated memory. This customization point exists only when ``_LIBCPP_HAS_ASAN_CONTAINER_ANNOTATIONS_FOR_ALL_ALLOCATORS`` Feature Test Macro is defined. -For allocators not running destructors, it is also possible to `bulk-unpoison memory `_ instead of disabling annotations altogether. +For allocators not running destructors, it is also possible to `bulk-unpoison memory `_ +instead of disabling annotations altogether. -The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait `_ with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise. +The struct may be specialized for user-defined allocators. It is a `Cpp17UnaryTypeTrait `_ +with a base characteristic of ``true_type`` if the container is allowed to use annotations and ``false_type`` otherwise. The annotations for a ``user_allocator`` can be disabled like this: @@ -371,7 +372,7 @@ locale behave differently than they otherwise do. By default, wide character streams don't convert wide characters but input/output them as is. If a specific locale is imbued, the IO with the underlying stream happens with regular ``char`` elements, which are converted to/from wide characters -according to the locale. Note that this doesn't behave as expected if the +according to the locale. Note that this will not behave as expected if the stream has been set in Unicode mode.