| .. _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:bit`` |
| * ``pw_polyfill:cstddef`` |
| * ``pw_polyfill:iterator`` |
| * ``pw_polyfill:span`` |
| |
| The GN build automatically adds dependencies on the ``<bit>`` and ``<span>`` |
| headers. 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 |
| =================== |
| ================== ================================ ================ ======================================== ============= |
| Header Feature Level of support Feature test macro Implicit dep? |
| ================== ================================ ================ ======================================== ============= |
| <bit> std::endian full __cpp_lib_endian GN |
| <cstdlib> std::byte full __cpp_lib_byte ❌ |
| <iterator> std::data, std::size full __cpp_lib_nonmember_container_access ❌ |
| <span> std::span no std::ranges __cpp_lib_span GN |
| ================== ================================ ================ ======================================== ============= |
| |
| ---------------------------------------------------- |
| 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. |