pw_polyfill/docs.rst

.. _module-pw_polyfill:

===========
pw_polyfill
===========
The ``pw_polyfill`` module backports new C++ features to C++14.

------------------------------------------------
Backport new C++ features to older C++ standards
------------------------------------------------
The main purpose of ``pw_polyfill`` is to bring new C++ library and language
features to older C++ standards. No additional ``#include`` statements are
required to use these features; simply write code assuming that the features are
available. This implicit feature backporting is provided through the
``overrides`` library in the ``pw_polyfill`` module. GN automatically adds this
library as a dependency in ``pw_source_set``.

``pw_polyfill`` backports C++ library features by wrapping the standard C++ and
C headers. The wrapper headers include the original header using
`#include_next <https://gcc.gnu.org/onlinedocs/cpp/Wrapper-Headers.html>`_, then
add missing features. The backported features are only defined if they aren't
provided by the standard header, so ``pw_polyfill`` is safe to use when
compiling with any standard C++14 or newer.

The wrapper headers are in ``public_overrides``. These are provided through the
following libraries:

* ``pw_polyfill:cstddef``
* ``pw_polyfill:iterator``
* ``pw_polyfill:span``

The GN build automatically adds dependencies on the ``<span>`` header. To apply
other overrides, add dependencies as needed. In Bazel or CMake, overrides are
not applied automatically, so depend on the targets you need such as
``//pw_polyfill:span`` or ``pw_polyfill.span``.

Backported features
===================

.. list-table::

  * - **Header**
    - **Feature**
    - **Feature test macro**
    - **Module**
    - **Polyfill header**
    - **Polyfill name**
  * - ``<array>``
    - ``std::to_array``
    - ``__cpp_lib_to_array``
    - :ref:`module-pw_containers`
    - ``pw_containers/to_array.h``
    - ``pw::containers::to_array``
  * - ``<bit>``
    - ``std::endian``
    - ``__cpp_lib_endian``
    - :ref:`module-pw_bytes`
    - ``pw_bytes/bit.h``
    - ``pw::endian``
  * - ``<cstdlib>``
    - ``std::byte``
    - ``__cpp_lib_byte``
    - pw_polyfill
    - ``<cstdlib>``
    - ``std::byte``
  * - ``<iterator>``
    - ``std::data``, ``std::size``
    - ``__cpp_lib_nonmember_container_access``
    - pw_polyfill
    - ``<iterator>``
    - ``std::data``, ``std::size``
  * - ``<span>``
    - ``std::span``
    - ``__cpp_lib_span``
    - pw_polyfill
    - ``<span>``
    - ``std::span``

----------------------------------------------------
Adapt code to compile with different versions of C++
----------------------------------------------------
``pw_polyfill`` provides features for adapting to different C++ standards when
``pw_polyfill:overrides``'s automatic backporting is insufficient.

C++ standard macro
==================
``pw_polyfill/standard.h`` provides a macro for checking if a C++ standard is
supported.

.. c:macro:: PW_CXX_STANDARD_IS_SUPPORTED(standard)

   Evaluates true if the provided C++ standard (98, 11, 14, 17, 20) is supported
   by the compiler. This is a simpler, cleaner alternative to checking the value
   of the ``__cplusplus`` macro.

Language feature macros
=======================
``pw_polyfill/language_feature_macros.h`` provides macros for adapting code to
work with or without newer language features

======================  ================================  ========================================  ==========================
Macro                   Feature                           Description                               Feature test macro
======================  ================================  ========================================  ==========================
PW_INLINE_VARIABLE      inline variables                  inline if supported by the compiler       __cpp_inline_variables
PW_CONSTEXPR_CPP20      constexpr in C++20                constexpr if compiling for C++20          __cplusplus >= 202002L
PW_CONSTEVAL            consteval                         consteval if supported by the compiler    __cpp_consteval
PW_CONSTINIT            constinit                         constinit in clang and GCC 10+            __cpp_constinit
======================  ================================  ========================================  ==========================

In GN, Bazel, or CMake, depend on ``$dir_pw_polyfill``, ``//pw_polyfill``,
or ``pw_polyfill``, respectively, to access these features. In other build
systems, add ``pw_polyfill/standard_library_public`` and
``pw_polyfill/public_overrides`` as include paths.

-------------
Compatibility
-------------
C++14

Zephyr
======
To enable ``pw_polyfill`` for Zephyr add ``CONFIG_PIGWEED_POLYFILL=y`` to the
project's configuration. Similarly, to enable ``pw_polyfill.overrides``, add
``CONFIG_PIGWEED_POLYFILL_OVERRIDES=y`` to the project's configuration.